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.

RoleScope on a tokenRoutes
Readrepo:readWorkflows, compatibility, runs, logs, live feed, artifacts, caches, environments
Writerepo:writeDispatch, cancel, rerun, approve, reject, delete caches
Adminrepo:adminSecrets, 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://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 fieldTypeNotes
providerstring, requiredOnly "depot".
tokenstring, requiredA Depot API token, no whitespace, at most 4096 characters.
depotOrgIdstring, optionalLetters, 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://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://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.

FieldTypeNotes
name (path)string[A-Za-z_][A-Za-z0-9_]*, not starting with GITHUB_.
valuestring, required1 byte to 48 KiB.
environmentstring, optionalAbsent 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://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://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 fieldTypeNotes
requireApprovalboolean, requiredHold 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://sailfork.com/api/repos/fenil/ocean-landing/environments/production
{ "name": "production", "requireApproval": true }

Workflows

List workflows

GET /api/repos/{owner}/{repo}/ci/workflows
QueryTypeNotes
refstring, optionalA 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
    }
  ]
}
FieldValues
severitywont_run, needs_setup, may_fail
kindinvalid, trigger, runs_on, var, secret, github_api
setFor 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.

FieldTypeNotes
file (path)stringThe name in .github/workflows, such as deploy.yml.
refstring, optionalA branch or tag, short or full. Defaults to the default branch.
inputsobject, optionalName 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://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
QueryTypeNotes
viewstring, optionalOnly 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://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 fieldNotes
event.kindpush, 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.
agentThe commit came from an agent through a caisson opened with an access token.
sha7 characters.
testsJUnit results (**/junit*.xml, **/TEST-*.xml) summed, or null without a report. Failures list the first 200 cases per job.
noteWhy a run failed without running, such as an invalid workflow file.
gateOn 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
ParameterNotes
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://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
QueryNotes
jobOptional 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.

QueryNotes
haveOptional 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.
logsfalse sends states only, with no lines events.

Events, in the order a viewer receives them:

eventdata
runThe 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://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.

FieldTypeNotes
failedOnlybooleanRerun only what failed and carry passed jobs over with their steps, logs and outputs. 409 unless the run failed or was cancelled.
jobsstring[]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://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://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
QueryNotes
keyOptional. Only keys that start with this prefix.
refOptional. 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://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://sailfork.com/api/repos/fenil/ocean-landing/ci/caches?key=bun-&ref=main"
{ "deleted": 3 }

Loading Sailfork