Skip to content

document signed GitHub Actions cache reuse #199

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
crazy-max wants to merge 1 commit into
base: main
Choose a base branch
from
+29 −5
Open

document signed GitHub Actions cache reuse #199

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 29 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ ___
* [Secrets](#secrets-1)
* [Outputs](#outputs-1)
* [Notes](#notes)
* [Signed GitHub Actions cache](#signed-github-actions-cache)
* [Runner mapping](#runner-mapping)
* [Metadata templates](#metadata-templates)

Expand Down Expand Up @@ -48,7 +49,7 @@ jobs:
uses: docker/github-builder/.github/workflows/build.yml@v1
permissions:
contents: read # to fetch the repository content
id-token: write # for signing attestation(s) with GitHub OIDC Token
id-token: write # for signing attestations and cache entries with GitHub OIDC
with:
output: image
push: ${{ github.event_name != 'pull_request' }}
Expand Down Expand Up @@ -79,8 +80,10 @@ toward higher levels of security and trust.
* **Optimized cache warming & reuse.**
The builder can use the GitHub Actions cache backend to persist layers across
branches, PRs, and rebuilds. This significantly reduces cold-start times and
avoids repeating expensive dependency installations, even for external
contributors' pull requests.
avoids repeating expensive dependency installations. With GitHub OIDC
available, cache entries are signed and verified before reuse so warm-cache
builds do not accept unauthenticated cache contents as build inputs. See
[Signed GitHub Actions cache](#signed-github-actions-cache).

* **Centralized build configuration.**
Repositories no longer need to configure buildx drivers, tune storage, or
Expand Down Expand Up @@ -118,6 +121,13 @@ toward higher levels of security and trust.
preventing untrusted workflow steps from modifying build logic, injecting
unexpected flags, or producing misleading provenance.

* **Signed cache reuse.**
GitHub Actions cache storage is repository-scoped but writable by actors who
Copy link
Copy Markdown
Member

@tonistiigi tonistiigi May 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This could use some editing for better clarity. It is not really obvious that when you say "writable by actors" then this doesn't apply to this workflow.

Better to start with something like. "All cache produced by this action is signed and verified before importing. This is because ..."

can write workflows in the consuming repository. The reusable workflows use
signed GitHub Actions cache support when GitHub OIDC is available, preventing
cache entries produced outside the trusted workflow from being restored. See
[Signed GitHub Actions cache](#signed-github-actions-cache).

### Isolation & Reliability

* **Separation between user CI logic and build logic.**
Expand Down Expand Up @@ -172,7 +182,7 @@ jobs:
uses: docker/github-builder/.github/workflows/build.yml@v1
permissions:
contents: read # to fetch the repository content
id-token: write # for signing attestation(s) with GitHub OIDC Token
id-token: write # for signing attestations and cache entries with GitHub OIDC
with:
output: image
push: ${{ github.event_name != 'pull_request' }}
Expand Down Expand Up @@ -286,7 +296,7 @@ jobs:
uses: docker/github-builder/.github/workflows/bake.yml@v1
permissions:
contents: read # to fetch the repository content
id-token: write # for signing attestation(s) with GitHub OIDC Token
id-token: write # for signing attestations and cache entries with GitHub OIDC
with:
output: image
push: ${{ github.event_name != 'pull_request' }}
Expand Down Expand Up @@ -368,6 +378,20 @@ with `builder-outputs: ${{ toJSON(needs.<job_id>.outputs) }}`.

## Notes

### Signed GitHub Actions cache

GitHub Actions cache is scoped to a repository, but repository writers can still
create cache entries. That matters for these reusable workflows because the
Docker-owned workflow is the trusted build boundary. Without verification, a
poisoned BuildKit cache could influence a later trusted build, which is the SLSA
isolation concern described in [docker/github-builder#56](https://github.com/docker/github-builder/issues/56).

When the workflow has GitHub OIDC available through `id-token: write`, BuildKit
signs cache entries with Cosign and requires restored cache entries to match the
expected workflow identity and source repository policy. This preserves cache
warming and reuse while preventing repository-writable cache storage from
becoming an unauthenticated input to the trusted build.

### Runner mapping

The `runner` input accepts either a single GitHub-hosted Linux runner label or a
Expand Down