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-botmentions and/tide-botlinks 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 that has the user scope, or from a signed-in browser. Add "org": "<handle>" to have an organization you own own it.
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 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 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.
POST /api/apps/tide-bot/installations
{ "repos": ["fenil/ocean-landing"] } - Leave out
orgto install on your own account, or name an organization you own. A member who is not an owner gets 403. - Leave out
repos, or sendnull, 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:
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 {
"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. For git over HTTPS, the username is the bot's handle and the password is the token.
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.
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.
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:
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:
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.
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:
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 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:
{
"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.
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:
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.