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.

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:

sailfork ci list
sailfork ci watch <run id>

If nothing starts, the repository has no compute yet. See 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

TriggerWhen it starts a run
pushA 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_requestA pull request is opened, reopened or pushed to (opened, reopened, synchronize), or the types: you list.
scheduleA cron in UTC (five fields) on the default branch.
workflow_dispatchYou 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) 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.
  • 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 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-onSandbox
ubuntu-latest, ubuntu-24.042 vCPUs and 4 GB
ubuntu-latest-8, linux-4-coresThat many vCPUs (1 to 64) and 2 GB per vCPU. Depot rounds up to a power of two.
ubuntu-latest-4-6gb4 vCPUs and 6 GB on Drydock. Depot ignores the memory.
ubuntu-24.04-arm, or an arm64 labelAn 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.

FamilyReaches
contentsgit clone, fetch and push, files, commits, branches, tags, compare
issuesissues, labels, milestones, attachments
pull-requestspull requests
actionsruns, 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 }}.

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.

GroupExamples
Won't runA file that does not parse. Triggers that never start (release, pull_request_target, workflow_run, issues). A macos-* or windows-* runner.
Needs setupA secrets.NAME that is not set here, and vars.*. The report shows the sailfork ci secret set command that fixes it.
May failA 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.

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.

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:

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

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

CommandWhat it does
sailfork ci listRecent 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 cachesLists 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, deleteManages 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. The ci toolset of the MCP server 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 for branch rules.

Limits

LimitValue
Workflow file size1 MiB
Matrix combinations256 per job. More, or none, makes the workflow invalid.
Job timeouttimeout-minutes, default 360
Sandbox lifetime15 minutes of setup plus the jobs' timeouts, at most 24 hours
Manual run inputs65,535 bytes
Secrets100 per repository, 48 KiB each
Log lines50,000 per step, kept 90 days
Artifacts512 MiB each, 2 GiB and 100 per run, kept 30 days
Caches10 GiB per repository, dropped after 7 days unused
GITHUB_TOKENExpires when the job ends, at most 26 hours

Common failures

What you seeWhy, and what to do
No runs appearThe 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 ownerSame cause.
The run stays queuedEvery Drydock host is full or offline. Check sailfork sandbox host list --org acme.
A secret reads emptyIt 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 GitHubIt uses the job's token against api.github.com. The token is Sailfork's.
Container jobs are not supported on Drydock yetThe 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 automaticallyA 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 triggerAdd on: workflow_dispatch to the file, on the branch you run.

Loading Sailfork