# 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](https://sailfork.com/docs/ci). Authentication, scopes, errors and paging are in the [API overview](https://sailfork.com/docs/api); see [Authentication](https://sailfork.com/docs/api#authentication), [Token scopes](https://sailfork.com/docs/api#token-scopes), [Errors](https://sailfork.com/docs/api#errors) and [Paging](https://sailfork.com/docs/api#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](https://sailfork.com/docs/sandboxes). These routes manage the Depot connection.

### Get the provider

```http
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.

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://sailfork.com/api/orgs/acme/ci/provider
```

```json
{
  "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

```http
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. |

```sh
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

```http
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

```http
GET /api/repos/{owner}/{repo}/ci/secrets
```

Needs repository admin. Returns names and environments.

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://sailfork.com/api/repos/fenil/ocean-landing/ci/secrets
```

```json
{
  "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

```http
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).

```sh
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

```http
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

```http
GET /api/repos/{owner}/{repo}/environments
```

Returns every configured or deployed-to environment as a bare array, each with its latest deploys.

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" https://sailfork.com/api/repos/fenil/ocean-landing/environments
```

```json
[
  {
    "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](#rerun-a-run)).

### Configure an environment

```http
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. |

```sh
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
```

```json
{ "name": "production", "requireApproval": true }
```

## Workflows

### List workflows

```http
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.

```json
{
  "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

```http
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.

```json
{
  "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

```http
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. |

```sh
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
```

```json
{ "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

```http
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.

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" "https://sailfork.com/api/repos/fenil/ocean-landing/runs?view=summary"
```

```json
{
  "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

```http
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

```http
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. |

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" \
  "https://sailfork.com/api/repos/fenil/ocean-landing/runs/42/jobs/deploy/steps/2/log?after=0"
```

```json
{ "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

```http
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

```http
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.

```sh
curl -N -H "Authorization: Bearer $SAILFORK_TOKEN" \
  "https://sailfork.com/api/repos/fenil/ocean-landing/runs/42/live?logs=false"
```

### Cancel a run

```http
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

```http
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).

```sh
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
```

```json
{ "id": 43 }
```

Answers 201 with the new run number.

### Approve a deploy job

```http
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

```http
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

```http
GET /api/repos/{owner}/{repo}/runs/{id}/artifacts
```

Returns `{ "artifacts": [...] }`, the same list as `Run.artifacts`. Answers 404 for an unknown run.

```json
{
  "artifacts": [
    { "name": "coverage", "size": 482113, "jobs": ["test"], "createdAt": "2026-11-10T08:03:01Z", "expiresAt": "2026-12-10T08:03:01Z" }
  ]
}
```

### Download an artifact

```http
GET /api/repos/{owner}/{repo}/runs/{id}/artifacts/{name}
```

Returns the artifact as `application/zip`. Answers 404 for an unknown or expired artifact.

```sh
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

```http
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.

```sh
curl -H "Authorization: Bearer $SAILFORK_TOKEN" "https://sailfork.com/api/repos/fenil/ocean-landing/ci/caches?key=bun-"
```

```json
{
  "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

```http
DELETE /api/repos/{owner}/{repo}/ci/caches/{id}
```

Needs repository write. Answers 204, or 404 for an unknown id.

### Delete matching caches

```http
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.

```sh
curl -X DELETE -H "Authorization: Bearer $SAILFORK_TOKEN" \
  "https://sailfork.com/api/repos/fenil/ocean-landing/ci/caches?key=bun-&ref=main"
```

```json
{ "deleted": 3 }
```

---

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