tools/bump: lock actions with gh-actions-lock

Workflows name release tags; actions.lock holds the commits. Bump moves
tags then relocks, and now reads .github/actions. Verify checks the lock.
This commit is contained in:
Kristoffer Dalby committed 2026-11-12 14:03:30 +01:00
1 parent 875f9f977c
commit 44e831e1fa
6 files changed
+248 -118

No files matched your search

+8 -1
View File
@@ -281,7 +281,7 @@ Key reminders:
day. `bump plan` reports what is stale without touching anything; `bump verify`
exits non-zero when the pins no longer agree.
Three rules it encodes. A hand-written bump has to follow them too:
Four rules it encodes. A hand-written bump has to follow them too:
1. **`modernc.org/libc` moves only to the version `modernc.org/sqlite`
requires**, and **`gvisor.dev/gvisor` only to the version `tailscale.com`
@@ -298,6 +298,13 @@ Three rules it encodes. A hand-written bump has to follow them too:
command then downloads one, so `go build` succeeds locally. The nix builders
set `GOTOOLCHAIN=local` and fail. `bump verify` reports the drift; the tool
never edits the directive itself.
4. **Actions are named by release tag; the commit lives in
`.github/workflows/actions.lock`.** After changing any `uses:`, in a workflow
or in `.github/actions/`, run `gh-actions-lock` (in the dev shell) and commit
the lockfile with it; GitHub runs the locked commit and the
`check-generated` workflow fails a stale lockfile. Same-repo actions are
written `$/.github/actions/...`, not `./`, so the lockfile covers what they
use. Never pass `--accept-moved`: a release tag that moved needs a human.
The tool does not encode one more rule: the DNS providers (`github.com/libdns/*`)
and `github.com/caddyserver/certmagic` must agree on the `github.com/libdns/libdns`
+1
View File
@@ -141,6 +141,7 @@
gotools
gh
gh-actions-lock
ksh
ko
yq-go
+133 -74
View File
@@ -7,33 +7,43 @@ import (
"regexp"
"sort"
"strings"
"gopkg.in/yaml.v3"
)
// actionPin matches a SHA-pinned action reference together with the trailing
// comment that says which version the SHA is. Both have to move, or the comment
// starts lying about what is running.
var actionPin = regexp.MustCompile(
`(?m)(uses:\s+)([\w.-]+)/([\w.-]+)((?:/[\w./-]+)?)@([0-9a-f]{40})(\s+#\s*)(\S+)`)
// actionsLock records the commit every action ref runs. Workflows name a
// readable tag; GitHub runs the commit locked here and rejects one that is
// missing or no longer reachable from that tag.
const actionsLock = ".github/workflows/actions.lock"
// isVersionRef reports whether a pin comment names a release rather than a
// branch. A branch pin is deliberate and keeps following that branch.
// actionRef matches a remote action and the ref it names. Local `./` and `$/`
// actions never match: they run from this repository's own commit.
var actionRef = regexp.MustCompile(`(?m)(uses:\s+)([\w.-]+)/([\w.-]+)((?:/[\w./-]+)?)@([\w.-]+)`)
// isVersionRef reports whether a ref names a release rather than a branch. A
// branch ref is deliberate; the lockfile advances it on --relock.
func isVersionRef(ref string) bool {
return strings.HasPrefix(ref, "v") && len(ref) > 1 && ref[1] >= '0' && ref[1] <= '9'
}
// workflowFiles lists the workflow definitions, which is the only place action
// pins live.
func workflowFiles(r *repo) ([]string, error) {
// actionFiles lists every file that can name a remote action: the workflows
// and this repository's composite actions, whose pins the lockfile also holds.
func actionFiles(r *repo) ([]string, error) {
var files []string
for _, ext := range []string{"*.yml", "*.yaml"} {
matches, err := filepath.Glob(r.path(".github", "workflows", ext))
for _, pattern := range []string{".github/workflows/*.y*ml", ".github/actions/*/action.y*ml"} {
matches, err := filepath.Glob(r.path(pattern))
if err != nil {
return nil, fmt.Errorf("listing workflows: %w", err)
return nil, fmt.Errorf("listing %s: %w", pattern, err)
}
for _, m := range matches {
files = append(files, filepath.Join(".github", "workflows", filepath.Base(m)))
rel, err := filepath.Rel(r.Root, m)
if err != nil {
return nil, err
}
files = append(files, rel)
}
}
@@ -42,46 +52,23 @@ func workflowFiles(r *repo) ([]string, error) {
return files, nil
}
// actionTarget is where one action should end up.
type actionTarget struct {
SHA string
Ref string
}
// resolveAction decides what a pin should point at. A release pin follows the
// newest release; a branch pin follows that branch's head.
func resolveAction(ctx context.Context, owner, name, ref string) (actionTarget, error) {
want := ref
if isVersionRef(ref) {
latest, err := latestRelease(ctx, owner, name)
if err != nil {
return actionTarget{}, err
}
want = latest
}
sha, err := commitOfRef(ctx, owner, name, want)
if err != nil {
return actionTarget{}, err
}
return actionTarget{SHA: sha, Ref: want}, nil
}
// applyActions refreshes every SHA-pinned action reference. This replaces the
// separate actions-version workflow, so there is one bot, one token and one
// pull request to review.
// applyActions moves every release ref to the newest release, then has
// gh-actions-lock resolve the commits. The lock tool, not this one, owns SHAs:
// it also locks transitive actions and checks the repository identity.
func applyActions(ctx context.Context, r *repo) (change, error) {
files, err := workflowFiles(r)
files, err := actionFiles(r)
if err != nil {
return change{}, err
}
lockBefore, err := r.readFile(actionsLock)
if err != nil {
return change{}, err
}
// One lookup per action, not per occurrence: checkout alone appears twenty
// times, and the API budget is not unlimited.
resolved := map[string]actionTarget{}
latest := map[string]string{}
moved := map[string]string{}
var touched []string
@@ -92,7 +79,7 @@ func applyActions(ctx context.Context, r *repo) (change, error) {
return change{}, err
}
updated, err := rewriteActions(ctx, content, resolved, moved)
updated, err := rewriteActions(ctx, content, latest, moved)
if err != nil {
return change{}, err
}
@@ -106,65 +93,90 @@ func applyActions(ctx context.Context, r *repo) (change, error) {
return change{}, err
}
touched = append(touched, filepath.Base(file))
touched = append(touched, file)
}
if len(moved) == 0 {
// --relock also advances branch refs, which no tag rewrite can see. Never
// --accept-moved: a release tag that moved is for a human to look at.
_, err = r.nixRun(ctx, "gh-actions-lock", "--no-interactive", "--relock")
if err != nil {
return change{}, err
}
lockAfter, err := r.readFile(actionsLock)
if err != nil {
return change{}, err
}
if len(touched) == 0 && lockAfter == lockBefore {
return change{Empty: true}, nil
}
details := make([]string, 0, len(moved))
relocked, err := lockMoves(lockBefore, lockAfter)
if err != nil {
return change{}, err
}
details := make([]string, 0, len(moved)+len(relocked)+1)
for _, line := range moved {
details = append(details, line)
}
sort.Strings(details)
details = append(details, relocked...)
return change{
Summary: fmt.Sprintf("%d action pins", len(moved)),
Detail: append(details, "files: "+strings.Join(touched, ", ")),
}, nil
summary := fmt.Sprintf("%d action pins", len(moved)+len(relocked))
if len(details) == 0 {
// The lock tool rewrote the file without moving a commit, such as
// after its own upgrade changed the format.
summary = "the actions lockfile"
}
if len(touched) > 0 {
details = append(details, "files: "+strings.Join(touched, ", "))
}
return change{Summary: summary, Detail: details}, nil
}
// rewriteActions rewrites every pin in one file, recording what moved.
func rewriteActions(ctx context.Context, content string, resolved map[string]actionTarget, moved map[string]string) (string, error) {
// rewriteActions moves every release ref in one file to the newest release,
// recording what moved.
func rewriteActions(ctx context.Context, content string, latest, moved map[string]string) (string, error) {
var failure error
updated := actionPin.ReplaceAllStringFunc(content, func(match string) string {
m := actionPin.FindStringSubmatch(match)
owner, name, sub, sha, sep, ref := m[2], m[3], m[4], m[5], m[6], m[7]
updated := actionRef.ReplaceAllStringFunc(content, func(match string) string {
m := actionRef.FindStringSubmatch(match)
owner, name, sub, ref := m[2], m[3], m[4], m[5]
key := owner + "/" + name + "@" + ref
if !isVersionRef(ref) {
return match
}
target, ok := resolved[key]
slug := owner + "/" + name
want, ok := latest[slug]
if !ok {
var err error
target, err = resolveAction(ctx, owner, name, ref)
want, err = latestRelease(ctx, owner, name)
if err != nil {
// One unreachable action must not abandon the rest; record it
// and leave that pin where it is.
// and leave that ref where it is.
failure = err
return match
}
resolved[key] = target
latest[slug] = want
}
if target.SHA == sha {
if want == ref {
return match
}
if ref == target.Ref {
// A branch pin keeps its name; only the commit under it moved.
moved[owner+"/"+name] = fmt.Sprintf("%s/%s %s %s -> %s",
owner, name, ref, sha[:7], target.SHA[:7])
} else {
moved[owner+"/"+name] = fmt.Sprintf("%s/%s %s -> %s", owner, name, ref, target.Ref)
}
moved[slug] = fmt.Sprintf("%s %s -> %s", slug, ref, want)
return m[1] + owner + "/" + name + sub + "@" + target.SHA + sep + target.Ref
return m[1] + slug + sub + "@" + want
})
if failure != nil && len(moved) == 0 {
@@ -174,6 +186,53 @@ func rewriteActions(ctx context.Context, content string, resolved map[string]act
return updated, nil
}
// lockMoves reports the refs that kept their name while the commit under them
// moved: a branch the relock advanced. A tag move shows up as a new entry
// instead, and rewriteActions already reported it.
func lockMoves(before, after string) ([]string, error) {
pre, err := lockedCommits(before)
if err != nil {
return nil, err
}
post, err := lockedCommits(after)
if err != nil {
return nil, err
}
var moves []string
for ref, commit := range post {
if old, ok := pre[ref]; ok && old != commit {
moves = append(moves, fmt.Sprintf("%s %s -> %s", ref, short(old), short(commit)))
}
}
sort.Strings(moves)
return moves, nil
}
// lockedCommits maps each lockfile entry to the commit it runs.
func lockedCommits(content string) (map[string]string, error) {
var lock struct {
Dependencies map[string]struct {
Commit string `yaml:"commit"`
} `yaml:"dependencies"`
}
if err := yaml.Unmarshal([]byte(content), &lock); err != nil { //nolint:noinlineerr
return nil, fmt.Errorf("parsing %s: %w", actionsLock, err)
}
commits := make(map[string]string, len(lock.Dependencies))
for ref, dep := range lock.Dependencies {
commits[ref] = strings.TrimPrefix(dep.Commit, "sha1-")
}
return commits, nil
}
func actionAreas() []area {
return []area{{
Name: "actions",
+94 -24
View File
@@ -1,46 +1,52 @@
package main
import "testing"
import (
"slices"
"testing"
)
func TestActionPinMatch(t *testing.T) {
func TestActionRefMatch(t *testing.T) {
tests := []struct {
name string
line string
owner, repo, sub string
sha, ref string
ref string
match bool
}{
{
name: "sha pinned with version comment",
line: " - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1\n",
name: "release tag",
line: " - uses: actions/checkout@v7.0.1\n",
owner: "actions", repo: "checkout",
sha: "8e8c483db84b4bee98b60c0593521ed34d9990e8",
ref: "v6.0.1",
ref: "v7.0.1",
match: true,
},
{
name: "branch comment",
line: " - uses: NixOS/nix-installer-action@6b8548fe06acfb0155a50ab5d561accb215764cc # main\n",
owner: "NixOS", repo: "nix-installer-action",
sha: "6b8548fe06acfb0155a50ab5d561accb215764cc",
ref: "main",
name: "action in a subdirectory",
line: " uses: mitchellh/vouch/action/check-pr@v1.5.0\n",
owner: "mitchellh", repo: "vouch", sub: "/action/check-pr",
ref: "v1.5.0",
match: true,
},
{
// No SHA to replace and no comment to correct; leave it alone
// rather than silently changing how it is pinned.
name: "unpinned branch reference",
line: " uses: alexellis/setup-sshd-actor@master\n",
name: "branch",
line: " uses: self-actuated/block-with-tmux@master\n",
owner: "self-actuated", repo: "block-with-tmux",
ref: "master",
match: true,
},
{
name: "local reusable workflow",
line: " uses: ./.github/workflows/integration-test-template.yml\n",
},
{
name: "same-repo action",
line: " uses: $/.github/actions/headscale-up\n",
},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
m := actionPin.FindStringSubmatch(test.line)
m := actionRef.FindStringSubmatch(test.line)
if (m != nil) != test.match {
t.Fatalf("match = %v, want %v", m != nil, test.match)
}
@@ -49,7 +55,7 @@ func TestActionPinMatch(t *testing.T) {
return
}
for i, want := range map[int]string{2: test.owner, 3: test.repo, 4: test.sub, 5: test.sha, 7: test.ref} {
for i, want := range map[int]string{2: test.owner, 3: test.repo, 4: test.sub, 5: test.ref} {
if m[i] != want {
t.Errorf("group %d = %q, want %q", i, m[i], want)
}
@@ -58,15 +64,79 @@ func TestActionPinMatch(t *testing.T) {
}
}
func TestActionPinRewrite(t *testing.T) {
const line = " - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1\n"
func TestRewriteActions(t *testing.T) {
const content = ` steps:
- uses: actions/checkout@v7.0.1
with:
persist-credentials: false
- uses: mitchellh/vouch/action/check-pr@v1.5.0
- uses: self-actuated/block-with-tmux@master
- uses: $/.github/actions/headscale-up
`
m := actionPin.FindStringSubmatch(line)
got := m[1] + m[2] + "/" + m[3] + m[4] + "@" + "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + m[6] + "v7.0.0"
const want = ` steps:
- uses: actions/checkout@v7.1.0
with:
persist-credentials: false
- uses: mitchellh/vouch/action/check-pr@v1.5.0
- uses: self-actuated/block-with-tmux@master
- uses: $/.github/actions/headscale-up
`
// Pre-resolved, so the test needs no network; the branch is never looked up.
latest := map[string]string{"actions/checkout": "v7.1.0", "mitchellh/vouch": "v1.5.0"}
moved := map[string]string{}
got, err := rewriteActions(t.Context(), content, latest, moved)
if err != nil {
t.Fatal(err)
}
const want = "uses: actions/checkout@aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa # v7.0.0"
if got != want {
t.Errorf("rewrite = %q, want %q", got, want)
t.Errorf("rewrite =\n%s\nwant\n%s", got, want)
}
if len(moved) != 1 || moved["actions/checkout"] != "actions/checkout v7.0.1 -> v7.1.0" {
t.Errorf("moved = %v", moved)
}
}
func TestLockMoves(t *testing.T) {
const before = `version: 'v0.0.3'
dependencies:
'actions/checkout@v7.0.1':
ref: 'v7.0.1'
commit: 'sha1-3d3c42e5aac5ba805825da76410c181273ba90b1'
'self-actuated/block-with-tmux@master':
ref: 'master'
commit: 'sha1-4d7a7ea0000000000000000000000000000000000'
'mic92/hestia@v3.1.0':
ref: 'v3.1.0'
commit: 'sha1-dfed9ced335d28978ba74e513939a10db1f71025'
`
const after = `version: 'v0.0.3'
dependencies:
'actions/checkout@v7.1.0':
ref: 'v7.1.0'
commit: 'sha1-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'
'self-actuated/block-with-tmux@master':
ref: 'master'
commit: 'sha1-bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb'
'mic92/hestia@v3.1.0':
ref: 'v3.1.0'
commit: 'sha1-dfed9ced335d28978ba74e513939a10db1f71025'
`
got, err := lockMoves(before, after)
if err != nil {
t.Fatal(err)
}
// The checkout tag move is a new entry, not a move; only the branch counts.
want := []string{"self-actuated/block-with-tmux@master 4d7a7ea -> bbbbbbb"}
if !slices.Equal(got, want) {
t.Errorf("lockMoves = %q, want %q", got, want)
}
}
-19
View File
@@ -90,25 +90,6 @@ func latestRelease(ctx context.Context, owner, name string) (string, error) {
return release.TagName, nil
}
// commitOfRef resolves a tag or branch to the commit it points at, following
// annotated tags the way an action pin must.
func commitOfRef(ctx context.Context, owner, name, ref string) (string, error) {
var commit struct {
SHA string `json:"sha"`
}
err := githubJSON(ctx, fmt.Sprintf("/repos/%s/%s/commits/%s", owner, name, ref), &commit)
if err != nil {
return "", err
}
if commit.SHA == "" {
return "", fmt.Errorf("%w: %s/%s@%s", errNoRelease, owner, name, ref)
}
return commit.SHA, nil
}
// currentSlug is the repository the run is acting on. It defaults to whatever
// the job is running in rather than a constant: a hardcoded upstream slug let a
// fork push its branch and then try to open the pull request on someone else's
+12
View File
@@ -32,6 +32,7 @@ func cmdVerify(ctx context.Context) error {
findings = append(findings, verifyToolchain(ctx, r)...)
findings = append(findings, verifyVendorHash(ctx, r)...)
findings = append(findings, verifyProviders(ctx, r)...)
findings = append(findings, verifyActionsLock(ctx, r)...)
if len(findings) == 0 {
log.Print("all version pins agree")
@@ -130,6 +131,17 @@ func verifyToolchain(ctx context.Context, r *repo) []finding {
return nil
}
// verifyActionsLock catches a workflow edited without relocking, and a locked
// commit its tag or branch no longer reaches, which the runner would reject.
func verifyActionsLock(ctx context.Context, r *repo) []finding {
_, err := r.nixRun(ctx, "gh-actions-lock", "--no-interactive", "--verify")
if err != nil {
return []finding{finding(actionsLock + " does not verify; run gh-actions-lock: " + err.Error())}
}
return nil
}
func verifyVendorHash(ctx context.Context, r *repo) []finding {
out, err := r.nixRun(ctx, "go", "run", "./cmd/vendorhash", "check")
if err != nil {