Skip to main content
Prepare a machine once with everything your jobs need, save it as a snapshot, and start every job from a copy of it.

Why

A job on a fresh machine repeats the same setup before it runs a single test: it installs your toolchain, restores dependency caches, and pulls the images of the services it tests against. With a snapshot, that setup runs once.
  • Each job starts with the setup on disk, so its time goes to your build and tests.
  • Each job gets its own copy, so jobs stay isolated from each other, as on a fresh machine.
  • Fewer downloads in every job, so fewer jobs fail on a registry or a mirror that is slow or down, and less cache traffic.

Set it up

You need the GitHub App connected (Run CI jobs on fresh machines), a paid plan, and a private repository with Run workflows from fork pull requests turned off.
1

Create a CI machine

Create a machine from the ci template. A job only starts from a snapshot of a ci machine.
2

Open a shell in it

3

Clone your repository

In that shell, clone the repository to ~/work/<repo>/<repo>, which is where actions/checkout puts it. A job’s checkout then only fetches what changed. acme/app stands for your repository on this page.
4

Install what your jobs install

Run the setup that your workflow runs before its tests, so that the results are on the disk. For a Node.js project, that is the dependency install.
Pull the images of the services that your tests start.
Then leave the shell.
5

Stop the machine

Stop the machine before you save it, so that everything your setup wrote is on its disks.
6

Save the snapshot

Save the snapshot under a name that you can use in a label. The command returns when the snapshot is ready.
7

Point your jobs at the snapshot

In your workflow, add -snapshot- and the snapshot’s name to the size label. The label is the job’s whole runs-on.
Keep the setup steps in the workflow. They finish fast when the snapshot already has their results, and they still do the work when a dependency changed after you saved the snapshot.
8

Check that a job used the snapshot

Push a commit, and list your jobs. The SNAPSHOT column has the snapshot’s name for a job that started from it.

Examples

Each example lists what to run in the machine before you save it, and the label that the jobs use. The commands stand for your own project’s setup.
A TypeScript monorepo with end-to-end tests installs thousands of packages and downloads browsers in every job. Put node_modules and the Playwright browsers in the snapshot.

When not to use it

  • A small repository whose setup takes a few seconds. A fresh machine is simpler, and there is no snapshot to keep up to date.
  • A workflow that changes its dependencies on every run, such as one that always installs the latest versions. The snapshot’s copies are out of date at once, so each job downloads them again.

Refresh the snapshot

Save the snapshot again when your dependencies change enough that jobs install much of them again, and at least once a month. A snapshot keeps the GitHub Actions runner that it was saved with, and GitHub stops sending jobs to a runner that is more than 30 days behind its latest release. A snapshot’s name cannot be used again while that snapshot exists, so save the new one under a new name.
Change runs-on to the new label, and delete the old snapshot when no workflow names it.

What to know

  • Each job gets its own copy. A job cannot change the snapshot, so nothing that one job writes reaches another job.
  • Keep secrets out of the snapshot. Any workflow on a branch of a linked repository can name the snapshot and read what is in it. Jobs get their secrets from GitHub Actions as usual.
  • The size is the snapshot’s. Name the size label of the machine that you saved, such as instabox-medium-snapshot- for a snapshot of an instabox-medium machine. You can also name the snapshot by its ID, as in instabox-medium-snapshot-sn_....
  • Stop services before you save. Stop any service that you started in the machine, so that the snapshot holds files and not half-written data.
  • A job from a snapshot waits for its machine to start. Machines for the plain size labels are started ahead of jobs, and machines from your snapshot are not.
  • Refreshing is a manual step today. Save the snapshot again yourself when it is due.
  • A job that names a snapshot is never moved to a fresh machine. When the snapshot is missing, still saving, or not from a ci machine, the job is refused, and instabox ci shows the reason. See When a job that names a snapshot is refused.

Run CI jobs on fresh machines

Connect GitHub, size labels, and what the machine has installed.

Snapshots

Save, list, and delete snapshots.