Buildkite Cache is generally available

Buildkite Cache is now generally available on hosted and self-hosted agents. It gives every job a way to reuse work an earlier job already did, from a dependency download to an entire build command. It's built into the Buildkite agent as buildkite-agent cache commands you can call anywhere in a pipeline.

Save and restore anything

Define a cache in .buildkite/cache.yml, or any file you pass with --cache-config-file, with a key built from the inputs that matter, such as a lockfile checksum, the OS or the architecture. Run buildkite-agent cache restore before the work and buildkite-agent cache save after it.

steps:
  - label: "Install"
    command:
      - buildkite-agent cache restore --name npm
      - npm ci
      - buildkite-agent cache save --name npm

If there's no entry for the exact key, such as after a lockfile change, restore can fall back to a recent one. Mark a key part with fallback_limit, and restore takes the newest entry that matches every part up to it. A dependency bump then starts warm, and your package manager only fetches what changed. A cache miss doesn't fail the job. By default, save and restore skip per-cache errors unless you set --cache-fail-on-error. Configuration-loading errors and failures while cleaning or extracting into target paths still stop the job, because a failed restore may leave those paths partially modified.

Decide who can write to the cache

Every cluster has cache registries, and each registry has a policy. By default, every job in the cluster shares entries by key. Cache policies let your platform team control, in one place, which builds can restore what others have saved, so untrusted code, like a pull request from a fork, can't put anything into the cache your main and release builds rely on. Policies scope entries by pipeline, branch and build, and can add rules with CEL conditions, all from cluster settings without editing a single pipeline.

Skip work entirely with cache exec

buildkite-agent cache exec uses the same keys, stores and policies to cache the result of a whole command. Give the command a cache keyed on the files it reads, and list the files it writes:

caches:
  - name: frontend_build
    cache_key:
      - frontend_build
      - checksum: ["src/**", "index.html", "public/**", "package-lock.json", "vite.config.ts"]
    target_paths:
      - dist

Then wrap the command:

steps:
  - label: "Build"
    command: buildkite-agent cache exec --name frontend_build -- vite build

When src/, index.html, public/, the lockfile and the Vite config match an earlier successful run, vite build doesn't run at all. The agent restores dist/, replays the original log output, and the log group tells you how much time it saved. When they don't match, the command runs and its outputs and log are saved together for next time. Only an exact key match is replayed, and a failed run saves nothing.

Get started

Hosted agents have a cache store ready with no setup. Self-hosted agents use your own Amazon S3 or S3-compatible bucket. You need agent v4.0.3 or later, and v4.2.1 or later for cache exec.

Start with the dependency install your pipeline repeats most, then try cache exec on a build or check whose inputs rarely change. The Buildkite Cache guide walks through both.

Have questions or need help? Reach out to us at support@buildkite.com.