How Do I Invalidate a Snapshot?

There are two ways to invalidate a WarpBuild runner snapshot: change the alias in the snapshot.key=<alias> label so the next job finds nothing saved under the new name and boots from the base image, or delete the stored snapshot with DELETE /api/v1/snapshots/{id}. Prefer the key change: it takes effect on the very next job, it leaves the old image in place for jobs that are already running against it, and it reverts with a one-line commit or a variable edit.

Answer

A snapshot has no invalidate label and no purge flag. It is reached through an alias you pick, so the alias is the control surface. The snapshot runners documentation states the resolution rule directly: snapshot.key=<alias> boots from an existing snapshot when one is available for that alias, and when none exists the runner boots from the base image. An alias nobody has saved to therefore behaves exactly like a clean runner, which is what invalidation means in practice.

That gives you two levers with different blast radii.

Platform scope is worth confirming before you plan any of this. Snapshot runners apply to the Cloud Ubuntu part of that catalog, listed on the snapshot runners hub.

Detail

Changing the key

Snapshot behavior is requested through a dynamic label appended to the runner label with a semicolon, so the edit is inside the runs-on string:

jobs:
  build:
    runs-on: warp-ubuntu-latest-x64-4x;snapshot.key=web-app-main-2026-08-13
    steps:
      - uses: actions/checkout@v5

      - name: Install system packages
        run: |
          if [ -z "$WARPBUILD_SNAPSHOT_KEY" ]; then
            sudo apt-get update
            sudo apt-get install -y libvips-dev protobuf-compiler
          fi

      - run: npm ci
      - run: npm run build

      - name: Cleanup credentials
        run: |
          rm -rf $HOME/.ssh $HOME/.aws
          git clean -ffdx

      - uses: WarpBuilds/snapshot-save@v1
        with:
          alias: "web-app-main-2026-08-13"

The alias appears in two places, and both have to move together. The alias input of WarpBuilds/snapshot-save is required and is the name a later snapshot.key resolves against, per the action inputs in the docs. Rotating only the runs-on label gives you an alias that boots cold on every run forever, because nothing ever saves to it.

On the run right after the rotation, the runner boots from the base image, so WARPBUILD_SNAPSHOT_KEY is unset. That variable is set only on a machine created from a snapshot, which means any setup step you guarded on it runs in full, exactly as it did on the first day. The save action then publishes a fresh image under the new alias, and the run after that boots warm again.

Keeping the alias in a repository or organization variable turns invalidation into a settings change with no commit and no pull request:

jobs:
  build:
    runs-on: warp-ubuntu-latest-x64-4x;snapshot.key=${{ vars.SNAPSHOT_KEY }}
    steps:
      - uses: actions/checkout@v5
      # build steps
      - uses: WarpBuilds/snapshot-save@v1
        with:
          alias: ${{ vars.SNAPSHOT_KEY }}

Both places read the same variable, so they cannot drift apart. Editing SNAPSHOT_KEY from web-app-main-2026-08-13 to web-app-main-2026-09-01 invalidates the snapshot for every workflow that reads it, and GitHub documents the variable scoping rules in use variables.

Deleting through the API

List first to get the ID, then delete:

curl -X GET 'https://api.warpbuild.com/api/v1/snapshots' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer wkey-xxxx'

curl -X DELETE 'https://api.warpbuild.com/api/v1/snapshots/<snapshot-id>' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer wkey-xxxx'

The list response carries id, status, created_at, and the provider fields for each snapshot in the organization, and the ID from that response is the path parameter for the delete call. The reference pages are GET /snapshots and DELETE /snapshots/{id}. The key itself comes from the API keys page; the automation documentation walks through creating one and granting the ci and cache scopes that the runner and cache APIs expect.

Delete when the content of the image is the problem rather than its freshness. A leaked credential is the clearest case, because a rotation leaves the old image addressable for the remainder of its 15 days while a delete removes it now. Storage is the second case. Once the image is gone, no snapshot is available for that alias, and the documented fallback applies: the next job boots from the base image and runs normally.

Pricing the first run after invalidation

Every invalidation buys a cold run, and the price of that run is arithmetic you can do in advance. Assume a job that takes 12 minutes on a clean boot, of which 7 minutes is environment setup, and a warm boot that adds about a minute and skips the setup, so 6 minutes. Restore bills $0.04 per job and per-minute rates come from the pricing page, checked on 2026-08-13.

Every row costs the same 6 minutes of wall clock, and the money column swings with the rate. The 2 vCPU row is negative because the fixed $0.04 restore fee outweighs 6 minutes at $0.004, which is a sign that the alias was not earning its keep at that size in the first place. ARM64 labels run lower at the same sizes, $0.003 to $0.048 per minute, so their cold-run penalty is smaller again.

Pricing is purely usage based.

Storage left behind by a rotation

A key change does not remove anything. The retired snapshot keeps billing storage at $0.025 per snapshot-hour, per the pricing page, until its 15-day lifetime expires, which puts a hard ceiling on what an abandoned alias can cost.

One rotation a month on one alias is $9.00 of dead storage, which is cheaper than the engineering minute spent on a delete call. A per-branch alias scheme rotated weekly across twenty branches is $180.00, which pays for a cleanup script that lists snapshots and deletes the ones whose alias no longer appears in any workflow file.

Ordering a rotation so fewer jobs boot cold

Which jobs pay the cold-run cost depends on the pattern the repository uses. With a save-on-main workflow, only the default branch republishes, so every pull request run between the key change and the next merge boots cold. Merge the rotation to the default branch first, let that run publish the new alias, then let pull requests pick it up. With a single self-updating alias, the first run after the change is the only cold one, because that same run saves the replacement. The snapshot runners hub covers both patterns and where each one fits.

Related Questions

Does changing snapshot.key delete the old snapshot?

No. The old image stays until you delete it through the API or until the 15-day lifetime expires. Storage bills at $0.025 per snapshot-hour, per the pricing page, so an abandoned alias costs $0.60 per day and at most $9.00 before it is deleted for you. How long do runner snapshots last? covers the lifetime and what happens when an alias goes stale.

Where do I find the snapshot ID for the delete call?

GET https://api.warpbuild.com/api/v1/snapshots lists the snapshots in your organization with their id, status, and created_at fields, and you pass the ID you want removed to DELETE /snapshots/{id} with the same API key. Create the key on the API keys page as described in the automation documentation.

What does the first run after invalidation cost?

The next job that asks for the new alias boots from the base image and repeats its setup. On warp-ubuntu-latest-x64-16x at $0.032 per minute, a 12-minute cold job costs $0.384 against $0.232 for the 6-minute warm job plus the $0.04 restore fee, so the invalidation costs $0.152 and 6 minutes of wall clock on that one run. Per-minute rates for every label are on the pricing page, and VM snapshot defines the underlying term.