# Build an app

Give your reviewer, CI provider or agent platform its own bot account, install it on repositories, and act through short-lived installation tokens.

## What an app is

An app is an outside tool with its own account on Sailfork. When someone installs it on their account or their organization, it can read and write the repositories they chose, as itself: its comments, reviews and presence carry the app's handle, not the person's.

- **A bot account.** Every app has one. Its handle is the app's slug, so `@tide-bot` mentions and `/tide-bot` links work, and nobody can sign up with that name. The bot never signs in: it has no password, session, SSH key or personal token.
- **Installations.** An app reaches nothing until a person installs it on their own account or an organization owner installs it on the organization, on every repository or only the ones they pick.
- **Installation tokens.** The app trades its client secret for a token that lasts an hour and reaches only one installation's repositories.

## Create an app

Create it with a personal [token](https://status.sailfork.com/docs/tokens) that has the `user` scope, or from a signed-in browser. Add `"org": "<handle>"` to have an organization you own own it.

```sh
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Tide Bot","slug":"tide-bot","description":"Reviews pull requests.","permissions":{"contents":"read","pulls":"write"},"public":true}' \
  https://status.sailfork.com/api/apps
```

The answer holds the app and its `clientSecret`, which starts with `sfapp_`. Store it now: Sailfork keeps only a hash and shows it once. `POST /api/apps/{slug}/secret` makes a new one, and the old secret and every token minted with it stop working at once.

| Field | Notes |
| --- | --- |
| `name` | 1 to 100 characters. Also the bot's display name. |
| `slug` | The bot's handle, with the same rules as any handle. Made from `name` when you leave it out. It never changes, and stays taken after the app is deleted, so the bot's old comments keep their author. |
| `permissions` | What the app asks for. See the table below. |
| `public` | `false` by default: the app installs only on the account that owns it. `true` lists it in `GET /api/apps` and lets anyone install it. |
| `webhookUrl`, `webhookSecret`, `events` | Where events go, and the secret they are signed with. The secret is never shown again. |

### Permissions

| Permission | Values | What it gives the bot |
| --- | --- | --- |
| `metadata` | always `read` | Nothing beyond what the others give. |
| `contents` | `none`, `read`, `write` | `read` reads the code; `write` moves refs: pushes, edits files, merges pull requests, applies suggestions and deletes branches. |
| `pulls` | `none`, `read`, `write` | `write` lets it open pull requests, comment, review and show presence. It moves no ref: merging needs `contents: write`. |
| `issues` | `none`, `read`, `write` | Reads issues and comments on them. |
| `checks` | `none`, `read`, `write` | Reads the repository, for check runs. |
| `sandboxes` | `none`, `write` | Starts and runs [sandboxes](https://status.sailfork.com/docs/sandboxes) on the organization's machines, on an organization install. |

In a covered repository the bot has read access when any of `contents`, `pulls`, `issues` or `checks` is read or write, and write access when `contents` or `pulls` is write. Only `contents: write` lets its tokens move a ref; without it a push, merge or file edit answers "this token is not scoped to that ref". It never has admin access. An installation keeps the permissions the app had when it was installed: narrowing the app's permissions narrows every installation at once, and widening them applies only to installations made after.

## Install it

People install from the browser. [Apps](https://status.sailfork.com/apps) lists every public app, and an app's page shows what it does, who made it, the permissions it asks for in plain words and the events it hears about. Install asks which account (yourself, or an organization you own; one you cannot administer is shown disabled with the reason), then every repository or only the ones you pick, then shows what the app will be able to do before anything changes. Signed out, Install sends you to sign in and back.

After that, **Settings, Installed apps** (and the same screen under an organization's settings) lists each installation with the repositories it reaches and what it can do. You can change the repositories, pause it (its tokens stop at once, and Resume turns it back on) or remove it. Developers create and edit apps under **Settings, Your apps**: the client secret appears once, after creating the app or rotating it.

Installing lets the app into an account's repositories, so it takes a signed-in browser session. A token cannot install an app.

```http
POST /api/apps/tide-bot/installations
{ "repos": ["fenil/ocean-landing"] }
```

- Leave out `org` to install on your own account, or name an organization you own. A member who is not an owner gets 403.
- Leave out `repos`, or send `null`, for every repository of the account, including ones made later. A list covers only those, and each must be one of the account's repositories that you admin; any that are not are named in a 422.
- `PATCH /api/installations/{id}` changes the repositories or suspends the installation with `{"suspended": true}`. `DELETE /api/installations/{id}` removes it. Either way its tokens stop working at once.
- A repository transferred to another account drops out of the installation.

### Ask an app to review

On a pull request, the reviewer picker also lists the apps installed on the repository. Asking one sends it `pull_request` with action `review_requested`, so it can start its review.

### Trusted approvals

An app's approval never counts toward the approvals a merge needs, the way an agent's approval never does, unless a repository admin trusts that app. Settings, Merging, **Apps whose approval counts** lists the installed apps; it is empty by default. The same list is `GET` and `PUT /api/repos/{owner}/{repo}/trusted-apps` (`{"apps": ["tide-bot"]}`, admin only, 422 for an app not installed there). An app that is not listed can still review and comment; its approval is shown but does not count.

## Mint a token

The app lists its installations and mints a token for one, with its client secret:

```sh
curl -H "Authorization: Bearer $APP_SECRET" https://status.sailfork.com/api/app/installations
curl -X POST -H "Authorization: Bearer $APP_SECRET" https://status.sailfork.com/api/app/installations/<id>/token
```

```json
{
  "token": "sf_...",
  "expiresAt": "2026-11-14T23:29:09Z",
  "installationId": "5c2eea08-7aae-428d-8c1a-7b3257373248",
  "repositorySelection": "selected",
  "repos": ["fenil/ocean-landing"],
  "permissions": { "metadata": "read", "contents": "read", "pulls": "write", "issues": "none", "checks": "none", "sandboxes": "none" }
}
```

Mint a new token when the hour is up. A suspended installation answers 403 with `code: "suspended"`.

## Call the API

Send the token as `Authorization: Bearer`, as with any [token](https://status.sailfork.com/docs/tokens). For git over HTTPS, the username is the bot's handle and the password is the token.

```sh
curl -X POST -H "Authorization: Bearer $INSTALLATION_TOKEN" -H "Content-Type: application/json" \
  -d '{"thread":null,"path":"src/tides.ts","line":42,"body":"This rounds down."}' \
  https://status.sailfork.com/api/repos/fenil/ocean-landing/pulls/14/comments
git clone https://tide-bot:$INSTALLATION_TOKEN@git.sailfork.com/fenil/ocean-landing.git
```

The comment's author is `tide-bot`, with `agent: true` and `via: "tide-bot"`. The token always speaks as its app, whatever `X-Sailfork-Agent` says. A batched review with a verdict works the same way. See [Reviews](https://status.sailfork.com/docs/api-pulls#reviews).

What a token reaches:

| Request | Answer |
| --- | --- |
| A repository the installation covers | Whatever the permissions allow. A route that needs more is 403 `insufficient_scope: this token needs repo:write`. |
| Any other repository, public or private, real or not | 404, so the token learns nothing about it. |
| `/api/me` | The bot's account. |
| Account and organization routes, other tokens, other apps | 403 `an installation token cannot reach this route`. |
| Anything after the installation is suspended or removed, or the token expired | 401. |

## Cite proof

A review comment can cite a sandbox exec as proof, and it shows as **Verified** when the exec is the bot's own and ran on the pull request's head commit. See [Proof](https://status.sailfork.com/docs/api-pulls#proof).

To run one, the app needs `sandboxes: write` and an installation on an organization with Drydock machines. Its token can then start a sandbox from the repository and run the test:

```sh
curl -X POST -H "Authorization: Bearer $INSTALLATION_TOKEN" -H "Content-Type: application/json" \
  -d '{"repo":"tidewater/ocean-landing","ref":"<head sha>"}' https://status.sailfork.com/api/orgs/tidewater/sandboxes
curl -i -X POST -H "Authorization: Bearer $INSTALLATION_TOKEN" -H "Content-Type: application/json" \
  -d '{"command":"npm test"}' https://status.sailfork.com/api/sandboxes/<sandbox id>/exec
```

Cite the `X-Sailfork-Exec` header of the exec as `"proof": {"exec": "<id>"}`. The token reaches only the sandboxes it started in its installation's organization.

## Show presence

While the app works on a pull request, it can show where on the page, as people do:

```sh
curl -X PUT -H "Authorization: Bearer $INSTALLATION_TOKEN" -H "Content-Type: application/json" \
  -d '{"path":"src/tides.ts","line":42,"composing":true,"ttl":60}' \
  https://status.sailfork.com/api/repos/fenil/ocean-landing/pulls/14/presence
```

The spot is labelled with the app. Renew it before `ttl` runs out, or take it down with `DELETE` on the same path. See [Presence](https://status.sailfork.com/docs/api-pulls#presence).

## Events

Set `webhookUrl`, `webhookSecret` and `events` on the app and Sailfork posts each subscribed event to the URL. One delivery goes to each installation that is active, covers the repository and grants a permission that can read what the event is about: `pulls` or `contents` for pull request events, `contents` for `push` and `ci_run`, `issues` for issue events, `checks` for check runs. A suspended installation hears only that it was suspended or deleted. Deliveries use the same engine as repository webhooks: a signed JSON `POST`, up to five attempts with growing waits, and a log.

Each request carries `X-Sailfork-Event`, `X-Sailfork-Delivery`, `X-Sailfork-Installation` and `X-Sailfork-Signature-256`, which is `sha256=` and the hex HMAC-SHA256 of the raw body under your webhook secret. Check it before trusting the body:

```ts
import { createHmac, timingSafeEqual } from 'node:crypto';

const expected = 'sha256=' + createHmac('sha256', webhookSecret).update(rawBody).digest('hex');
const ok = timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
```

Every body has `event`, `action`, `repository` (`owner`, `name`, `full_name`, `private`), `installation.id` and `sender` (`handle`, `kind` of `person` or `app`), plus the subject below.

| Event | Actions | Subject |
| --- | --- | --- |
| `installation` | `created`, `deleted`, `suspended`, `unsuspended`, `repositories` | The installation and its `repositories`. Sent to the app whatever the repository, so it has no `repository`. |
| `pull_request` | `opened`, `synchronize`, `closed`, `merged`, `reopened`, `review_requested` | `pull_request` with number, title, body, state, draft, `head` and `base` (`ref`, `sha`), author and `html_url`. `synchronize` adds `before` and `after`, and fires when the branch moves by push, update-branch or conflict resolution. |
| `pull_request_review` | `submitted` | `review` with `verdict`, `body`, `reviewer` and `commit`, the head the review was sent against. |
| `pull_request_review_comment` | `created` | `thread` (id, path, line, side) and `comment` (body, author, `proof` when it cites one). |
| `pull_request_thread` | `resolved`, `unresolved` | `thread`. |
| `issues` | `opened`, `edited`, `closed`, `reopened` | `issue` with number, title, body, state, author, assignee, labels and `html_url`. |
| `issue_comment` | `created` | `issue` and `comment`. |
| `ci_run` | `completed` | `conclusion` (`pass`, `fail`, `cancelled`) and the `run`. |
| `push` | `push` | `ref`, `before`, `after`, `created`, `deleted`. |
| `check_run` | `created`, `completed`, `rerequested`, `requested_action` | `check_run`, as [check runs](#check-runs) show it. `rerequested` and `requested_action` go only to the app that reported the run; `requested_action` adds `requested_action.identifier`. |

A `pull_request.synchronize` looks like this:

```json
{
  "event": "pull_request",
  "action": "synchronize",
  "number": 14,
  "before": "401e66909694bb57fee6925812cc7d8ed08a832c",
  "after": "e3371fa48215feedb98110c955e454d555c33510",
  "pull_request": {
    "number": 14,
    "title": "Lift the tide chart",
    "state": "open",
    "draft": false,
    "head": { "ref": "evt/two", "sha": "e3371fa48215feedb98110c955e454d555c33510" },
    "base": { "ref": "main", "sha": "67550ce17f4ecd146a1d5bb91babd2036a847110" },
    "author": "fenil",
    "html_url": "https://sailfork.com/fenil/ocean-landing/pulls/14"
  },
  "repository": { "owner": "fenil", "name": "ocean-landing", "full_name": "fenil/ocean-landing", "private": false },
  "installation": { "id": "c635a53a-5688-4ba4-bd78-5c5343981013" },
  "sender": { "handle": "fenil", "kind": "person" }
}
```

An app reads its log with `GET /api/app/deliveries` (newest first, `limit` and `event` filters) and sends one again with `POST /api/app/deliveries/{id}/redeliver`; both take the client secret.

## Check runs

A check run is your tool's result on a commit, shown beside Sailfork CI. It appears on every pull request whose head is that commit, counts in the pull request's checks state, holds auto-merge and the merge queue until it passes, and a branch rule's `requiredChecks` can name it. Its annotations show in the diff on the lines they point at.

Create one with an installation token whose installation grants `checks: write`. Only your app can change it afterwards. A CI provider without an app can report runs with a personal token of someone with write access; those runs belong to that person.

```sh
curl -X POST -H "Authorization: Bearer $INSTALLATION_TOKEN" -H 'content-type: application/json' \
  https://status.sailfork.com/api/repos/fenil/ocean-landing/check-runs \
  -d '{"name":"tide-lint","headSha":"9c1d0e47a2b3f6e85d0a7c4b19e2f3a6d8b05c71","status":"in_progress","detailsUrl":"https://tide.example/runs/81"}'
```

When it finishes, send the conclusion with a `PATCH`:

```sh
curl -X PATCH -H "Authorization: Bearer $INSTALLATION_TOKEN" -H 'content-type: application/json' \
  https://status.sailfork.com/api/repos/fenil/ocean-landing/check-runs/42 \
  -d '{
    "conclusion": "failure",
    "output": { "title": "2 problems", "summary": "Run `tide lint --fix` to fix the first one." },
    "annotations": [
      { "path": "src/tide.ts", "startLine": 12, "endLine": 14, "level": "failure", "title": "Unrounded minutes", "message": "Round before you compare." }
    ],
    "actions": [{ "label": "Fix it", "identifier": "fix", "description": "Push a commit with the fix" }]
  }'
```

| Field | Notes |
| --- | --- |
| `name` | What `requiredChecks` matches. 1 to 255 bytes. |
| `headSha` | The full commit id. |
| `status` | `queued` (the default), `in_progress` or `completed`. |
| `conclusion` | `success`, `failure`, `neutral`, `cancelled`, `skipped`, `timed_out` or `action_required`. Needed once completed, and sending one alone completes the run. Success and neutral pass; skipped and cancelled do not fail but do not pass a required check; the rest fail. |
| `startedAt`, `completedAt` | Default to when the run started and completed. |
| `detailsUrl`, `externalId` | Your report's page, and your own id for the run. |
| `output` | `title`, and `summary` and `text` in markdown. A person expands them under the check on the pull request. |
| `annotations` | `path`, `startLine`, `endLine`, `level` (`notice`, `warning`, `failure`), `message`, `title`. Each `PATCH` adds to them, up to 500 per run. |
| `actions` | Up to 3 buttons: `label` (20 characters), `identifier` (20 of letters, digits, `.`, `_`, `-`) and `description` (40). A `PATCH` replaces them. |

The bodies also take GitHub's snake_case names (`head_sha`, `details_url`, `start_line`, `annotation_level`, annotations inside `output`), so a GitHub check run body works as it is.

A person with write access can press **Re-run** under your check, which sends you `check_run.rerequested`, or one of its action buttons, which sends `check_run.requested_action` with the button's `identifier`. Subscribe to `check_run` to hear them.

| Route | Does |
| --- | --- |
| `POST /api/repos/{owner}/{repo}/check-runs` | Creates a run. |
| `PATCH /api/repos/{owner}/{repo}/check-runs/{id}` | Changes your run. 403 for anyone else's. |
| `GET /api/repos/{owner}/{repo}/check-runs/{id}` | One run. |
| `GET /api/repos/{owner}/{repo}/commits/{sha}/check-runs` | The newest run of each name and reporter on a commit; `?filter=all` for every run. |
| `POST /api/repos/{owner}/{repo}/check-runs/{id}/rerequest` | Asks the app to run it again. A person with write access. |
| `POST /api/repos/{owner}/{repo}/check-runs/{id}/actions/{identifier}` | Presses one of its buttons. A person with write access. |

## Manage the app

| Route | Who | Does |
| --- | --- | --- |
| `GET /api/apps`, `GET /api/apps/{slug}` | Anyone | The public apps, and one app. A private app is 404 except to its owners. |
| `GET /api/me/apps` | You | The apps you or your organizations own. |
| `PATCH /api/apps/{slug}` | Its owners | Changes the name, description, URLs, permissions, events or `public`. |
| `DELETE /api/apps/{slug}` | Its owners | Deletes the app, its installations and their tokens. |
| `GET /api/me/installations`, `GET /api/orgs/{org}/installations` | You, organization owners | What is installed on your account or the organization. |
| `GET /api/app` | The app | Itself, with its client secret. |
| `GET /api/app/deliveries`, `POST /api/app/deliveries/{id}/redeliver` | The app | Its webhook log, and a delivery sent again. |

Every field and status is in [the REST API](https://status.sailfork.com/docs/api).

---

Every docs page: https://status.sailfork.com/llms.txt
