Why a CI build starts cold

With the exception of single-CPU runners, each GitHub-hosted runner is a new virtual machine, so the layer cache from your last run isn't sitting on the machine. Docker's docs put it this way: CI environments "usually have little-to-no persistence between runs". BuildKit can export its build cache to an external location and import it in a later build, but the cache backends have to be exported to and imported from explicitly.

The two lines that turn it on

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v4

- name: Build and push
  uses: docker/build-push-action@v7
  with:
    context: .
    push: true
    tags: <registry>/<image>:latest
    cache-from: type=gha
    cache-to: type=gha,mode=max

• cache-to exports the cache and cache-from imports it. type=gha stores it in the GitHub Actions cache.
• With docker/build-push-action, the cache server URL and token are filled in for you. If you call docker buildx build from your own run: step, you have to expose those variables yourself.
• setup-buildx-action uses the docker-container driver by default. The gha backend works with the plain docker driver only when the containerd image store is enabled.

What mode=max does

mode only applies to cache-to. In mode=min (the default), only layers that are exported into the resulting image are cached. In mode=max, layers of intermediate steps are cached too.

That matters for multi-stage builds. If your npm ci or pip install runs in an earlier stage whose layers don't end up in the final image, mode=min leaves them out of the cache, so the next run may have to install again. Docker's docs note the trade-off: a min cache is typically smaller, while a max cache is more likely to get more cache hits, and they suggest trying both.

scope= when you build several images or branches

The cache object is identified by a scope, which defaults to buildkit. If one workflow builds several images with the default scope, each build overwrites the cache of the previous one, leaving only the last one's cache. Give each image its own scope on both lines:

cache-from: type=gha,scope=api
cache-to: type=gha,mode=max,scope=api

Branches have their own boundary. A workflow run can restore caches from the current branch, the base branch and the default branch, but not from sibling or child branches. A cache created by a pull_request run belongs to the merge ref, so only re-runs of that pull request can restore it.

Size and eviction limits

From GitHub's dependency caching reference:

• Cache entries that haven't been accessed in over 7 days are removed.
• The total cache size per repository is limited, 10 GB by default. A repository administrator can raise it, and usage beyond 10 GB is billed.
• When a repository reaches its limit, GitHub deletes caches in order of last access date, oldest first. That can cause cache thrashing, where caches are created and deleted at a high rate.
• Uploads are limited to 200 per minute per repository, and downloads to 1500 per minute.

Docker notes that a mode=min cache is typically smaller, so a mode=max cache can use more of that space.

Why the cache can still miss

1. A layer above it changed. Once a layer changes, the layers after it rebuild too, even if they'd produce the same result. If COPY . . comes before your dependency install, a change to a source file invalidates the install layer. Docker's docs suggest copying the package files first, installing, then copying the rest of the project.
2. mode=min in a multi-stage build. The install stage's layers aren't in the final image, so they weren't exported.
3. Several images share one scope. The last build's cache replaced the others.
4. Branch boundaries. A feature branch can't read a sibling branch's cache, and a pull request's cache stays with that pull request.
5. The entry was evicted. It went unused for over 7 days, or the repository hit its size limit.
6. The run had read-only cache access. Events such as issue_comment and pull_request_target get read-only cache access by default when they run in the default-branch context. They can restore, but cache-to: type=gha can fail with failed to reserve cache. Populate the cache from a workflow with write access, such as a push on the default branch. If export is optional, ignore-error=true on cache-to makes export failures non-fatal.
7. You're relying on cache mounts. BuildKit doesn't preserve RUN --mount=type=cache mounts in the GitHub Actions cache by default.
8. Old tooling on a self-hosted runner. As of April 15, 2025, only GitHub's cache service API v2 is supported. Docker lists Buildx v0.21.0 and BuildKit v0.20.0 as the minimum versions. On GitHub-hosted runners, build-push-action's Buildx and BuildKit are already up to date.

Where ShipKit's kit fits

The docker-ghcr workflow in ShipKit's GitHub Actions + Docker Templates bundle uses the GitHub Actions cache for Docker layers (type=gha, mode=max). It doesn't set scope=, so if you add a second image to it, give each image its own scope as shown above. It's an example workflow to start from, so check it against the list above for your repository.

Sources (checked October 22, 2026): Docker Docs, "GitHub Actions cache" (cache backends); Docker Docs, "Cache storage backends"; Docker Docs, "Cache management with GitHub Actions"; Docker Docs, "Configuring your GitHub Actions builder"; Docker Docs, "Docker build cache"; Docker Docs, "Optimize cache usage in builds"; GitHub Docs, "Dependency caching reference"; GitHub Docs, "GitHub-hosted runners".

This post was drafted with AI tools and checked before it went out.

I make ShipKit, which gives away this guide and sells the paid GitHub Actions + Docker Templates bundle.

1. Is the workflow file on the default branch? A schedule event only triggers a workflow if the workflow file exists on the default branch, and scheduled workflows run only on the default branch, using its latest commit. A cron block that exists only on a feature branch won't start a scheduled run. Merge it into the default branch (often main).

2. Is the workflow enabled? In a public repository, GitHub disables scheduled workflows automatically when no repository activity has occurred in 60 days. Open the Actions tab, select the workflow in the left sidebar, and look for an Enable workflow button, or run gh workflow enable WORKFLOW. A commit that changes the cron line, made by a user with write access, also reactivates a deactivated scheduled workflow, and that user becomes the actor for its runs.

3. Is this repository a fork? When a public repository is forked, its scheduled workflows are disabled by default, and workflows don't run in a fork until you enable GitHub Actions in the fork's Actions tab.

4. Did you write the time in UTC? Scheduled workflows run in UTC by default. 30 12 * * 2 means 12:30 UTC on Tuesday, not 12:30 in your local time. GitHub's docs also describe an optional timezone key that takes an IANA time zone name, such as America/New_York.

5. Is the cron expression one GitHub accepts? Use POSIX cron syntax with five fields (minute, hour, day of month, month, day of week) and the operators * , - and /. GitHub Actions doesn't support the shortcuts @yearly, @monthly, @weekly, @daily, @hourly or @reboot. The shortest interval is once per 5 minutes.

6. Is it scheduled at a busy time? The schedule event can be delayed when GitHub Actions is under high load, and the start of each hour is a high-load time. If the load is high enough, some queued jobs may be dropped. GitHub suggests scheduling your workflow at a different time of the hour, for example 17 3 * * * instead of 0 3 * * *.

7. Was a scheduled run created? Filter your runs by event with gh run list --workflow your-workflow.yml --event schedule (or the REST API: GET /repos/OWNER/REPO/actions/runs?event=schedule). A run that was created but failed still appears in this list, so this tells a run that was not created apart from one that started late or failed.

8. If manual runs are also blocked: are Actions minutes available? Private repositories get a quota of free minutes. If the account has no valid payment method on file, usage is blocked once that quota is used up, and budgets can also limit spending. Check the account's billing settings.

9. Enterprise Managed Users: scheduled workflows won't run if their last actor has been deprovisioned by the identity provider.

If those checks pass: the cause may be on GitHub's end. Check GitHub's status page for Actions incidents, and keep in mind the documented note that scheduled runs can be delayed, or queued jobs dropped, under high load. In the meantime, if the workflow also has a workflow_dispatch trigger, you can start it by hand from the Actions tab.

Sources (checked October 21, 2026): GitHub Docs, "Events that trigger workflows" (schedule section); GitHub Docs, "Disabling and enabling a workflow"; GitHub CLI manual, "gh run list"; GitHub Docs, REST API "List workflow runs for a repository"; GitHub Docs, "GitHub Actions billing"; GitHub Status.

This post was drafted with AI tools and checked before it went out.

I make ShipKit, which gives away this guide and sells the paid GitHub Actions Starter Pack.