CI API
Connect CI compute, manage secrets and environments, start, watch, cancel and rerun workflow runs, and read logs, artifacts and caches over REST.
These routes cover the CI of a repository: workflows, runs, logs, artifacts, caches, secrets, environments and the organization's compute provider. For what CI is and how workflows run, read CI. Authentication, scopes, errors and paging are in the API overview; see Authentication, Token scopes, Errors and Paging.
Reading routes need read access to the repository (signed out is enough on a public repository). Routes that change something say what they need. A repository's secrets are managed by admins only.
| Role | Scope on a token | Routes |
|---|---|---|
| Read | repo:read | Workflows, compatibility, runs, logs, live feed, artifacts, caches, environments |
| Write | repo:write | Dispatch, cancel, rerun, approve, reject, delete caches |
| Admin | repo:admin | Secrets, environment settings |
Every route here answers 503 when the server has no CI configured. Repositories without an organization, and organizations with neither a provider nor an online Drydock host, get no runs.
Note
A workflow's own GITHUB_TOKEN can call the actions family of these routes (runs, environments, workflows, dispatches, and cache reads and deletes) within its permissions: block. It cannot approve or reject a deploy: those routes answer 403 for it.
Organization provider
An organization runs CI on a connected Depot account, or on its own Drydock hosts. These routes manage the Depot connection.
Get the provider
GET /api/orgs/{org}/ci/provider Returns the connection. Needs org:read and organization membership. Answers 404 with { "error": "not_connected" } when none is set.
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://status.sailfork.com/api/orgs/acme/ci/provider {
"provider": "depot",
"depotOrgId": "dp-8f3a2",
"tokenHint": "…9k2m",
"connectedBy": "Fenil Sonani",
"connectedAt": "2026-11-03T18:22:10Z",
"lastError": null
} The token is never returned, only tokenHint (a mark and its last 4 characters).
Connect a provider
PUT /api/orgs/{org}/ci/provider Needs org:admin and organization owner. Sailfork checks the token against Depot first and stores it sealed.
| Body field | Type | Notes |
|---|---|---|
provider | string, required | Only "depot". |
token | string, required | A Depot API token, no whitespace, at most 4096 characters. |
depotOrgId | string, optional | Letters, digits, - and _, at most 200 characters. |
curl -X PUT -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"provider":"depot","token":"depot_xxxxxxxxxxxx"}' \
https://status.sailfork.com/api/orgs/acme/ci/provider Returns the same object as the get route. Answers 422 for a bad field, or with { "error": "provider_rejected", "message": "..." } when Depot refuses the token. The change is in the audit log as ci.provider.connect.
Disconnect a provider
DELETE /api/orgs/{org}/ci/provider Needs org:admin and organization owner. Answers 204, or 404 with not_connected when none is set. Audit entry ci.provider.disconnect.
Secrets
Secrets are write-only: the API lists names and never returns a value. They reach a job as secrets and are masked in logs. Masking matches exact text only, so a workflow that can read a secret can print it in another encoding.
List secrets
GET /api/repos/{owner}/{repo}/ci/secrets Needs repository admin. Returns names and environments.
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://status.sailfork.com/api/repos/fenil/ocean-landing/ci/secrets {
"secrets": [
{ "name": "DEPLOY_KEY", "environment": "production", "updatedAt": "2026-11-02T09:14:00Z" },
{ "name": "NPM_TOKEN", "environment": null, "updatedAt": "2026-10-20T16:40:12Z" }
]
} Set a secret
PUT /api/repos/{owner}/{repo}/ci/secrets/{name} Needs repository admin. Creates the secret or replaces its value.
| Field | Type | Notes |
|---|---|---|
name (path) | string | [A-Za-z_][A-Za-z0-9_]*, not starting with GITHUB_. |
value | string, required | 1 byte to 48 KiB. |
environment | string, optional | Absent keeps the current environment, "" removes it, longer than 255 characters is 422. |
A secret without an environment goes to every run that is not an outside contribution. A secret with an environment goes only to an execution whose jobs all declare environment: <name>, and only on a run of the default branch. A repository holds at most 100 secrets (422 beyond that).
curl -X PUT -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"value":"s3cret","environment":"production"}' \
https://status.sailfork.com/api/repos/fenil/ocean-landing/ci/secrets/DEPLOY_KEY Returns the secret as listed above, with the audit entry ci.secret.update.
Delete a secret
DELETE /api/repos/{owner}/{repo}/ci/secrets/{name} Needs repository admin. Answers 204, or 404 for an unknown name.
Note
There is no variables route. Only secrets are stored, so keep non-secret values in the workflow file.
Environments
An environment can hold secrets and can require a person to approve a deploy before its jobs run.
List environments
GET /api/repos/{owner}/{repo}/environments Returns every configured or deployed-to environment as a bare array, each with its latest deploys.
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://status.sailfork.com/api/repos/fenil/ocean-landing/environments [
{
"name": "production",
"url": "https://ocean-landing.example.com",
"instances": null,
"current": { "runId": 41, "sha": "9c1d4e2", "tag": "v1.4.0", "at": "2026-11-09T21:05:00Z", "by": "Fenil Sonani", "agent": false },
"previous": { "runId": 37, "sha": "4be07aa", "tag": "v1.3.2", "at": "2026-11-01T17:30:00Z", "by": "Fenil Sonani", "agent": false },
"requireApproval": true
}
] current and previous are null before a first deploy. To roll back, rerun the runId of previous (see Rerun a run).
Configure an environment
PUT /api/repos/{owner}/{repo}/environments/{name} Needs repository admin. The name is 1 to 255 characters with no leading or trailing space.
| Body field | Type | Notes |
|---|---|---|
requireApproval | boolean, required | Hold the environment's jobs until a person approves them. |
curl -X PUT -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"requireApproval":true}' \
https://status.sailfork.com/api/repos/fenil/ocean-landing/environments/production { "name": "production", "requireApproval": true } Workflows
List workflows
GET /api/repos/{owner}/{repo}/ci/workflows | Query | Type | Notes |
|---|---|---|
ref | string, optional | A branch or tag. Defaults to the default branch. 422 for an unknown ref. |
Returns each file in .github/workflows/ at that ref, the inputs of a manual run when it has on: workflow_dispatch, or why it does not parse.
{
"ref": "main",
"workflows": [
{
"path": ".github/workflows/deploy.yml",
"file": "deploy.yml",
"name": "Deploy",
"dispatch": {
"inputs": [
{ "name": "target", "description": "Where to deploy", "required": true, "default": null, "type": "choice", "options": ["staging", "production"] }
]
},
"error": null
}
]
} dispatch is null without workflow_dispatch. An input type is string, boolean, choice, number or environment; options is set for choice only.
Check compatibility
GET /api/repos/{owner}/{repo}/ci/compatibility Reads the default branch's workflow files as GitHub would and reports what will not run here, what needs setup and what may fail. Before the first push it returns no workflows and no findings.
{
"ref": "main",
"workflows": 2,
"findings": [
{
"severity": "needs_setup",
"kind": "secret",
"name": "NPM_TOKEN",
"message": "The workflow reads secrets.NPM_TOKEN and the repository has no such secret.",
"fix": "sailfork ci secret set NPM_TOKEN",
"workflows": ["ci.yml"],
"set": false
}
]
} | Field | Values |
|---|---|
severity | wont_run, needs_setup, may_fail |
kind | invalid, trigger, runs_on, var, secret, github_api |
set | For secrets, whether the repository has it. Filled for admins, null for everyone else. |
Dispatch a workflow
POST /api/repos/{owner}/{repo}/ci/workflows/{file}/dispatches Starts a manual run of a workflow with on: workflow_dispatch. Needs repository write. The body is optional.
| Field | Type | Notes |
|---|---|---|
file (path) | string | The name in .github/workflows, such as deploy.yml. |
ref | string, optional | A branch or tag, short or full. Defaults to the default branch. |
inputs | object, optional | Name to string, boolean or number. Defaults fill missing inputs. At most 65,535 bytes. |
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"ref":"main","inputs":{"target":"staging"}}' \
https://status.sailfork.com/api/repos/fenil/ocean-landing/ci/workflows/deploy.yml/dispatches { "id": 42 } Answers 201 with the new run number. Answers 422 with { "error": "..." } for an unknown input, a missing required input, a choice outside its options, a boolean that is not true or false, a number that does not parse, a workflow without workflow_dispatch, a missing file or ref, or an owner with no CI compute.
Runs
A run's id is a per-repository sequence number. A run has jobs, a job has steps, and steps are numbered from 0 in RunJob.steps order.
List runs
GET /api/repos/{owner}/{repo}/runs | Query | Type | Notes |
|---|---|---|
view | string, optional | Only summary. Any other value is 422. |
Returns the newest runs first, at most 200, as { "runs": [...] }. In the default view each step carries log: []. With view=summary each job has steps: [] and carries stepCount and seconds (its steps' seconds summed) instead, and its tests keep their counts with failures: []; one run (GET .../runs/{id}) has them.
curl -H "Authorization: Bearer $SAILFORK_TOKEN" "https://status.sailfork.com/api/repos/fenil/ocean-landing/runs?view=summary" {
"runs": [
{
"id": 42,
"workflow": "Deploy",
"event": { "kind": "dispatch", "inputs": { "target": "staging" } },
"actor": "Fenil Sonani",
"agent": false,
"branch": "main",
"sha": "9c1d4e2",
"subject": "fix(web): tighten hero spacing",
"startedAt": "2026-11-10T08:01:12Z",
"finishedAt": "2026-11-10T08:03:40Z",
"jobs": [
{
"id": "deploy",
"name": "deploy",
"needs": [],
"state": "pass",
"runner": "ubuntu-latest",
"steps": [],
"stepCount": 6,
"seconds": 142,
"tests": null,
"env": "staging",
"gate": null
}
],
"artifacts": [],
"tests": null,
"note": null
}
]
} | Run field | Notes |
|---|---|
event.kind | push, pull (with pull, the pull request number), schedule or dispatch (with inputs). |
state (run, job, step) | pass, fail, running, queued, waiting, skipped, cancelled. A step is never waiting. |
agent | The commit came from an agent through a caisson opened with an access token. |
sha | 7 characters. |
tests | JUnit results (**/junit*.xml, **/TEST-*.xml) summed, or null without a report. Failures list the first 200 cases per job. |
note | Why a run failed without running, such as an invalid workflow file. |
gate | On a job of an environment that requires approval: reason, approvedBy, at. |
Get a run
GET /api/repos/{owner}/{repo}/runs/{id} Returns one run with every step's full log. Answers 404 for an unknown run. For long runs, read logs in pages with the routes below instead.
Read a step log
GET /api/repos/{owner}/{repo}/runs/{id}/jobs/{job}/steps/{n}/log | Parameter | Notes |
|---|---|
job (path) | The job key, as in RunJob.id. |
n (path) | The 0-based index into the job's steps. |
after (query) | Lines already shown. Default 0. |
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
"https://status.sailfork.com/api/repos/fenil/ocean-landing/runs/42/jobs/deploy/steps/2/log?after=0" { "lines": ["Run bun install", "bun install v1.2.0", "Done in 3.1s"], "next": 3, "done": true } A page is up to 5000 lines. Pass next back as after to continue. done is true once the step has finished and no lines are left. Answers 404 for an unknown run, job or step.
Read a run's logs
GET /api/repos/{owner}/{repo}/runs/{id}/logs | Query | Notes |
|---|---|
job | Optional job key. Limits the result to one job. 404 for an unknown job. |
Returns the first page of every step of every job (or of one job) in job then step order, as { "steps": [...] }. Each entry has job, jobName, step, name, lines, next and done. Continue a step that is not done with its step log route and next.
Watch a run live
GET /api/repos/{owner}/{repo}/runs/{id}/live A server-sent event stream (text/event-stream). It works signed out on public repositories.
| Query | Notes |
|---|---|
have | Optional JSON cursor: per job key, the next line index of each step, such as {"build":[12,0]}. Missing steps count from 0. 422 for malformed JSON. |
logs | false sends states only, with no lines events. |
Events, in the order a viewer receives them:
event | data |
|---|---|
run | The run, with every step's log empty. First event. |
lines | { job, step, from, lines }. Append the lines to that step's log at index from. |
step | { job, step, state, seconds } |
job | { job, state } |
end | {}. The run finished and everything was sent. The server closes the stream. |
Step and job states only move forward. The server sends a comment keep-alive every 15 seconds. To resume after a drop, send your current line counts as have, and nothing is sent twice or skipped.
curl -N -H "Authorization: Bearer $SAILFORK_TOKEN" \
"https://status.sailfork.com/api/repos/fenil/ocean-landing/runs/42/live?logs=false" Cancel a run
POST /api/repos/{owner}/{repo}/runs/{id}/cancel Needs repository write. Answers 202. Unstarted jobs are cancelled at once and a running sandbox is killed within about 2 seconds. Answers 409 when the run has already finished.
Rerun a run
POST /api/repos/{owner}/{repo}/runs/{id}/rerun Needs repository write. Starts a new run of the same workflow file and commit, from any run. The body is optional and accepts no other fields.
| Field | Type | Notes |
|---|---|---|
failedOnly | boolean | Rerun only what failed and carry passed jobs over with their steps, logs and outputs. 409 unless the run failed or was cancelled. |
jobs | string[] | Job keys to rerun, plus the jobs that need them. Every other passed job is carried over. 422 for a key the workflow lacks, 409 while the run is still going. |
Send failedOnly or jobs, not both (422).
curl -X POST -H "Authorization: Bearer $SAILFORK_TOKEN" -H "Content-Type: application/json" \
-d '{"failedOnly":true}' \
https://status.sailfork.com/api/repos/fenil/ocean-landing/runs/42/rerun { "id": 43 } Answers 201 with the new run number.
Approve a deploy job
POST /api/repos/{owner}/{repo}/runs/{id}/jobs/{job}/approve Releases a job that is waiting on an environment that requires approval. Needs repository write, from a person's token. A workflow's GITHUB_TOKEN gets 403. Answers 409 unless the job is waiting. Returns { "approvedBy": "fenil", "at": "2026-11-10T08:02:00Z" }. The org audit log records ci.deploy.approve.
Reject a deploy job
POST /api/repos/{owner}/{repo}/runs/{id}/jobs/{job}/reject Same access as approve. The job becomes cancelled and its dependents are skipped. Returns { "reason": "...", "at": "2026-11-10T08:02:00Z" }. Answers 409 unless the job is waiting. The audit entry is ci.deploy.reject.
Artifacts
Artifacts come from actions/upload-artifact@v4 and expire 30 days after upload. Limits are 512 MiB per artifact and 2 GiB and 100 artifacts per run. An artifact over a limit is skipped, with a line in the job's "Complete job" step.
List artifacts
GET /api/repos/{owner}/{repo}/runs/{id}/artifacts Returns { "artifacts": [...] }, the same list as Run.artifacts. Answers 404 for an unknown run.
{
"artifacts": [
{ "name": "coverage", "size": 482113, "jobs": ["test"], "createdAt": "2026-11-10T08:03:01Z", "expiresAt": "2026-12-10T08:03:01Z" }
]
} Download an artifact
GET /api/repos/{owner}/{repo}/runs/{id}/artifacts/{name} Returns the artifact as application/zip. Answers 404 for an unknown or expired artifact.
curl -L -H "Authorization: Bearer $SAILFORK_TOKEN" -o coverage.zip \
https://status.sailfork.com/api/repos/fenil/ocean-landing/runs/42/artifacts/coverage Caches
Jobs save and restore caches through the cache service (actions/cache). A repository holds at most 10 GiB, least recently restored evicted first, and entries not restored for 7 days expire. These routes inspect and clear them.
List caches
GET /api/repos/{owner}/{repo}/ci/caches | Query | Notes |
|---|---|
key | Optional. Only keys that start with this prefix. |
ref | Optional. A branch name or a full ref such as refs/heads/main. |
Returns up to 1000 caches, most recently used first, plus total usage.
curl -H "Authorization: Bearer $SAILFORK_TOKEN" "https://status.sailfork.com/api/repos/fenil/ocean-landing/ci/caches?key=bun-" {
"caches": [
{
"id": 118,
"key": "bun-Linux-4f2a91",
"version": "d41d8cd9",
"ref": "refs/heads/main",
"sizeBytes": 73400320,
"createdAt": "2026-11-09T21:06:12Z",
"lastUsedAt": "2026-11-10T08:01:40Z"
}
],
"usedBytes": 73400320,
"limitBytes": 10737418240
} A GITHUB_TOKEN with actions access can also call this route.
Delete a cache
DELETE /api/repos/{owner}/{repo}/ci/caches/{id} Needs repository write. Answers 204, or 404 for an unknown id.
Delete matching caches
DELETE /api/repos/{owner}/{repo}/ci/caches Needs repository write. Takes the same key and ref query as the list route. With no filter it deletes every cache of the repository.
curl -X DELETE -H "Authorization: Bearer $SAILFORK_TOKEN" \
"https://status.sailfork.com/api/repos/fenil/ocean-landing/ci/caches?key=bun-&ref=main" { "deleted": 3 }