pin-images

name

pin-images

description

Audit and refresh the digest pins for the Docker base images referenced by `FROM` in `docker/*/Dockerfile`, with a supply-chain cooldown that refuses freshly-rebuilt digests. The image tag (`golang:1.26.5-alpine`) is the version source of truth and is owned by `go-upgrade` / `tools-upgrade` / `make sync-versions` — this skill NEVER changes tags, only the trailing `@sha256:...` digest. `docker/images-pin.toml` is the resolved `image:tag → digest` lockfile (SSOT), driven by `make pin-images-resolve` / `pin-images-apply` / `pin-images-check` (backed by `scripts/pin-images`). `resolve` re-resolves each tag's current digest via `docker buildx imagetools inspect` and quarantines any whose image-config `created` is younger than `PIN_IMAGES_MIN_AGE_DAYS` (default 14; pass `days=N` to override, `0` disables). Because a mutable tag has no queryable history, the step-back target is the tool's own prior lock entry; on bootstrap a still-fresh image is left tag-only and reported with its re-run date. Verifies with `make pin-images-check` + `make docker-lint` (hadolint). Sibling of `actions-pin` (which pins GitHub Actions `uses:`). Use on a routine cadence, after a base-image / registry security advisory, or to pin an image that was previously quarantined once it has aged.

Docker Base Image Pin Refresh

This skill audits and refreshes the digest pins of the FROM base images in docker/*/Dockerfile, with a supply-chain cooldown gate: a digest whose image-config created timestamp is newer than the exclusion window (PIN_IMAGES_MIN_AGE_DAYS, default 14) is never adopted. A freshly-published (possibly compromised) rebuild is thus never pulled in before upstream has time to detect and revoke it.

It is the sibling of actions-pin — that skill pins GitHub Actions uses: to commit SHAs; this one pins Docker base images to digests. They share the same cooldown philosophy but operate on different SSOTs.

The tag is not this skill's to change. golang:1.26.5-alpine, node:24.18.0-alpine, etc. are version-pinned by make sync-versions (from mise.toml) and bumped by go-upgrade / tools-upgrade. This skill only manages the @sha256:... digest that follows the tag. Never edit a tag here — if a version bump is needed, stop and defer to the owning skill.

A Japanese reference translation is available at SKILL.ja.md in the same directory (not loaded as a skill; for human reference only).

How Pinning Works in This Repo

Read this before doing anything — the mechanism determines every step below. Read the actual scripts/pin-images/main.go and .makefiles/docker/pin.mk at runtime; this section is the summary, the code is the source of truth.

• Each base image is pinned as FROM image:tag@sha256:<hex> [AS <stage>]. The tag is the version source of truth; the @sha256 digest is the immutability lock.
• docker/images-pin.toml is the lockfile: "image:tag" = "sha256:<hex>" (SSOT for apply, regenerated by resolve).
• make pin-images-resolve — collects every FROM image:tag, resolves its current digest via docker buildx imagetools inspect, applies the cooldown, and rewrites the lockfile. Env PIN_IMAGES_MIN_AGE_DAYS (default 14) controls the gate.
• make pin-images-apply — normalizes each FROM to image:tag@<digest> from the lockfile. Quarantined images (absent from the lockfile) are normalized back to tag-only — apply strips a stale digest, so the lockfile is the single source of truth.
• make pin-images-check — verifies FROM matches the lockfile without writing (CI / hook); network-free (reads lockfile + Dockerfiles only). The CI gate is .github/workflows/pin-images-check.yaml.

The Cooldown & Quarantine Rule (core of this skill)

For each image:tag (N = exclusion days, cutoff = now - N days):

1. Aged → adopt. If the current digest's image-config created is older than the cutoff → write it to the lockfile; apply pins it.
2. Fresh, with a prior lock → keep prior. If the current digest is inside the window but the lockfile already has an entry for this image:tag → keep the existing (older, already-vetted) pin, and report the quarantine.
3. Fresh, no prior lock (bootstrap) → tag-only. If the current digest is inside the window and there is no prior lock entry → leave the image absent from the lockfile; apply keeps it on the tag. Report it with the date it becomes adoptable (created + N days).

Why this differs from actions-pin: a Git tag/release has an enumerable, immutable history, so actions-pin can step back to an older exact version. A mutable image tag has no queryable history — the registry only answers "what does this tag point to now." So the only step-back target is the tool's own prior lock entry (rule 2). On first-ever pin there is nothing to step back to, hence rule 3 leaves it tag-only rather than adopting a fresh (unvetted) digest.

Official images are rebuilt often (base-OS CVE patches), so a fresh current digest is common and quarantine is expected, not an error.

When to Use

• Routine periodic refresh of the base-image digest pins.
• After a base-image or registry supply-chain advisory.
• To pin an image that a previous run left quarantined, once it has aged past the window.

Do NOT use this skill for:

• Bumping an image version/tag (Go/node/python runtime) — use /go-upgrade or /tools-upgrade (+ make sync-versions).
• GitHub Actions uses: pins — use /actions-pin.
• Dockerfile lint findings — use make docker-lint.

Arguments

Parse the invocation arguments (order-independent):

Token	Meaning	Default
a bare integer, or days=N (or --days N)	Exclusion window in days = PIN_IMAGES_MIN_AGE_DAYS.	14

Examples: /pin-images (14d) · /pin-images 30 (30d) · /pin-images days=7.

The exclusion days must be a non-negative integer. 0 disables the cooldown (adopt even brand-new digests) — only honor it when the user explicitly passes 0, and surface the supply-chain risk.

AI Modification Scope

Per the "Exception: Skill Execution" clause in CLAUDE.md, the following paths may be modified while this skill runs (this skill touches the sensitive docker/ area — that is intentional and scoped to pinning only):

• docker/*/Dockerfile — the @sha256:... digest on FROM lines (written by make pin-images-apply)
• docker/images-pin.toml — the lockfile (written by make pin-images-resolve)

The following remain protected even during skill execution:

• AGENTS.md / CLAUDE.md
• Generated files (**/*.gen.go, *.sql.go, *_mock.go, **/openapi.gen.yaml, generated content under docs/)
• Any file unrelated to the digest pin. Do NOT change a FROM tag, RUN/COPY steps, or scripts/pin-images — if a tag bump is needed, surface it and stop.

Execution Steps

0. Pre-flight: vendor consistency + registry access

make pin-images-* runs go run ./scripts/pin-images, which compiles against vendor/. vendor/ is gitignored, so a parallel checkout can leave it inconsistent with the current branch's go.mod, failing with vendor/modules.txt: ... inconsistent. If so, run go mod vendor once, then proceed.

resolve calls docker buildx imagetools inspect, which hits the registry. Docker Hub's anonymous pull rate limit returns 429 Too Many Requests after a burst. If resolve fails with 429, have the user authenticate (raises the limit) — suggest they type ! docker login in the prompt — then retry. apply / check are network-free and unaffected.

1. Parse Arguments and Inventory

Parse the arguments into <N> (exclusion days). Then:

• Read docker/images-pin.toml for the current image:tag → digest set.
• Grep FROM across docker/*/Dockerfile to map each base image to its file locations and tag (note images referenced in multiple stages / files — e.g. golang:*-alpine appears in several stages).

2. Resolve

make pin-images-resolve PIN_IMAGES_MIN_AGE_DAYS=<N>   # the parsed exclusion days

resolve re-resolves every image:tag and prints ⚠️ ... のため既存ピンを維持 (rule 2) or ⚠️ ... tag のまま skip (rule 3) for any inside the window — expected, not a failure. Note each quarantined image and, for bootstrap skips, compute its adoptable date (created + N days) from the warning's age.

3. Apply

make pin-images-apply

Normalizes every FROM from the lockfile (aged images gain / refresh @sha256:...; quarantined images are stripped back to tag-only).

4. Verify

make pin-images-check     # FROM matches lockfile (network-free)
make docker-lint          # hadolint over docker/*/Dockerfile

Report OK / FAIL per command. Do NOT auto-roll-back on failure — the user decides.

5. Final Report

Summarize in Japanese: images newly pinned / digest-refreshed (with the digest age), images quarantined (rule 2 kept-prior / rule 3 tag-only, each with reason and — for tag-only — the adoptable date), and verification result. List quarantined images so the user knows to re-run this skill once they age. Do NOT commit, stage, or push — the user runs /commit (these changes are CI:- or Build:-prefixed) manually.

Notes

• The tag is off-limits. This skill only moves digests. A version bump is go-upgrade / tools-upgrade + make sync-versions.
• Quarantine is normal, not a failure. Official base images rebuild frequently, so a fresh current digest is common; the gate keeps the prior aged pin (or tag-only on bootstrap) rather than adopting it.
• A fast-moving tag can stall. If a tag is rebuilt more often than every N days, the current digest is always fresh and the pin never advances past the last aged one. That is the accepted cooldown cost; lower N deliberately (and note the risk) only if a security patch must be adopted sooner.
• Multi-arch digest. resolve pins the top-level image-index digest (Docker resolves the per-platform manifest from it), and reads the earliest per-platform created for the age check (most conservative).
• check is network-free. It reads the lockfile + Dockerfiles only, so it is safe as a CI / pre-commit gate even without registry access.
• Enforcement. The local gate is the lefthook pin-images pre-commit hook (glob-filtered to docker/**/Dockerfile + docker/images-pin.toml) plus the pin-images-check.yaml CI workflow — both mirror pin-actions. Escalating to a required status check (a hard merge block via the branch ruleset) is intentionally left to the downstream template consumer: the boilerplate ships the check, not the mandate. Note a path-filtered workflow made a required check blocks PRs that do not touch those paths, so that escalation also needs an always-run adjustment — another reason it is deferred to the consumer.
• Idempotency: a second apply is a no-op and pin-images-check passes.
• The skill never auto-pushes.

Checklist

Confirm before reporting completion:

• Exclusion days <N> parsed (default 14)
• vendor/ consistency ensured (go mod vendor if needed); registry reachable (docker login if 429)
• Current pins inventoried from images-pin.toml + FROM grep
• make pin-images-resolve PIN_IMAGES_MIN_AGE_DAYS=<N> run; quarantined images noted with reason + adoptable date
• make pin-images-apply run
• make pin-images-check + make docker-lint run and reported
• No FROM tag changed (digest-only); held / quarantined images left tag-only
• Quarantined images listed for later re-run once aged
• After updating SKILL.md, also update SKILL.ja.md to keep the Japanese translation in sync
• No commit / stage / push performed