# CI

Push a GitHub Actions workflow and every push and pull request runs it on your own machines, with live logs, reruns, secrets, caches and artifacts.

## A first workflow

Run this in a clone, swap the `echo` line for your test command, then commit and push.

```sh
mkdir -p .github/workflows
cat > .github/workflows/ci.yml <<'EOF'
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "tests go here"
EOF
```

The run appears on the repository's Runs page, with live logs and reruns. From a terminal:

```sh
sailfork ci list
sailfork ci watch <run id>
```

If nothing starts, the repository has no compute yet. See [Where jobs run](#where-jobs-run).

## How it works

### Workflows are GitHub Actions files

Put YAML in `.github/workflows/` and push. Sailfork runs it with nektos/act, so most actions and `run:` steps work as they do on GitHub. Files must end in `.yml` or `.yaml`, and a file over 1 MiB is not read.

Each matching workflow gets one run per event. A workflow file that does not parse becomes a failed run on push, and its note says why.

Some things behave differently from GitHub:

- Jobs run on Linux only. A `runs-on` label that starts with `macos` or `windows` fails the job at once.
- On Drydock, a job that uses `container:` or `services:` fails with "Container jobs are not supported on Drydock yet", because a sandbox has no Docker socket.
- `GITHUB_SERVER_URL` is `https://github.com` and the REST API is Sailfork's, so a step that calls `api.github.com` or the `gh` CLI with the job's token fails. Actions whose `token` input defaults to `github.token`, such as `oven-sh/setup-bun`, get an empty default and call `api.github.com` anonymously, which GitHub rate limits per IP; a `token:` you pass in `with:` is Sailfork's token and `api.github.com` rejects it.
- Repository variables are not supported: `vars.*` is empty.
- Each run keeps the workflow text it started with, so a rerun reads the same file even if you changed it since.

### Triggers

| Trigger | When it starts a run |
| --- | --- |
| `push` | A branch or tag moves: an HTTP or SSH push, a caisson commit, or a pull request merge that moves the base branch. Deleting a ref starts nothing. |
| `pull_request` | A pull request is opened, reopened or pushed to (`opened`, `reopened`, `synchronize`), or the `types:` you list. |
| `schedule` | A cron in UTC (five fields) on the default branch. |
| `workflow_dispatch` | You start it by hand. |

`on: release` is accepted but publishing a release starts nothing. For a release build, trigger on a tag push: `on: push: tags: ['v*']`. `pull_request_target`, `workflow_run`, `issues` and `issue_comment` never start a run.

**Filters.** `push` takes `branches`, `branches-ignore`, `tags`, `tags-ignore`, `paths` and `paths-ignore`. `pull_request` takes `types`, `branches`, `branches-ignore`, `paths` and `paths-ignore`, and `branches` there matches the pull request's base. Use one of each pair, not both: a file with both is invalid. Patterns follow GitHub's syntax: `*` stops at `/`, `**` crosses it, and a later `!pattern` clears an earlier match. If you filter only on branches, a tag push starts nothing, and the other way around. `paths` compares against the files changed since the old tip of the branch (or since the default branch for a new branch) and is not applied to tags.

**Pushes to pull request branches.** A push to the head branch of an open pull request starts the `pull_request` workflows (`synchronize`). If a push and the pull request report the same head commit, the workflows start once.

**Schedules.** Sailfork reads the crons from the default branch on every push to it, and checks every 30 seconds for crons that ticked. A cron run uses the default branch's latest commit and runs as the repository's owner.

**Outside contributions.** A pull request from a `contrib/` branch (see [Pull requests](https://status.sailfork.com/docs/pull-requests)) never starts workflows on its own, and a push to a `contrib/` branch starts none either. Someone with write access presses Run workflows on the pull request. Those runs get read-only permissions and no repository secrets. They never run on Sailfork's shared hosts: they go to Depot or the owner's own hosts, and with neither the run fails and says so.

**Concurrency.** A top-level `concurrency:` group works as on GitHub: runs of one group in a repository run one at a time, a new run cancels the group's runs that have not started, and `cancel-in-progress: true` also cancels the running one. A waiting run says "Waiting for run #N in the group concurrency group". Job-level `concurrency:` is not read.

### Where jobs run

Each job runs in a sandbox that belongs to the owner of the repository. Jobs go to the first of these that the owner has:

- Sailfork hosted, when the owner turned it on under Settings, CI. Jobs run on Sailfork's machines and are billed per second. See [Hosted compute](https://status.sailfork.com/docs/billing#hosted-compute).
- An organization with a connected Depot account runs jobs on Depot. An organization owner connects it under the organization's Settings, CI: paste a Depot API token, and a Depot organization ID if the token reaches more than one. Sailfork checks the token with Depot first and stores it encrypted.
- Otherwise jobs run on an online [Drydock host](https://status.sailfork.com/docs/sandboxes) of the owner. Personal repositories use hosts registered under your own handle.

A repository whose owner has none of these gets no runs, and nothing reports an error. If a Drydock host goes offline mid-job, the job starts over on another host, at most 3 attempts. A job with an `environment:` fails instead, so a deploy never runs twice. Set `retry-on-host-loss: true` on the job to allow a rerun.

The sandbox shape comes from `runs-on`:

| `runs-on` | Sandbox |
| --- | --- |
| `ubuntu-latest`, `ubuntu-24.04` | 2 vCPUs and 4 GB |
| `ubuntu-latest-8`, `linux-4-cores` | That many vCPUs (1 to 64) and 2 GB per vCPU. Depot rounds up to a power of two. |
| `ubuntu-latest-4-6gb` | 4 vCPUs and 6 GB on Drydock. Depot ignores the memory. |
| `ubuntu-24.04-arm`, or an `arm64` label | An arm64 machine |
| `[self-hosted, linux, arm64, gpu]` | arm64, 2 vCPUs, on a Drydock host that has the label `gpu` |

Any label that is not a size or architecture is a host label. A Drydock host must carry every label. Depot has no labels and ignores them.

Jobs that depend on each other share one sandbox. Jobs that do not depend on each other get separate sandboxes, as on GitHub. A job that needs a job with different `permissions:` runs in a later sandbox, and `needs.<job>.outputs` still work.

### GITHUB_TOKEN

Each job gets a `GITHUB_TOKEN` (also `secrets.GITHUB_TOKEN` and `github.token`) that reaches only its own repository, as the person who started the run: the pusher, the pull request's author, the person who pressed Run workflow or rerun, or the repository's owner for a cron run. If that person cannot write to the repository, the token is read-only. It is revoked when the job ends.

The workflow's `permissions:` block decides what it may do. Job level wins over workflow level, and with neither the token gets `contents: read`. `read-all`, `write-all`, `{}` and per-family `read`, `write` and `none` work.

| Family | Reaches |
| --- | --- |
| `contents` | git clone, fetch and push, files, commits, branches, tags, compare |
| `issues` | issues, labels, milestones, attachments |
| `pull-requests` | pull requests |
| `actions` | runs, environments, workflows and dispatches |

Every other route answers 403, including settings, secrets, caissons and `/mcp`. Git accepts the token as the password with any user name: `http://x-access-token:$GITHUB_TOKEN@sailfork.com/fenil/ocean-landing.git`. As on GitHub, anything the token pushes starts no runs.

### Secrets and variables

Repository admins add secrets under the repository's Settings, CI secrets, or with the CLI. A secret is read in a workflow as `${{ secrets.NAME }}`.

```sh
printf '%s' "$DEPLOY_KEY" | sailfork ci secret set DEPLOY_KEY -R fenil/ocean-landing --value -
sailfork ci secret list -R fenil/ocean-landing
```

Pass the value on stdin with `--value -`: a value on the command line shows in `ps` and shell history.

- A name starts with a letter or `_`, then letters, digits and `_`, and it cannot start with `GITHUB_`.
- A value is 1 byte to 48 KiB, and a repository holds at most 100 secrets.
- Values are encrypted, never shown again, and masked as `***` in logs. Masking matches exact text, so a workflow that can read a secret can print it in another encoding.
- Repository variables (`vars.*`) are not supported. Write the value into the workflow, or store it as a secret.
- Secrets are not copied when you move from GitHub. Set them here.

**Environment secrets.** `sailfork ci secret set NAME --environment production` gives a secret only to jobs that declare `environment: production`, and only on runs of the default branch. `--no-environment` removes the restriction.

### Environments and approvals

A job with `environment: production` records a deploy. A repository admin can make an environment require approval: the job then waits as "Waiting for approval to deploy to production" until a person with write access presses Approve and deploy on the Runs page or the run, or rejects it. A rejected job is cancelled, the jobs that need it are skipped and the run ends cancelled. Approvals and rejections are in the organization's audit log. The Runs page lists each environment with its current and previous deploy.

### Not everything runs

The compatibility report reads the workflow files on the default branch and lists what will not run here, what needs setup and what may fail. It is under the repository's Settings, Workflow compatibility, and on the Runs page when a repository has no runs yet.

| Group | Examples |
| --- | --- |
| Won't run | A file that does not parse. Triggers that never start (`release`, `pull_request_target`, `workflow_run`, `issues`). A `macos-*` or `windows-*` runner. |
| Needs setup | A `secrets.NAME` that is not set here, and `vars.*`. The report shows the `sailfork ci secret set` command that fixes it. |
| May fail | A step that runs the `gh` CLI, calls `api.github.com`, or uses an action that talks to GitHub, such as `actions/github-script`, `softprops/action-gh-release` or `peter-evans/create-pull-request`. Detected by name, so the step may still work. |

## Reading a run

### The Runs page

Open Runs in a repository. Each row is one run: the workflow, what started it (Pull request #N, Push to a branch, Nightly schedule, Manual run), who, and the commit. A run opens to its jobs, steps and live logs. The Runs page filters the list, and Show all runs clears the filter.

A run page shows each job's runner, how long it took, its tests and its artifacts. Run workflow starts a manual run. Caches opens the repository's caches.

A run started by a coding agent through a caisson is marked as agent work. See [Working with agents](https://status.sailfork.com/docs/agents).

### Test reports

After each job, Sailfork collects JUnit XML files that match `**/junit*.xml` or `**/TEST-*.xml` (each under 5 MiB, at most 50 per job, none under `node_modules` or `.git`). The run page shows totals and the first 200 failed cases, and `sailfork ci failures` prints them. A file that is not JUnit is skipped with a line in the log, and none of this fails a job.

### Logs

A step keeps at most 50,000 lines, and then one line says the rest was dropped. Logs are kept for 90 days. A run's logs update as they happen, and `sailfork ci watch` and `sailfork ci logs --follow` use the same live stream.

### Artifacts

`actions/upload-artifact@v4` and `actions/download-artifact@v4` work inside a run. An artifact is kept for 30 days. Limits: 512 MiB per artifact, 2 GiB and 100 artifacts per run. A v3 upload is not kept, and an artifact over a limit is skipped with a line in the job's Complete job step. A job cannot download an artifact that an earlier run made.

```sh
sailfork ci artifacts 481
sailfork ci artifacts 481 --download dist --output build/dist.zip
```

### Caches

Caching is opt in: only `actions/cache` and the `cache:` input of the setup actions save anything. Both of GitHub's cache protocols work.

- A cache is saved under the run's ref and restored from that ref, then the pull request's base branch, then the default branch.
- A `pull_request` run by someone without write access saves to a separate scope that no trusted run reads, as on GitHub for forks.
- A repository holds up to 10 GiB, and one entry can be up to 10 GiB. Least recently used entries go first, and an entry not restored for 7 days is dropped.

Open Runs, Caches to see caches grouped by branch, the storage used and delete one or a whole branch's. From a terminal:

```sh
sailfork ci caches --key node-modules- --ref main
sailfork ci caches delete 12
sailfork ci caches delete --all --ref main --yes
```

## Run, rerun and cancel

```sh
sailfork ci run deploy.yml --ref v1.4.0 -f environment=staging -f dry-run=true
sailfork ci rerun 481 --failed
sailfork ci cancel 481 --yes
```

**Manual dispatch.** A workflow needs `on: workflow_dispatch`. Press Run workflow on the Runs page and pick a branch or tag and a workflow, or use `sailfork ci run`. The workflow is named by its file, like `deploy.yml` (the extension may be left out), and `--ref` takes a branch or tag and defaults to the default branch. Pass inputs with `-f key=value`, repeated. Inputs are checked against the file: an unknown input, a missing required one, a `choice` outside its options, a `boolean` that is not `true` or `false`, a `number` that does not parse, or more than 65,535 bytes of inputs is refused. Defaults fill the rest. You need write access.

**Rerun.** The new run uses the same workflow file and commit. On a run page, Rerun all jobs starts it over, and Rerun failed jobs copies the jobs that passed, with their logs and outputs, and runs only the rest. On the CLI, `--failed` does the same, and `--job <id>` reruns that job and the jobs that need it, keeping the others' results. Repeat `--job` for several.

**Cancel.** Cancel run on the run page, or `sailfork ci cancel <id>`. Jobs that have not started cancel at once, and a running sandbox is killed within about 2 seconds. Add `--dry-run` to see what would happen, and `--yes` when there is no terminal to ask on.

## From a terminal

| Command | What it does |
| --- | --- |
| `sailfork ci list` | Recent runs. `--branch`, `--workflow`, `--status`, `--pr <number>` and `--limit` (default 30) narrow it. |
| `sailfork ci view <id>` | A run with its jobs and steps. `--exit-status` exits 1 when the run failed. |
| `sailfork ci watch <id>` | Waits for the run, showing each job as it changes. Exits 1 when the run failed. `--interval` is seconds between checks (default 3). |
| `sailfork ci logs <id>` | Prints logs. `--follow`, `--job`, `--step` (index or part of a name), `--tail <n>` and `--grep <text>`. |
| `sailfork ci failures [id]` | Only what failed: each failed step's exit code, last log lines and error locations. With no id, the newest failed run on the current branch. `--pr`, `--branch` and `--lines` (default 30). |
| `sailfork ci artifacts <id>` | Lists artifacts, or downloads one with `--download <name>`, `--output` and `--force`. |
| `sailfork ci caches` | Lists the repository's caches, or deletes with `caches delete`. |
| `sailfork ci run <workflow>` | Starts a manual run. |
| `sailfork ci rerun <id>` | Runs it again. |
| `sailfork ci cancel <id>` | Cancels a running run. |
| `sailfork ci secret list`, `set`, `delete` | Manages secrets. |
| `sailfork wait run <id>` | Waits for a run to finish, exit 1 when it failed, exit 12 on `--timeout` (default 10m). |
| `sailfork pr checks <number>` | A pull request's checks. `--watch` waits for them. |

Add `-R fenil/ocean-landing` outside a clone, and `--json` for scripts. Over REST, see [CI runs](https://status.sailfork.com/docs/api#ci-runs). The `ci` toolset of the [MCP server](https://status.sailfork.com/docs/mcp) does the same for assistants.

## Pull request checks

A pull request's checks come from the newest run of each workflow on its head commit. Any failed or cancelled run makes it failing, any unfinished run makes it running, and otherwise it passes. A pull request with no runs shows no checks.

A branch rule can require checks before a merge. A required check is a workflow name (its latest run on the head passed) or a job name or id (that job passed in its workflow's latest run). A merge that misses one is refused with `merge rules not met: required check <name>`. See [Branches](https://status.sailfork.com/docs/branches) for branch rules.

## Limits

| Limit | Value |
| --- | --- |
| Workflow file size | 1 MiB |
| Matrix combinations | 256 per job. More, or none, makes the workflow invalid. |
| Job timeout | `timeout-minutes`, default 360 |
| Sandbox lifetime | 15 minutes of setup plus the jobs' timeouts, at most 24 hours |
| Manual run inputs | 65,535 bytes |
| Secrets | 100 per repository, 48 KiB each |
| Log lines | 50,000 per step, kept 90 days |
| Artifacts | 512 MiB each, 2 GiB and 100 per run, kept 30 days |
| Caches | 10 GiB per repository, dropped after 7 days unused |
| `GITHUB_TOKEN` | Expires when the job ends, at most 26 hours |

## Common failures

| What you see | Why, and what to do |
| --- | --- |
| No runs appear | The repository's owner has no Depot account and no Drydock host, or the push did not match the workflow's filters. Connect compute, then check the filters. |
| A manual run answers `this repository has no CI compute: connect a Depot account or a Drydock host to its owner` | Same cause. |
| The run stays queued | Every Drydock host is full or offline. Check `sailfork sandbox host list --org acme`. |
| A secret reads empty | It is not set on this repository, it is restricted to an environment the job does not declare, or the run is an outside contribution. |
| A step gets Bad credentials from GitHub | It uses the job's token against `api.github.com`. The token is Sailfork's. |
| `Container jobs are not supported on Drydock yet` | The job uses `container:` or `services:`. Run the service as a step. |
| The job failed with "The CI worker running this job stopped" | The server restarted. Rerun the workflow. |
| A job failed and says it deploys to an environment, so it is not run again automatically | A Drydock host was lost during a job with an `environment:`. Rerun the workflow, or set `retry-on-host-loss: true` on the job. |
| The manual run answers `has no workflow_dispatch trigger` | Add `on: workflow_dispatch` to the file, on the branch you run. |

---

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