Bake stable dependencies into runner images

Prepare versioned system dependencies and build downloads once in the runner image instead of installing them on every job.

View in Markdown

Prompt

Evaluate and apply this CI technique to my repository: Bake stable dependencies into runner images.

Prepare versioned system dependencies and build downloads once in the runner image instead of installing them on every job.

Read the technique and its source-backed company examples: https://starsling.dev/ci-playbooks/techniques/prebuild-runner-images.md

Inspect this repository’s CI workflows, build and test commands, dependencies, and recent run timings. Identify where this technique applies and explain the expected benefit using this repository’s evidence.
Measure a baseline from recent comparable runs: elapsed time, queue time, runner minutes and failures where available. If data is unavailable, say what cannot be measured.
Compare relevant company approaches, checking prerequisites, platform differences and tradeoffs. Rank applicable options by evidence, fit and measurable opportunity; do not present company results as predictions for this repo.
Recommend the smallest safe change, show what checks and fallback paths remain, and ASK ME WHICH CHANGE TO APPROVE BEFORE EDITING ANY FILES.
Only after approval, work on a new feature branch, make one reversible change, and open a reviewable pull request. Never merge or push to a default or protected branch.
Keep required checks, test coverage, deployment and release behavior intact. Validate the change and compare equivalent runs where possible; report limitations and what should be monitored after merge.

View all playbooks

How companies used this technique

Read what each company changed and follow the original sources.

Bake versioned build downloads into the runner image

Bun bakes a read-only prefetch store of its dependency tarballs, WebKit prebuilt and zig compiler into its build images. A build copies a prefetched file when its URL matches and downloads from the network when a version has changed.

Before the change every CI build downloaded about 18 archive tarballs, a 200 MB WebKit prebuilt and a zig compiler before compiling. Source

Use it when: Builds on fresh runners download the same large, versioned inputs on every run, and you control the runner image.
Before applying it: Entries are keyed by exact URL or version, so a bumped dependency downloads fresh until the image is refreshed.

Bake stable system dependencies into the CI image

Each API test shard spent 7 to 8 seconds installing the same Postgres client with apt. Linear moved it into a small CI base image with Node and the client, and later added the native build headers whose downloads could occasionally hang.

Together, the CI base image, the filtered install and dropping the node_modules cache reduced per-shard setup time by roughly 44%, from 110-140 seconds to 67-73 seconds. Source

Use it when: Multiple jobs repeat stable OS-package setup on equivalent environments.
Before applying it: Pin and rebuild the image, patch vulnerabilities and measure image-pull cost. Repository secrets and mutable build outputs do not belong in the image.

How companies used this technique

Bake versioned build downloads into the runner image

Bake stable system dependencies into the CI image

Related techniques

Reuse downloaded tools across runs

Reduce the setup floor before increasing shard count

Cache package downloads and dependency stores

Company Playbooks

Related guides

Cache workflow dependencies

Cut repeated test setup

Share setup steps across jobs

Optimize npm installs

Optimize pnpm installs

Filter workflows by changed files