diff --git a/AGENTS.md b/AGENTS.md index 222d1b1dc..eea35c9e2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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` diff --git a/flake.nix b/flake.nix index 67a0426d3..61932d41f 100644 --- a/flake.nix +++ b/flake.nix @@ -141,6 +141,7 @@ gotools gh + gh-actions-lock ksh ko yq-go diff --git a/tools/bump/actions.go b/tools/bump/actions.go index 262074ded..33ab4da65 100644 --- a/tools/bump/actions.go +++ b/tools/bump/actions.go @@ -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", diff --git a/tools/bump/actions_test.go b/tools/bump/actions_test.go index b97cfb69f..1a14a9077 100644 --- a/tools/bump/actions_test.go +++ b/tools/bump/actions_test.go @@ -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) } } diff --git a/tools/bump/github.go b/tools/bump/github.go index 41201c3ae..a46183531 100644 --- a/tools/bump/github.go +++ b/tools/bump/github.go @@ -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 diff --git a/tools/bump/verify.go b/tools/bump/verify.go index 95b6f60c0..99ddd5988 100644 --- a/tools/bump/verify.go +++ b/tools/bump/verify.go @@ -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 {