Skip to main content
Two ways to run CI on boat:

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

  1. Install the boat CI GitHub App on your GitHub organization or account. Pick the repositories:
The command opens GitHub in your browser. GitHub asks you to authorize the app: boat uses that to check that you can manage the installation. GitHub lets an app add runners to one repository only with the repository permission Administration: write. If your organization cannot grant it, install Boat CI for orgs instead: on the CI tab, click Connect an organization without repo admin. It needs only the organization permission Self-hosted runners: write. Boat makes one runner group per repository, named 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:
Use the GitHub account name after --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.
  1. In your workflow, change runs-on:
GitHub Actions secrets, 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 run and docker compose work in steps.
  • services: containers (Postgres, Redis) start next to the job, on localhost.
  • 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.
Each job starts from a clean sandbox, so Docker pulls its images again. A 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:
An Android 14 emulator boots in about 25 seconds. Use 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:
The install takes about 17 seconds. On Ubuntu 24.04 the 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:
Add --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:
The CI tab in the dashboard has the same switch. It checks each name on GitHub as you type.
  • 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.
  • --anyone clears 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: boat jobs do not read a Boat environment, so values set with boat env set-var are 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 the ci preset. It can create, use and delete sandboxes. Then store it as a repository secret:
The key expires after 90 days. Rotate it with 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:
A saved snapshot keeps only the Docker images that a container uses. A plain docker pull is lost. Create a container from each image that you need, as above: docker create --name keep-<x> <image>. The container does not need to run. boat pulls registry images again at each start, so a large image adds start time. See What a snapshot saves.
10 saved snapshots are free. Run the same steps again to update ci-base: a save with the same name replaces it. See Saved snapshots.

3. The workflow

.github/workflows/boat-tests.yml
What each part does: 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:
See Background commands.

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:
The copy holds the files that git tracks and the new files that .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 set azure.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-fast to boat 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:
Run it after the job fails on GitHub, or use Re-run failed jobs on the GitHub run page.

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 small sandbox 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 on default, 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 small jobs still cost $1,802 a month. A runner that bills per minute can cost less for short jobs at this volume.
See Pricing.

Private repositories and secrets

A runs-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:
An environment that is safe for third parties withholds all your secrets. See Secrets.

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.