GitHub Actions runners: runs-on: boat
Each job gets a fresh sandbox, billed per second, deleted when the job ends.
CI needs the $20/month plan or higher. On the free trial, or without a plan, boat refuses each job once and says why in boat ci and on the dashboard. Start a plan, then re-run the job.
Set up in 2 steps
- Install the boat CI GitHub App on your GitHub organization or account. Pick the repositories:
boat <repository>, so a runner only takes jobs of its own repository. It works on GitHub organizations only.
If the app is already installed, an owner of the GitHub organization can link it without reinstalling:
--account, not the repository name. The owner can open a link generated by a boat organization admin. After authorizing on GitHub, boat shows which boat account will own the jobs, and nothing is linked until the owner confirms. Only open a link from someone you trust: that account can read the jobs’ logs and sandboxes. The CI tab also has Already installed on GitHub? Link it here.
- In your workflow, change
runs-on:
services:, container:, actions/cache and actions/upload-artifact work as on GitHub-hosted runners. Boat does not pass your own environment to the job: no saved variables, secret files, GitHub token or model provider keys. Use GitHub Actions secrets for anything the job needs. Run boat ci to see the last jobs.
Sizes and options
A job can use the RAM of its size plus all the swap on the sandbox: 4 GB from boat, plus any swapfile a step adds. When a process needs more, the kernel kills it, and boat adds an “Out of memory on Boat” warning to the run. Then use a larger size. The job runs in
$HOME/actions-runner/_work, under $HOME as on GitHub-hosted runners.
Add options after the size with /, for example runs-on: boat-large/from=ci-base/debug:
A label with an unknown option never runs: boat refuses the job and
boat ci shows the reason.
Docker, containers and virtual machines
Each job runs on a full Linux virtual machine with Docker, not in a container:docker build,docker runanddocker composework in steps.services:containers (Postgres, Redis) start next to the job, onlocalhost.container:runs the steps inside the image that you name.- The job can start its own virtual machines: QEMU, Firecracker, the Android emulator. Every sandbox has
/dev/kvm.
from= snapshot does not remove the pulls: boat pulls registry images again at each start. See What a snapshot saves.
Android emulator tests
The emulator is hardware-accelerated on every sandbox. Nothing is boat-specific: the job installs the Android SDK and accepts its license, as on any runner:setup-android@v4: @v3 asks the SDK for the tools package, which Google removed, so it fails on every runner that does not ship an Android SDK.
Windows programs with Wine
boat has no Windows runners. To build Windows executables and test them, cross-compile on Linux and run the.exe with Wine:
wine64 package puts its program at /usr/lib/wine/wine64, not on the PATH. For Rust MSVC targets, cargo-xwin builds on Linux and cargo xwin test runs the tests with Wine. Wine runs most console programs and tests. It is not Windows: GUI, driver and installer tests need a real Windows machine.
See and debug jobs
The CI on Boat VMs tab of the dashboard shows your setup steps, the repositories the app can see, every job with its wait, run time, cost and log, and why a job did not run. The CLI and the API show the same data:--json for the full data. In the API and the SDKs:
Reading needs an API key with
account.read; connecting GitHub and public repositories need account.admin.
Each job shows its true state and its reason: what it waits for, or why it did not run. When boat refuses a job, it says why: no paid plan, an unknown label such as boat-huge, a public repository, a GitHub account not linked to boat, or a sandbox boat cannot create (for example a from= snapshot that does not exist). The job then shows as refused, with the reason, in all three places. A full minute start limit or too many running sandboxes do not refuse the job: boat retries every 15 seconds. For the hour and day start limits, read What happens at a limit.
Each job is a normal sandbox named ci-<repo>-<job id>. It shows in the dashboard and in boat list while it runs. Run boat ssh <id> on a running job, or on a failed /debug job.
Public repositories
Jobs from public repositories do not run on boat by default. Anyone can open a pull request on a public repository, and its jobs would run on your bill. Turn them on per GitHub account, and list the GitHub users whose runs may use boat:- A run uses boat only when both its author and the user who started it (for example a re-run) are on the list. A pull request from someone else is refused with the reason, even when you re-run it.
--anyoneclears the list: every run uses boat, pull requests from forks too. To keep that safe, set “Require approval for all outside collaborators” in the repository’s Actions settings on GitHub.- Only the person who linked the account, or an owner or admin of its org, can change this.
Safety
- Jobs from public repositories do not run on boat unless you turn them on.
- Each job starts with your Boat environment off. The job gets no Boat environment variables, secret files, GitHub token or model provider keys. A
/from=snapshot keeps its disk, but Boat removes the owner secrets before the job starts. - Use GitHub Actions secrets for job secrets.
runs-on: boatjobs do not read a Boat environment, so values set withboat env set-varare not present. - A job runs for at most 6 hours, the GitHub limit. boat deletes any CI sandbox that outlives its job.
- A job past your start limits waits or fails. It depends on the limit.
The CLI from any CI
Each CI job creates one sandbox, runs the tests in it, and deletes it.boat exec exits with the exit code of the tests, so the job fails when the tests fail.
1. Create a CI key and a secret
Create a key with theci preset. It can create, use and delete sandboxes. Then store it as a repository secret:
boat api-key rotate <id>. See API keys.
2. Prepare a saved snapshot (one time)
Install your toolchain and dependencies once. Save the result as a saved snapshot. Each CI sandbox then starts with them in place:ci-base: a save with the same name replaces it. See Saved snapshots.
3. The workflow
.github/workflows/boat-tests.yml
Use the sandbox ID in every command. The
current alias does not work in CI: each step runs in a new shell.
Tests that run longer than 10 minutes
Give a longer--timeout, or --timeout 0 for no limit. The CLI prints the output live until the command ends, and exits with its exit code:
One command instead of the steps above
boat run creates the sandbox, copies the checkout in, runs the tests, prints the cost and deletes the sandbox. It exits with the exit code of the tests:
.gitignore does not exclude. A cancelled job deletes the sandbox too. If the runner dies, the sandbox stops by itself within 15 minutes. See boat run.
Fast apt-get: use the French Ubuntu mirror
GitHub Actions scripts often setazure.archive.ubuntu.com. From a sandbox, that mirror is slow. Use fr.archive.ubuntu.com:
Run this before
apt-get install, or put it in the saved snapshot:
Many jobs at once: start limits
Each job starts one sandbox. Your plan includes a number of starts. Create, fork and resume each count as a start.- Above the included number, a job uses an extra start.
- A matrix of 30 jobs on the $20 plan: 12 start free. With money in the wallet, the other 18 cost $0.90 and start in the same minute. Without extra starts, all 30 need about 3 minutes to start. To stay free, cap it with
strategy.max-parallel: 12. - To fail at once when no machine is free, add
--fail-fasttoboat new. Retry the job later.
What happens at a limit
This applies when no extra start can run.
A refused start does not count as a start. All limits and how to raise them: Limits.
A job that a limit stopped shows as paused in
boat ci and the CI tab, not as failed. On GitHub it shows the title “Paused by plan limit” and what you can do. It does not restart by itself, and turning on extra starts does not restart it. A full limit shows above the job list in the CI tab and first in boat ci. boat ci prints the command, and the CI tab links to the run. boat ci --all shows every job and every limit:
Cost
A job costs VM time, and an extra start when it falls above the included starts.- boat bills each second that the sandbox runs. A
smallsandbox costs $0.018 an hour. A 6-minute run costs about $0.002. A deleted sandbox costs nothing more. - The plan price comes back as VM time. A team pays the higher of the plan price and its VM time, plus its extra starts.
Worked examples
These examples use today’s prices. They assume 32 jobs per developer per workday, 22 workdays a month, 6 minutes per job ondefault, and 16% of the day’s jobs in the busiest hour.
- At 100 developers, the day goes above 1,680 included starts. 840 starts cost $0.03 and 680 cost $0.05, which is $59.20 a day.
- The same team on the $2000 plan pays $2,528.
- The busiest hour (512) is above the 420 included starts of the $500 plan. Starts in that hour that are still inside the day limit add up to $61 a month.
- At this volume, extra starts set the bill, not the job length. 2-minute
smalljobs still cost $1,802 a month. A runner that bills per minute can cost less for short jobs at this volume.
Private repositories and secrets
Aruns-on: boat job uses GitHub Actions secrets. It does not read a Boat environment.
The CLI workflow above copies the checked-out code, so its sandbox needs no GitHub access. To give those tests secrets, set them on a Boat environment and start with --environment <name>, or pass one value with -e KEY=VALUE. Check that a value arrived:
Other CI systems
The steps are the same in GitLab CI, CircleCI or Buildkite: download the binary, sign in with--key-stdin, boat new --json, boat exec, and boat delete --yes in a step that always runs. In code, use the Python or TypeScript SDK instead. Each page has the same job as boat run: create, copy the code in, run with no time limit, print the cost, delete.