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-onlabel that starts withmacosorwindowsfails the job at once. - On Drydock, a job that uses
container:orservices:fails with "Container jobs are not supported on Drydock yet", because a sandbox has no Docker socket. GITHUB_SERVER_URLishttps://github.comand the REST API is Sailfork's, so a step that callsapi.github.comor theghCLI with the job's token fails. Actions whosetokeninput defaults togithub.token, such asoven-sh/setup-bun, get an empty default and callapi.github.comanonymously, which GitHub rate limits per IP; atoken:you pass inwith:is Sailfork's token andapi.github.comrejects 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) 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-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 }}.
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 withGITHUB_. - 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.
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_requestrun 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
| 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. 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
| 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. |