From dc8dd99752117947237e60f713e5aac6edaab83b Mon Sep 17 00:00:00 2001 From: Jeff Martin Date: Wed, 18 Nov 2026 19:34:49 -0800 Subject: [PATCH 01/20] Add actions/verify composite action --- Makefile | 1 + actions/verify/README.md | 49 ++++++++++++++++++++++++ actions/verify/action.yml | 40 ++++++++++++++++++++ actions/verify/install.sh | 66 +++++++++++++++++++++++++++++++++ script/stamp-verify-action | 50 +++++++++++++++++++++++++ script/stamp-verify-action-test | 49 ++++++++++++++++++++++++ 6 files changed, 255 insertions(+) create mode 100644 actions/verify/README.md create mode 100644 actions/verify/action.yml create mode 100755 actions/verify/install.sh create mode 100755 script/stamp-verify-action create mode 100755 script/stamp-verify-action-test diff --git a/Makefile b/Makefile index 460e6730..0a45e651 100644 --- a/Makefile +++ b/Makefile @@ -17,6 +17,7 @@ test: test-release test-release: script/release-test + script/stamp-verify-action-test vet: go vet ./... diff --git a/actions/verify/README.md b/actions/verify/README.md new file mode 100644 index 00000000..6359d566 --- /dev/null +++ b/actions/verify/README.md @@ -0,0 +1,49 @@ +# Verify actions.lock + +Fails the job when `.github/workflows/actions.lock` is out of sync with the workflows, or a locked pin no longer verifies upstream. It downloads a checked `gh-actions-lock` release binary and runs `gh-actions-lock --verify`. + +```yaml +steps: + - uses: actions/checkout@v7.0.1 + with: + persist-credentials: false + - uses: github/gh-actions-lock/actions/verify@verify-vX.Y.Z +``` + +Use the [latest `verify-v*` tag](https://github.com/github/gh-actions-lock/tags). Every CLI release `vX.Y.Z` publishes `verify-vX.Y.Z`, which runs that CLI version by default, so a Dependabot bump of this action is also a CLI bump. Check out the repository before this step. + +The action runs on Linux, macOS and Windows runners, on x64 and arm64. + +## Inputs + +| Input | Default | Description | +|---|---|---| +| `token` | `${{ github.token }}` | Token the CLI uses to read action repositories. | +| `version` | the CLI release the tag was cut with | `gh-actions-lock` release to run, such as `v0.4.1`. | +| `args` | `--verify` | Arguments passed to `gh-actions-lock`, split on whitespace. For example, `--verify --fail-on-warning`. | + +With the default `version`, the binary is checked against checksums recorded in the tag. With another `version`, it's checked against the release's build attestation using `token`, so that token must be able to read public github.com repositories. + +## Private and internal actions + +The default `GITHUB_TOKEN` can read only the repository the workflow runs in. When a workflow uses a private or internal action from another repository, the runner can still run it if that repository's [Actions access setting](https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-a-private-repository) allows it, but `--verify` can't read it with `GITHUB_TOKEN` and fails. + +To verify those actions, pass a GitHub App installation token with read access to the repositories that hold them: + +```yaml +- uses: actions/create-github-app-token@vX + id: app-token + with: + app-id: ${{ vars.LOCKFILE_APP_ID }} + private-key: ${{ secrets.LOCKFILE_APP_PRIVATE_KEY }} + owner: ${{ github.repository_owner }} +- uses: github/gh-actions-lock/actions/verify@verify-vX.Y.Z + with: + token: ${{ steps.app-token.outputs.token }} +``` + +The app needs **Contents: read** on this repository and on every repository whose actions your workflows use. + +## GitHub Enterprise Cloud with data residency + +Set `GH_ACTIONS_LOCK_GITHUB_COM_TOKEN` on the step or job for actions read from github.com; see the [main README](../../README.md#github-enterprise-cloud-with-data-residency). diff --git a/actions/verify/action.yml b/actions/verify/action.yml new file mode 100644 index 00000000..e7c3d5d4 --- /dev/null +++ b/actions/verify/action.yml @@ -0,0 +1,40 @@ +name: Verify actions.lock +description: Fail when .github/workflows/actions.lock is out of sync with the workflows or a locked pin no longer verifies upstream + +inputs: + token: + description: Token the CLI uses to read action repositories. The default GITHUB_TOKEN can't read private or internal actions in other repositories; pass a GitHub App installation token for those. + required: false + default: ${{ github.token }} + version: + description: gh-actions-lock release to run, such as v0.4.1. Release tags of this action default it to the CLI release they were cut with. + required: false + default: "" # stamped by script/stamp-verify-action + args: + description: Arguments passed to gh-actions-lock, split on whitespace. + required: false + default: --verify + +runs: + using: composite + steps: + - name: Install gh-actions-lock + id: install + shell: bash + env: + VERSION: ${{ inputs.version }} + GH_TOKEN: ${{ inputs.token }} + OS: ${{ runner.os }} + ARCH: ${{ runner.arch }} + run: bash "$GITHUB_ACTION_PATH/install.sh" + + - name: Run gh-actions-lock + shell: bash + env: + BIN: ${{ steps.install.outputs.bin }} + ARGS: ${{ inputs.args }} + GH_TOKEN: ${{ inputs.token }} + run: | + set -f + read -r -a args <<<"$ARGS" + "$BIN" "${args[@]}" diff --git a/actions/verify/install.sh b/actions/verify/install.sh new file mode 100755 index 00000000..d73c833d --- /dev/null +++ b/actions/verify/install.sh @@ -0,0 +1,66 @@ +#!/usr/bin/env bash +# Downloads the gh-actions-lock release binary for this runner and checks it +# before use: against checksums.txt when VERSION is the release this action +# tag was stamped with, otherwise against the release's build attestation. +set -euo pipefail + +repo=github/gh-actions-lock +sums="$GITHUB_ACTION_PATH/checksums.txt" +: "${OS:?}" "${ARCH:?}" "${RUNNER_TEMP:?}" + +die() { + echo "::error::$*" >&2 + exit 1 +} + +if [ -z "${VERSION:-}" ]; then + die "set the version input, or use a verify-v* release tag of $repo/actions/verify" +fi +[[ "$VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-rc\.[0-9]+)?$ ]] || + die "invalid version '$VERSION'; expected vX.Y.Z or vX.Y.Z-rc.N" + +case "$OS" in + Linux) os=linux ext= ;; + macOS) os=darwin ext= ;; + Windows) os=windows ext=.exe ;; + *) die "unsupported runner OS '$OS'" ;; +esac +case "$ARCH" in + X64) arch=amd64 ;; + ARM64) arch=arm64 ;; + *) die "unsupported runner architecture '$ARCH'" ;; +esac +asset="${os}-${arch}${ext}" + +dir="$RUNNER_TEMP/gh-actions-lock" +bin="$dir/gh-actions-lock$ext" +mkdir -p "$dir" +curl -fsSL --retry 3 -o "$bin" "https://github.com/$repo/releases/download/$VERSION/$asset" + +sha256() { + if command -v sha256sum >/dev/null; then + sha256sum "$1" | awk '{ print $1 }' + else + shasum -a 256 "$1" | awk '{ print $1 }' + fi +} + +stamped= +[ -f "$sums" ] && stamped="$(awk 'NR == 1 && $1 == "#" { print $2 }' "$sums")" +if [ "$VERSION" = "$stamped" ]; then + want="$(awk -v a="$asset" '$2 == a { print $1 }' "$sums")" + [ -n "$want" ] || die "no checksum for $asset in $sums" + got="$(sha256 "$bin")" + [ "$got" = "$want" ] || die "checksum mismatch for $asset $VERSION: got $got, want $want" + echo "Verified $asset $VERSION against the stamped checksum." +else + GH_HOST=github.com gh attestation verify "$bin" \ + --repo "$repo" \ + --signer-workflow "$repo/.github/workflows/release.yml" \ + --source-ref "refs/tags/$VERSION" >/dev/null || + die "attestation check failed for $asset $VERSION" + echo "Verified $asset $VERSION against its build attestation." +fi + +chmod +x "$bin" +echo "bin=$bin" >>"$GITHUB_OUTPUT" diff --git a/script/stamp-verify-action b/script/stamp-verify-action new file mode 100755 index 00000000..bbdddc3a --- /dev/null +++ b/script/stamp-verify-action @@ -0,0 +1,50 @@ +#!/usr/bin/env bash +# +# Stamp actions/verify with a CLI release: default its version input to the +# tag and record the runner binaries' checksums. +# +# Usage: +# script/stamp-verify-action +# +# The release workflow runs this on the tagged commit and publishes the result +# as verify-. + +set -euo pipefail + +die() { + echo "error: $*" >&2 + exit 1 +} + +[ "$#" -eq 2 ] || die "usage: script/stamp-verify-action " +tag="$1" +assets="$(cd "$2" && pwd)" || die "no asset directory $2" +[[ "$tag" =~ ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-rc\.[1-9][0-9]*)?$ ]] || + die "invalid tag '$tag'; expected vX.Y.Z or vX.Y.Z-rc.N" + +cd "$(dirname "$0")/.." +action=actions/verify/action.yml +marker='default: "" # stamped by script/stamp-verify-action' + +[ "$(grep -cF "$marker" "$action")" -eq 1 ] || + die "$action must contain exactly one line with: $marker" + +sha256() { + if command -v sha256sum >/dev/null; then + sha256sum "$1" | awk '{ print $1 }' + else + shasum -a 256 "$1" | awk '{ print $1 }' + fi +} + +{ + echo "# $tag" + for a in linux-amd64 linux-arm64 darwin-amd64 darwin-arm64 windows-amd64.exe windows-arm64.exe; do + [ -f "$assets/$a" ] || die "missing release asset $assets/$a" + echo "$(sha256 "$assets/$a") $a" + done +} >actions/verify/checksums.txt + +tmp="$(mktemp)" +awk -v m="$marker" -v r="default: $tag" '{ i = index($0, m); if (i) $0 = substr($0, 1, i - 1) r; print }' "$action" >"$tmp" +mv "$tmp" "$action" diff --git a/script/stamp-verify-action-test b/script/stamp-verify-action-test new file mode 100755 index 00000000..48f642de --- /dev/null +++ b/script/stamp-verify-action-test @@ -0,0 +1,49 @@ +#!/usr/bin/env bash +set -euo pipefail + +root="$(cd "$(dirname "$0")/.." && pwd)" +tmp="$(mktemp -d)" +trap 'rm -r "$tmp"' EXIT + +mkdir -p "$tmp/repo/script" "$tmp/repo/actions/verify" "$tmp/assets" +cp "$root/script/stamp-verify-action" "$tmp/repo/script/" +cp "$root/actions/verify/action.yml" "$tmp/repo/actions/verify/" +for a in linux-amd64 linux-arm64 darwin-amd64 darwin-arm64 windows-amd64.exe windows-arm64.exe; do + printf '%s' "$a" >"$tmp/assets/$a" +done + +fail() { + echo "FAIL: $*" >&2 + exit 1 +} + +if "$tmp/repo/script/stamp-verify-action" 'v1.2.3;x' "$tmp/assets" 2>/dev/null; then + fail "accepted an invalid tag" +fi + +rm "$tmp/assets/windows-arm64.exe" +if "$tmp/repo/script/stamp-verify-action" v1.2.3 "$tmp/assets" 2>/dev/null; then + fail "stamped with a missing asset" +fi +printf '%s' windows-arm64.exe >"$tmp/assets/windows-arm64.exe" + +cd "$tmp" +repo/script/stamp-verify-action v1.2.3-rc.1 assets + +grep -q '^ default: v1.2.3-rc.1$' repo/actions/verify/action.yml || + fail "version default not stamped" +grep -q 'stamped by script/stamp-verify-action' repo/actions/verify/action.yml && + fail "stamp marker left behind" +[ "$(head -n 1 repo/actions/verify/checksums.txt)" = "# v1.2.3-rc.1" ] || + fail "checksums.txt header" +want="$(printf '%s' linux-arm64 | shasum -a 256 | awk '{ print $1 }')" +grep -qx "$want linux-arm64" repo/actions/verify/checksums.txt || + fail "linux-arm64 checksum" +[ "$(wc -l /dev/null; then + fail "restamped an already stamped action" +fi + +echo "stamp-verify-action tests passed" From 31be5560cc44913b14dff159b5ee3a8adf298fd5 Mon Sep 17 00:00:00 2001 From: Jeff Martin Date: Wed, 18 Nov 2026 19:34:49 -0800 Subject: [PATCH 02/20] Publish verify-vX.Y.Z action tags from the release workflow --- .github/workflows/release.yml | 54 +++++++++++++++++++++++++++++++++++ RELEASING.md | 8 ++++++ 2 files changed, 62 insertions(+) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 84105eee..4021067a 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -4,6 +4,7 @@ on: push: tags: - v* + - "!verify-v*" permissions: contents: read @@ -34,3 +35,56 @@ jobs: generate_attestations: true go_version_file: go.mod go_build_options: ./cmd/gh-actions-lock + + stamp-action: + name: Publish verify action + needs: publish + permissions: + contents: write + attestations: read + runs-on: ubuntu-latest + env: + GH_TOKEN: ${{ github.token }} + TAG: ${{ github.ref_name }} + REPO: ${{ github.repository }} + steps: + - uses: actions/checkout@v7.0.1 + with: + persist-credentials: false + + - name: Download and check release binaries + run: | + mkdir "$RUNNER_TEMP/assets" + cd "$RUNNER_TEMP/assets" + for a in linux-amd64 linux-arm64 darwin-amd64 darwin-arm64 windows-amd64.exe windows-arm64.exe; do + gh release download "$TAG" --repo "$REPO" --pattern "$a" + gh attestation verify "$a" --repo "$REPO" \ + --signer-workflow "$REPO/.github/workflows/release.yml" \ + --source-ref "refs/tags/$TAG" >/dev/null + done + + - name: Stamp actions/verify + run: script/stamp-verify-action "$TAG" "$RUNNER_TEMP/assets" + + # A commit created through the API is signed by GitHub, which the tag + # ruleset requires. It sits on top of the release commit, off main. + - name: Tag verify-${{ github.ref_name }} + run: | + set -euo pipefail + entries='[]' + for f in actions/verify/action.yml actions/verify/checksums.txt; do + sha="$(base64 -w0 "$f" | jq -Rn '{content: input, encoding: "base64"}' | + gh api "repos/$REPO/git/blobs" --input - --jq .sha)" + entries="$(jq -c --arg p "$f" --arg s "$sha" '. + [{path: $p, mode: "100644", type: "blob", sha: $s}]' <<<"$entries")" + done + tree="$(jq -n --arg b "$(git rev-parse 'HEAD^{tree}')" --argjson t "$entries" '{base_tree: $b, tree: $t}' | + gh api "repos/$REPO/git/trees" --input - --jq .sha)" + commit="$(jq -n --arg m "Stamp actions/verify for $TAG" --arg t "$tree" --arg p "$(git rev-parse HEAD)" \ + '{message: $m, tree: $t, parents: [$p]}' | + gh api "repos/$REPO/git/commits" --input - --jq .sha)" + [ "$(gh api "repos/$REPO/git/commits/$commit" --jq .verification.verified)" = true ] || { + echo "::error::stamp commit $commit is not signed" + exit 1 + } + gh api "repos/$REPO/git/refs" -f "ref=refs/tags/verify-$TAG" -f "sha=$commit" >/dev/null + echo "Tagged verify-$TAG at $commit" diff --git a/RELEASING.md b/RELEASING.md index 264ce23e..24c368f5 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -41,6 +41,14 @@ then pushes and verifies an annotated `vX.Y.Z` or `vX.Y.Z-rc.N` tag. The tag workflow verifies the tag, then publishes the binaries, attestations, and GitHub release. +It then publishes the [verify action](actions/verify/README.md) for the +release. `script/stamp-verify-action` sets the action's default `version` to +the new tag and records the release binaries' checksums in +`actions/verify/checksums.txt`. The workflow commits that on top of the release +commit and tags it `verify-vX.Y.Z`. That commit isn't on `main`, since it +holds checksums of binaries built from its parent. Don't edit the default or +the checksums by hand. + ## Dependabot compatibility Before releasing, decide whether From 8f6ad9c8d38d5eba572d64cdf2d59b5ed7f120cd Mon Sep 17 00:00:00 2001 From: Jeff Martin Date: Wed, 18 Nov 2026 19:34:49 -0800 Subject: [PATCH 03/20] Verify this repository's lockfile with actions/verify --- .github/workflows/verify-lockfile.yml | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/.github/workflows/verify-lockfile.yml b/.github/workflows/verify-lockfile.yml index c54560d5..96836aff 100644 --- a/.github/workflows/verify-lockfile.yml +++ b/.github/workflows/verify-lockfile.yml @@ -1,5 +1,9 @@ # Fails when .github/workflows/actions.lock is out of sync with the # workflows or a locked pin no longer verifies upstream. +# +# This repository runs its own actions/verify from the checkout, so the +# version is set here. Other repositories pin a verify-v* tag instead; see +# actions/verify/README.md. name: verify-lockfile @@ -15,11 +19,10 @@ permissions: jobs: verify: runs-on: ubuntu-latest - env: - GH_TOKEN: ${{ github.token }} steps: - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - run: gh extension install github/gh-actions-lock --pin v0.4.1 - - run: gh actions-lock --verify + - uses: ./actions/verify + with: + version: v0.4.1 From 195b118ee08b1819b9a7b8f20b728414bfc33d28 Mon Sep 17 00:00:00 2001 From: Jeff Martin Date: Wed, 18 Nov 2026 19:34:49 -0800 Subject: [PATCH 04/20] Document the verify action and its token caveat --- README.md | 32 +++++++++++++++++++++++++++++++- skills/gh-actions-lock/SKILL.md | 18 +++++++++++++----- 2 files changed, 44 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 75f31565..72f07d12 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,29 @@ git add .github/workflows/ # check into source Rerun `gh actions-lock` after adding a workflow or changing any `uses:`. -Make sure you don't check in a corrupt lockfile. Copy [`.github/workflows/verify-lockfile.yml`](.github/workflows/verify-lockfile.yml) into your repository, modify it for your needs, then run `gh actions-lock` once so that workflow is locked too. +Make sure you don't check in a corrupt lockfile. Add a workflow that runs the [verify action](actions/verify/README.md) on every pull request, then run `gh actions-lock` once so that workflow is locked too: + +```yaml +name: verify-lockfile +on: + pull_request: + push: + branches: [main] +permissions: + contents: read +jobs: + verify: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7.0.1 + with: + persist-credentials: false + - uses: github/gh-actions-lock/actions/verify@verify-vX.Y.Z +``` + +Replace `verify-vX.Y.Z` with the [latest `verify-v*` tag](https://github.com/github/gh-actions-lock/tags). Dependabot's `github-actions` updates bump it with each CLI release. + +The job's `GITHUB_TOKEN` can only read the repository the workflow runs in, so `--verify` fails on private or internal actions from other repositories even when the runner is allowed to use them. Pass a GitHub App installation token with read access to those repositories as the action's `token` input; see [Private and internal actions](actions/verify/README.md#private-and-internal-actions). ### GitHub Enterprise Cloud with data residency @@ -41,6 +63,14 @@ Actions that aren't on the tenant, such as `actions/checkout`, are read from pub In GitHub Actions on GHE.com, the job's `GITHUB_TOKEN` is issued by your tenant, so github.com doesn't accept it. Create a [fine-grained personal access token](https://docs.github.com/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) on github.com with public repository access only and no permissions, save it as a secret on the tenant, and pass it in: +```yaml +- uses: github/gh-actions-lock/actions/verify@verify-vX.Y.Z + env: + GH_ACTIONS_LOCK_GITHUB_COM_TOKEN: ${{ secrets.ACTIONS_LOCK_GITHUB_COM_TOKEN }} +``` + +Or, running the CLI directly: + ```yaml - run: gh actions-lock --verify env: diff --git a/skills/gh-actions-lock/SKILL.md b/skills/gh-actions-lock/SKILL.md index 8eba8c49..06d45ea2 100644 --- a/skills/gh-actions-lock/SKILL.md +++ b/skills/gh-actions-lock/SKILL.md @@ -133,11 +133,19 @@ category name alone. ## CI -Copy [`.github/workflows/verify-lockfile.yml`](https://github.com/github/gh-actions-lock/blob/main/.github/workflows/verify-lockfile.yml) -into the repository, then run `gh actions-lock` once so the new workflow is locked too. It runs -`gh actions-lock --verify` on pull requests, pushes to `main`, and a weekly schedule that catches -re-pointed tags. The job's `GITHUB_TOKEN` reads public actions and the repository itself; actions -from other private or internal repositories need a token that can read them. +Add a workflow that runs the [verify action](https://github.com/github/gh-actions-lock/blob/main/actions/verify/README.md) +on pull requests and pushes to `main`, then run `gh actions-lock` once so the new workflow is locked too: + +```yaml +- uses: actions/checkout@v7.0.1 + with: + persist-credentials: false +- uses: github/gh-actions-lock/actions/verify@verify-vX.Y.Z # latest verify-v* tag +``` + +It runs `gh actions-lock --verify`. The job's `GITHUB_TOKEN` reads public actions and the repository +itself; actions from other private or internal repositories need a GitHub App installation token +that can read them, passed as the action's `token` input. ## Limits From fbafe8e2ce7608417a577989aa527568d75be603 Mon Sep 17 00:00:00 2001 From: Jeff Martin Date: Wed, 18 Nov 2026 19:41:09 -0800 Subject: [PATCH 05/20] verify action: hash via stdin, split multiline args, keep GHE.com tokens off github.com --- actions/verify/README.md | 4 ++-- actions/verify/action.yml | 2 +- actions/verify/install.sh | 14 +++++++++++--- 3 files changed, 14 insertions(+), 6 deletions(-) diff --git a/actions/verify/README.md b/actions/verify/README.md index 6359d566..b19fd276 100644 --- a/actions/verify/README.md +++ b/actions/verify/README.md @@ -20,9 +20,9 @@ The action runs on Linux, macOS and Windows runners, on x64 and arm64. |---|---|---| | `token` | `${{ github.token }}` | Token the CLI uses to read action repositories. | | `version` | the CLI release the tag was cut with | `gh-actions-lock` release to run, such as `v0.4.1`. | -| `args` | `--verify` | Arguments passed to `gh-actions-lock`, split on whitespace. For example, `--verify --fail-on-warning`. | +| `args` | `--verify` | Arguments passed to `gh-actions-lock`, split on whitespace and newlines. For example, `--verify --fail-on-warning`. | -With the default `version`, the binary is checked against checksums recorded in the tag. With another `version`, it's checked against the release's build attestation using `token`, so that token must be able to read public github.com repositories. +With the default `version`, the binary is checked against checksums recorded in the tag. With another `version`, it's checked against the release's build attestation on github.com using `token`. On GHE.com, that check uses `GH_ACTIONS_LOCK_GITHUB_COM_TOKEN` instead, so your tenant token never leaves the tenant. ## Private and internal actions diff --git a/actions/verify/action.yml b/actions/verify/action.yml index e7c3d5d4..713b7bf0 100644 --- a/actions/verify/action.yml +++ b/actions/verify/action.yml @@ -36,5 +36,5 @@ runs: GH_TOKEN: ${{ inputs.token }} run: | set -f - read -r -a args <<<"$ARGS" + read -r -d '' -a args <<<"$ARGS" || true "$BIN" "${args[@]}" diff --git a/actions/verify/install.sh b/actions/verify/install.sh index d73c833d..89bd1321 100755 --- a/actions/verify/install.sh +++ b/actions/verify/install.sh @@ -38,10 +38,11 @@ mkdir -p "$dir" curl -fsSL --retry 3 -o "$bin" "https://github.com/$repo/releases/download/$VERSION/$asset" sha256() { + # Hash stdin: GNU sha256sum escapes output for Windows paths with backslashes. if command -v sha256sum >/dev/null; then - sha256sum "$1" | awk '{ print $1 }' + sha256sum <"$1" | awk '{ print $1 }' else - shasum -a 256 "$1" | awk '{ print $1 }' + shasum -a 256 <"$1" | awk '{ print $1 }' fi } @@ -54,7 +55,14 @@ if [ "$VERSION" = "$stamped" ]; then [ "$got" = "$want" ] || die "checksum mismatch for $asset $VERSION: got $got, want $want" echo "Verified $asset $VERSION against the stamped checksum." else - GH_HOST=github.com gh attestation verify "$bin" \ + # Attestations live on github.com. A GHE.com job token must never be sent there. + token="${GH_TOKEN:-}" + if [ "${GITHUB_SERVER_URL:-https://github.com}" != https://github.com ]; then + token="${GH_ACTIONS_LOCK_GITHUB_COM_TOKEN:-}" + [ -n "$token" ] || + die "set GH_ACTIONS_LOCK_GITHUB_COM_TOKEN to check $VERSION, or use the version this action tag was released with" + fi + env -u GITHUB_TOKEN GH_HOST=github.com GH_TOKEN="$token" gh attestation verify "$bin" \ --repo "$repo" \ --signer-workflow "$repo/.github/workflows/release.yml" \ --source-ref "refs/tags/$VERSION" >/dev/null || From b1b70c4f02f2e2fc03d81efc16cae35df68cc935 Mon Sep 17 00:00:00 2001 From: Jeff Martin Date: Wed, 18 Nov 2026 19:59:23 -0800 Subject: [PATCH 06/20] Run this repository's verify action through $/ A $/ reference runs actions/verify at the workflow's own commit, which avoids a local ./ reference. The action has no uses:, so it needs no lockfile entry. --- .github/workflows/verify-lockfile.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/verify-lockfile.yml b/.github/workflows/verify-lockfile.yml index 96836aff..ad9af7bd 100644 --- a/.github/workflows/verify-lockfile.yml +++ b/.github/workflows/verify-lockfile.yml @@ -1,7 +1,7 @@ # Fails when .github/workflows/actions.lock is out of sync with the # workflows or a locked pin no longer verifies upstream. # -# This repository runs its own actions/verify from the checkout, so the +# This repository runs its own actions/verify at the workflow commit, so the # version is set here. Other repositories pin a verify-v* tag instead; see # actions/verify/README.md. @@ -23,6 +23,6 @@ jobs: - uses: actions/checkout@v7.0.1 with: persist-credentials: false - - uses: ./actions/verify + - uses: $/actions/verify with: version: v0.4.1 From edefb671f4fab3d8ec5d15edbefa0f08430140be Mon Sep 17 00:00:00 2001 From: Jeff Martin Date: Wed, 18 Nov 2026 20:16:26 -0800 Subject: [PATCH 07/20] Run the verify action's install and CLI from Node Moves the download, checksum and attestation checks and the CLI run from bash into actions/verify/lib.mjs and verify.mjs, with node:test unit tests. action.yml is a single step that calls verify.mjs. --- actions/verify/README.md | 2 +- actions/verify/action.yml | 25 +--- actions/verify/install.sh | 74 ------------ actions/verify/lib.mjs | 129 ++++++++++++++++++++ actions/verify/lib.test.mjs | 201 ++++++++++++++++++++++++++++++++ actions/verify/verify.mjs | 18 +++ script/stamp-verify-action | 50 -------- script/stamp-verify-action-test | 49 -------- 8 files changed, 355 insertions(+), 193 deletions(-) delete mode 100755 actions/verify/install.sh create mode 100644 actions/verify/lib.mjs create mode 100644 actions/verify/lib.test.mjs create mode 100644 actions/verify/verify.mjs delete mode 100755 script/stamp-verify-action delete mode 100755 script/stamp-verify-action-test diff --git a/actions/verify/README.md b/actions/verify/README.md index b19fd276..e45410b9 100644 --- a/actions/verify/README.md +++ b/actions/verify/README.md @@ -12,7 +12,7 @@ steps: Use the [latest `verify-v*` tag](https://github.com/github/gh-actions-lock/tags). Every CLI release `vX.Y.Z` publishes `verify-vX.Y.Z`, which runs that CLI version by default, so a Dependabot bump of this action is also a CLI bump. Check out the repository before this step. -The action runs on Linux, macOS and Windows runners, on x64 and arm64. +The action runs on Linux, macOS and Windows runners, on x64 and arm64. It needs `node` (20 or later) on `PATH`, which GitHub-hosted runners have. ## Inputs diff --git a/actions/verify/action.yml b/actions/verify/action.yml index 713b7bf0..5784c83f 100644 --- a/actions/verify/action.yml +++ b/actions/verify/action.yml @@ -9,7 +9,7 @@ inputs: version: description: gh-actions-lock release to run, such as v0.4.1. Release tags of this action default it to the CLI release they were cut with. required: false - default: "" # stamped by script/stamp-verify-action + default: "" # stamped by script/verify-action-release.mjs args: description: Arguments passed to gh-actions-lock, split on whitespace. required: false @@ -18,23 +18,10 @@ inputs: runs: using: composite steps: - - name: Install gh-actions-lock - id: install + - name: Verify actions.lock shell: bash env: - VERSION: ${{ inputs.version }} - GH_TOKEN: ${{ inputs.token }} - OS: ${{ runner.os }} - ARCH: ${{ runner.arch }} - run: bash "$GITHUB_ACTION_PATH/install.sh" - - - name: Run gh-actions-lock - shell: bash - env: - BIN: ${{ steps.install.outputs.bin }} - ARGS: ${{ inputs.args }} - GH_TOKEN: ${{ inputs.token }} - run: | - set -f - read -r -d '' -a args <<<"$ARGS" || true - "$BIN" "${args[@]}" + INPUT_TOKEN: ${{ inputs.token }} + INPUT_VERSION: ${{ inputs.version }} + INPUT_ARGS: ${{ inputs.args }} + run: node "$GITHUB_ACTION_PATH/verify.mjs" diff --git a/actions/verify/install.sh b/actions/verify/install.sh deleted file mode 100755 index 89bd1321..00000000 --- a/actions/verify/install.sh +++ /dev/null @@ -1,74 +0,0 @@ -#!/usr/bin/env bash -# Downloads the gh-actions-lock release binary for this runner and checks it -# before use: against checksums.txt when VERSION is the release this action -# tag was stamped with, otherwise against the release's build attestation. -set -euo pipefail - -repo=github/gh-actions-lock -sums="$GITHUB_ACTION_PATH/checksums.txt" -: "${OS:?}" "${ARCH:?}" "${RUNNER_TEMP:?}" - -die() { - echo "::error::$*" >&2 - exit 1 -} - -if [ -z "${VERSION:-}" ]; then - die "set the version input, or use a verify-v* release tag of $repo/actions/verify" -fi -[[ "$VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-rc\.[0-9]+)?$ ]] || - die "invalid version '$VERSION'; expected vX.Y.Z or vX.Y.Z-rc.N" - -case "$OS" in - Linux) os=linux ext= ;; - macOS) os=darwin ext= ;; - Windows) os=windows ext=.exe ;; - *) die "unsupported runner OS '$OS'" ;; -esac -case "$ARCH" in - X64) arch=amd64 ;; - ARM64) arch=arm64 ;; - *) die "unsupported runner architecture '$ARCH'" ;; -esac -asset="${os}-${arch}${ext}" - -dir="$RUNNER_TEMP/gh-actions-lock" -bin="$dir/gh-actions-lock$ext" -mkdir -p "$dir" -curl -fsSL --retry 3 -o "$bin" "https://github.com/$repo/releases/download/$VERSION/$asset" - -sha256() { - # Hash stdin: GNU sha256sum escapes output for Windows paths with backslashes. - if command -v sha256sum >/dev/null; then - sha256sum <"$1" | awk '{ print $1 }' - else - shasum -a 256 <"$1" | awk '{ print $1 }' - fi -} - -stamped= -[ -f "$sums" ] && stamped="$(awk 'NR == 1 && $1 == "#" { print $2 }' "$sums")" -if [ "$VERSION" = "$stamped" ]; then - want="$(awk -v a="$asset" '$2 == a { print $1 }' "$sums")" - [ -n "$want" ] || die "no checksum for $asset in $sums" - got="$(sha256 "$bin")" - [ "$got" = "$want" ] || die "checksum mismatch for $asset $VERSION: got $got, want $want" - echo "Verified $asset $VERSION against the stamped checksum." -else - # Attestations live on github.com. A GHE.com job token must never be sent there. - token="${GH_TOKEN:-}" - if [ "${GITHUB_SERVER_URL:-https://github.com}" != https://github.com ]; then - token="${GH_ACTIONS_LOCK_GITHUB_COM_TOKEN:-}" - [ -n "$token" ] || - die "set GH_ACTIONS_LOCK_GITHUB_COM_TOKEN to check $VERSION, or use the version this action tag was released with" - fi - env -u GITHUB_TOKEN GH_HOST=github.com GH_TOKEN="$token" gh attestation verify "$bin" \ - --repo "$repo" \ - --signer-workflow "$repo/.github/workflows/release.yml" \ - --source-ref "refs/tags/$VERSION" >/dev/null || - die "attestation check failed for $asset $VERSION" - echo "Verified $asset $VERSION against its build attestation." -fi - -chmod +x "$bin" -echo "bin=$bin" >>"$GITHUB_OUTPUT" diff --git a/actions/verify/lib.mjs b/actions/verify/lib.mjs new file mode 100644 index 00000000..f1f228f3 --- /dev/null +++ b/actions/verify/lib.mjs @@ -0,0 +1,129 @@ +// Logic for actions/verify. verify.mjs is the entry point; tests import this. + +import { spawnSync } from "node:child_process"; +import { createHash } from "node:crypto"; +import { existsSync } from "node:fs"; +import { chmod, mkdir, readFile } from "node:fs/promises"; +import { join } from "node:path"; + +export const REPO = "github/gh-actions-lock"; + +export class ActionError extends Error {} + +export function checkVersion(version) { + if (!version) { + throw new ActionError(`set the version input, or use a verify-v* release tag of ${REPO}/actions/verify`); + } + if (!/^v\d+\.\d+\.\d+(-rc\.\d+)?$/.test(version)) { + throw new ActionError(`invalid version '${version}'; expected vX.Y.Z or vX.Y.Z-rc.N`); + } + return version; +} + +const platforms = { Linux: ["linux", ""], macOS: ["darwin", ""], Windows: ["windows", ".exe"] }; +const arches = { X64: "amd64", ARM64: "arm64" }; + +// assetFor maps RUNNER_OS and RUNNER_ARCH to a release asset name. +export function assetFor(runnerOS, runnerArch) { + const platform = platforms[runnerOS]; + if (!platform) throw new ActionError(`unsupported runner OS '${runnerOS}'`); + const arch = arches[runnerArch]; + if (!arch) throw new ActionError(`unsupported runner architecture '${runnerArch}'`); + const [os, ext] = platform; + return { asset: `${os}-${arch}${ext}`, ext }; +} + +// splitArgs splits the args input on any whitespace, newlines included. Nothing is +// globbed or expanded. +export function splitArgs(input) { + return (input ?? "").split(/\s+/).filter(Boolean); +} + +// selectCheck picks how to check the binary: the checksum stamped into this action +// tag when version is the release it was stamped with, otherwise the release's +// build attestation. checksums is the text of checksums.txt, or null. +export function selectCheck(version, checksums, asset) { + const lines = checksums?.split(/\r?\n/) ?? []; + const header = lines[0]?.split(/\s+/); + const stamped = header?.[0] === "#" ? header[1] : undefined; + if (version !== stamped) return { kind: "attestation" }; + for (const line of lines.slice(1)) { + const [sum, name] = line.trim().split(/\s+/); + if (name === asset) return { kind: "checksum", want: sum }; + } + throw new ActionError(`no checksum for ${asset} in checksums.txt`); +} + +// attestationEnv builds the environment for `gh attestation verify`. Attestations +// live on github.com, so a GHE.com job token must never be sent there. +export function attestationEnv(env) { + let token = env.INPUT_TOKEN ?? ""; + if ((env.GITHUB_SERVER_URL ?? "https://github.com") !== "https://github.com") { + token = env.GH_ACTIONS_LOCK_GITHUB_COM_TOKEN ?? ""; + if (!token) { + throw new ActionError( + `set GH_ACTIONS_LOCK_GITHUB_COM_TOKEN to check ${env.INPUT_VERSION}, or use the version this action tag was released with`, + ); + } + } + const out = { ...env, GH_HOST: "github.com", GH_TOKEN: token }; + delete out.GITHUB_TOKEN; + return out; +} + +export async function sha256File(path) { + return createHash("sha256").update(await readFile(path)).digest("hex"); +} + +// curl, unlike Node 20's fetch, honors the runner's proxy settings and backs off between retries. +function curl(url, dest) { + const r = spawnSync("curl", ["-fsSL", "--retry", "3", "-o", dest, url], { stdio: ["ignore", "ignore", "inherit"] }); + return r.status === 0; +} + +function runGh(args, env) { + const r = spawnSync("gh", args, { env, stdio: ["ignore", "ignore", "inherit"] }); + return r.status === 0; +} + +// install downloads the gh-actions-lock binary for this runner into RUNNER_TEMP, +// checks it and returns its path. +export async function install({ env, actionDir, download = curl, gh = runGh, log = console.log }) { + const version = checkVersion(env.INPUT_VERSION); + const { asset, ext } = assetFor(env.RUNNER_OS, env.RUNNER_ARCH); + if (!env.RUNNER_TEMP) throw new ActionError("RUNNER_TEMP is not set"); + + const sumsPath = join(actionDir, "checksums.txt"); + const sums = existsSync(sumsPath) ? await readFile(sumsPath, "utf8") : null; + const check = selectCheck(version, sums, asset); + const ghEnv = check.kind === "attestation" ? attestationEnv(env) : null; + + const dir = join(env.RUNNER_TEMP, "gh-actions-lock"); + await mkdir(dir, { recursive: true }); + const bin = join(dir, `gh-actions-lock${ext}`); + const url = `https://github.com/${REPO}/releases/download/${version}/${asset}`; + if (!(await download(url, bin))) throw new ActionError(`download ${url} failed`); + + if (check.kind === "checksum") { + const got = await sha256File(bin); + if (got !== check.want) { + throw new ActionError(`checksum mismatch for ${asset} ${version}: got ${got}, want ${check.want}`); + } + log(`Verified ${asset} ${version} against the stamped checksum.`); + } else { + const ok = gh( + [ + "attestation", "verify", bin, + "--repo", REPO, + "--signer-workflow", `${REPO}/.github/workflows/release.yml`, + "--source-ref", `refs/tags/${version}`, + ], + ghEnv, + ); + if (!ok) throw new ActionError(`attestation check failed for ${asset} ${version}`); + log(`Verified ${asset} ${version} against its build attestation.`); + } + + await chmod(bin, 0o755); + return bin; +} diff --git a/actions/verify/lib.test.mjs b/actions/verify/lib.test.mjs new file mode 100644 index 00000000..0adcecf3 --- /dev/null +++ b/actions/verify/lib.test.mjs @@ -0,0 +1,201 @@ +import assert from "node:assert/strict"; +import { createHash } from "node:crypto"; +import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { afterEach, beforeEach, describe, test } from "node:test"; +import { ActionError, assetFor, attestationEnv, checkVersion, install, selectCheck, splitArgs } from "./lib.mjs"; + +const sha = (s) => createHash("sha256").update(s).digest("hex"); + +describe("splitArgs", () => { + test("splits on spaces, tabs and newlines", () => { + assert.deepEqual(splitArgs("--verify\n--fail-on-warning\t --json\r\n"), ["--verify", "--fail-on-warning", "--json"]); + }); + test("passes glob characters through unexpanded", () => { + assert.deepEqual(splitArgs("--verify *"), ["--verify", "*"]); + }); + test("empty input gives no args", () => { + assert.deepEqual(splitArgs(""), []); + assert.deepEqual(splitArgs(undefined), []); + }); +}); + +describe("checkVersion", () => { + test("accepts releases and release candidates", () => { + assert.equal(checkVersion("v0.4.1"), "v0.4.1"); + assert.equal(checkVersion("v1.2.3-rc.4"), "v1.2.3-rc.4"); + }); + test("asks for a version when empty", () => { + assert.throws(() => checkVersion(""), /set the version input/); + }); + for (const v of ["0.4.1", "v0.4", "v0.4.1;rm", "../v0.4.1", "v0.4.1-beta"]) { + test(`rejects ${v}`, () => assert.throws(() => checkVersion(v), /invalid version/)); + } +}); + +describe("assetFor", () => { + test("maps runners to release assets", () => { + assert.deepEqual(assetFor("Linux", "X64"), { asset: "linux-amd64", ext: "" }); + assert.deepEqual(assetFor("macOS", "ARM64"), { asset: "darwin-arm64", ext: "" }); + assert.deepEqual(assetFor("Windows", "X64"), { asset: "windows-amd64.exe", ext: ".exe" }); + }); + test("rejects unsupported runners", () => { + assert.throws(() => assetFor("FreeBSD", "X64"), /unsupported runner OS/); + assert.throws(() => assetFor("Linux", "X86"), /unsupported runner architecture/); + }); +}); + +describe("selectCheck", () => { + const sums = `# v0.4.1\n${"a".repeat(64)} linux-amd64\n${"b".repeat(64)} windows-amd64.exe\n`; + test("uses the stamped checksum for the stamped version", () => { + assert.deepEqual(selectCheck("v0.4.1", sums, "windows-amd64.exe"), { kind: "checksum", want: "b".repeat(64) }); + }); + test("handles CRLF checksums", () => { + assert.deepEqual(selectCheck("v0.4.1", sums.replaceAll("\n", "\r\n"), "linux-amd64"), { + kind: "checksum", + want: "a".repeat(64), + }); + }); + test("uses the attestation for any other version", () => { + assert.deepEqual(selectCheck("v0.4.2", sums, "linux-amd64"), { kind: "attestation" }); + }); + test("uses the attestation when the action is unstamped", () => { + assert.deepEqual(selectCheck("v0.4.1", null, "linux-amd64"), { kind: "attestation" }); + }); + test("fails when the stamped version lacks the asset", () => { + assert.throws(() => selectCheck("v0.4.1", sums, "darwin-arm64"), /no checksum for darwin-arm64/); + }); +}); + +describe("attestationEnv", () => { + const base = { INPUT_TOKEN: "job", INPUT_VERSION: "v0.4.2", GITHUB_TOKEN: "ambient", PATH: "/bin" }; + test("on github.com uses the token input and drops GITHUB_TOKEN", () => { + const env = attestationEnv({ ...base, GITHUB_SERVER_URL: "https://github.com" }); + assert.equal(env.GH_TOKEN, "job"); + assert.equal(env.GH_HOST, "github.com"); + assert.equal(env.PATH, "/bin"); + assert.ok(!("GITHUB_TOKEN" in env)); + }); + test("off github.com uses GH_ACTIONS_LOCK_GITHUB_COM_TOKEN, never the tenant token", () => { + const env = attestationEnv({ + ...base, + GITHUB_SERVER_URL: "https://tenant.ghe.com", + GH_ACTIONS_LOCK_GITHUB_COM_TOKEN: "dotcom", + }); + assert.equal(env.GH_TOKEN, "dotcom"); + assert.equal(env.GH_HOST, "github.com"); + assert.ok(!("GITHUB_TOKEN" in env)); + }); + test("off github.com fails without a github.com token", () => { + assert.throws( + () => attestationEnv({ ...base, GITHUB_SERVER_URL: "https://tenant.ghe.com" }), + /set GH_ACTIONS_LOCK_GITHUB_COM_TOKEN to check v0.4.2/, + ); + }); +}); + +describe("install", () => { + let tmp; + beforeEach(async () => { + tmp = await mkdtemp(join(tmpdir(), "verify-action-")); + }); + afterEach(async () => { + await rm(tmp, { recursive: true, force: true }); + }); + + const binary = "fake gh-actions-lock"; + const okDownload = async (url, dest) => (await writeFile(dest, binary), true); + const quiet = () => {}; + + async function stampedAction(version, asset, sum = sha(binary)) { + await writeFile(join(tmp, "checksums.txt"), `# ${version}\n${sum} ${asset}\n`); + return tmp; + } + + test("checks the stamped checksum, with backslashes in the path", async () => { + // GNU sha256sum escaped backslash paths; hashing in-process must not care. + const env = { + INPUT_VERSION: "v0.4.1", + RUNNER_OS: "Windows", + RUNNER_ARCH: "X64", + RUNNER_TEMP: join(tmp, "runner\\temp"), + }; + const actionDir = await stampedAction("v0.4.1", "windows-amd64.exe"); + let fetched; + const bin = await install({ + env, + actionDir, + download: async (url, dest) => ((fetched = url), okDownload(url, dest)), + gh: () => assert.fail("attestation should not run"), + log: quiet, + }); + assert.equal(fetched, "https://github.com/github/gh-actions-lock/releases/download/v0.4.1/windows-amd64.exe"); + assert.equal(bin, join(env.RUNNER_TEMP, "gh-actions-lock", "gh-actions-lock.exe")); + assert.equal(await readFile(bin, "utf8"), binary); + }); + + test("fails on a checksum mismatch", async () => { + const env = { INPUT_VERSION: "v0.4.1", RUNNER_OS: "Linux", RUNNER_ARCH: "X64", RUNNER_TEMP: tmp }; + const actionDir = await stampedAction("v0.4.1", "linux-amd64", "0".repeat(64)); + await assert.rejects( + install({ env, actionDir, download: okDownload, gh: () => true, log: quiet }), + (err) => err instanceof ActionError && /checksum mismatch for linux-amd64 v0.4.1/.test(err.message), + ); + }); + + test("checks other versions against the attestation with a scoped token", async () => { + const env = { + INPUT_VERSION: "v0.4.2", + INPUT_TOKEN: "tenant", + GITHUB_TOKEN: "ambient", + GITHUB_SERVER_URL: "https://tenant.ghe.com", + GH_ACTIONS_LOCK_GITHUB_COM_TOKEN: "dotcom", + RUNNER_OS: "macOS", + RUNNER_ARCH: "ARM64", + RUNNER_TEMP: tmp, + }; + const actionDir = await stampedAction("v0.4.1", "darwin-arm64"); + let call; + const bin = await install({ env, actionDir, download: okDownload, gh: (args, e) => ((call = { args, e }), true), log: quiet }); + assert.deepEqual(call.args, [ + "attestation", "verify", bin, + "--repo", "github/gh-actions-lock", + "--signer-workflow", "github/gh-actions-lock/.github/workflows/release.yml", + "--source-ref", "refs/tags/v0.4.2", + ]); + assert.equal(call.e.GH_TOKEN, "dotcom"); + assert.ok(!("GITHUB_TOKEN" in call.e)); + }); + + test("fails when the attestation check fails", async () => { + const env = { INPUT_VERSION: "v0.4.2", RUNNER_OS: "Linux", RUNNER_ARCH: "X64", RUNNER_TEMP: tmp }; + await assert.rejects( + install({ env, actionDir: tmp, download: okDownload, gh: () => false, log: quiet }), + /attestation check failed for linux-amd64 v0.4.2/, + ); + }); + + test("checks the token scope before downloading", async () => { + const env = { + INPUT_VERSION: "v0.4.2", + GITHUB_SERVER_URL: "https://tenant.ghe.com", + RUNNER_OS: "Linux", + RUNNER_ARCH: "X64", + RUNNER_TEMP: tmp, + }; + await assert.rejects( + install({ env, actionDir: tmp, download: () => assert.fail("downloaded"), gh: () => true, log: quiet }), + /GH_ACTIONS_LOCK_GITHUB_COM_TOKEN/, + ); + }); + + test("fails when the download fails", async () => { + const env = { INPUT_VERSION: "v0.4.1", RUNNER_OS: "Linux", RUNNER_ARCH: "X64", RUNNER_TEMP: tmp }; + const actionDir = await stampedAction("v0.4.1", "linux-amd64"); + await assert.rejects( + install({ env, actionDir, download: () => false, gh: () => true, log: quiet }), + /download https:\/\/github.com\/github\/gh-actions-lock\/releases\/download\/v0.4.1\/linux-amd64 failed/, + ); + }); +}); diff --git a/actions/verify/verify.mjs b/actions/verify/verify.mjs new file mode 100644 index 00000000..dbb6aba4 --- /dev/null +++ b/actions/verify/verify.mjs @@ -0,0 +1,18 @@ +import { spawnSync } from "node:child_process"; +import { dirname } from "node:path"; +import { fileURLToPath } from "node:url"; +import { install, splitArgs } from "./lib.mjs"; + +try { + const env = process.env; + const bin = await install({ env, actionDir: dirname(fileURLToPath(import.meta.url)) }); + const r = spawnSync(bin, splitArgs(env.INPUT_ARGS), { + stdio: "inherit", + env: { ...env, GH_TOKEN: env.INPUT_TOKEN ?? "" }, + }); + if (r.error) throw r.error; + process.exitCode = r.status ?? 1; +} catch (err) { + console.error(`::error::${err.message}`); + process.exitCode = 1; +} diff --git a/script/stamp-verify-action b/script/stamp-verify-action deleted file mode 100755 index bbdddc3a..00000000 --- a/script/stamp-verify-action +++ /dev/null @@ -1,50 +0,0 @@ -#!/usr/bin/env bash -# -# Stamp actions/verify with a CLI release: default its version input to the -# tag and record the runner binaries' checksums. -# -# Usage: -# script/stamp-verify-action -# -# The release workflow runs this on the tagged commit and publishes the result -# as verify-. - -set -euo pipefail - -die() { - echo "error: $*" >&2 - exit 1 -} - -[ "$#" -eq 2 ] || die "usage: script/stamp-verify-action " -tag="$1" -assets="$(cd "$2" && pwd)" || die "no asset directory $2" -[[ "$tag" =~ ^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-rc\.[1-9][0-9]*)?$ ]] || - die "invalid tag '$tag'; expected vX.Y.Z or vX.Y.Z-rc.N" - -cd "$(dirname "$0")/.." -action=actions/verify/action.yml -marker='default: "" # stamped by script/stamp-verify-action' - -[ "$(grep -cF "$marker" "$action")" -eq 1 ] || - die "$action must contain exactly one line with: $marker" - -sha256() { - if command -v sha256sum >/dev/null; then - sha256sum "$1" | awk '{ print $1 }' - else - shasum -a 256 "$1" | awk '{ print $1 }' - fi -} - -{ - echo "# $tag" - for a in linux-amd64 linux-arm64 darwin-amd64 darwin-arm64 windows-amd64.exe windows-arm64.exe; do - [ -f "$assets/$a" ] || die "missing release asset $assets/$a" - echo "$(sha256 "$assets/$a") $a" - done -} >actions/verify/checksums.txt - -tmp="$(mktemp)" -awk -v m="$marker" -v r="default: $tag" '{ i = index($0, m); if (i) $0 = substr($0, 1, i - 1) r; print }' "$action" >"$tmp" -mv "$tmp" "$action" diff --git a/script/stamp-verify-action-test b/script/stamp-verify-action-test deleted file mode 100755 index 48f642de..00000000 --- a/script/stamp-verify-action-test +++ /dev/null @@ -1,49 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -root="$(cd "$(dirname "$0")/.." && pwd)" -tmp="$(mktemp -d)" -trap 'rm -r "$tmp"' EXIT - -mkdir -p "$tmp/repo/script" "$tmp/repo/actions/verify" "$tmp/assets" -cp "$root/script/stamp-verify-action" "$tmp/repo/script/" -cp "$root/actions/verify/action.yml" "$tmp/repo/actions/verify/" -for a in linux-amd64 linux-arm64 darwin-amd64 darwin-arm64 windows-amd64.exe windows-arm64.exe; do - printf '%s' "$a" >"$tmp/assets/$a" -done - -fail() { - echo "FAIL: $*" >&2 - exit 1 -} - -if "$tmp/repo/script/stamp-verify-action" 'v1.2.3;x' "$tmp/assets" 2>/dev/null; then - fail "accepted an invalid tag" -fi - -rm "$tmp/assets/windows-arm64.exe" -if "$tmp/repo/script/stamp-verify-action" v1.2.3 "$tmp/assets" 2>/dev/null; then - fail "stamped with a missing asset" -fi -printf '%s' windows-arm64.exe >"$tmp/assets/windows-arm64.exe" - -cd "$tmp" -repo/script/stamp-verify-action v1.2.3-rc.1 assets - -grep -q '^ default: v1.2.3-rc.1$' repo/actions/verify/action.yml || - fail "version default not stamped" -grep -q 'stamped by script/stamp-verify-action' repo/actions/verify/action.yml && - fail "stamp marker left behind" -[ "$(head -n 1 repo/actions/verify/checksums.txt)" = "# v1.2.3-rc.1" ] || - fail "checksums.txt header" -want="$(printf '%s' linux-arm64 | shasum -a 256 | awk '{ print $1 }')" -grep -qx "$want linux-arm64" repo/actions/verify/checksums.txt || - fail "linux-arm64 checksum" -[ "$(wc -l /dev/null; then - fail "restamped an already stamped action" -fi - -echo "stamp-verify-action tests passed" From c65397ebd8f9c045704035715f49cc6c15c8d5fd Mon Sep 17 00:00:00 2001 From: Jeff Martin Date: Wed, 18 Nov 2026 20:16:27 -0800 Subject: [PATCH 08/20] Stamp and tag the verify action from a Node script script/verify-action-release.mjs replaces the bash stamp script and the inline release workflow steps. --- .github/workflows/release.yml | 38 +------- RELEASING.md | 4 +- script/verify-action-release.mjs | 134 ++++++++++++++++++++++++++ script/verify-action-release.test.mjs | 120 +++++++++++++++++++++++ 4 files changed, 258 insertions(+), 38 deletions(-) create mode 100644 script/verify-action-release.mjs create mode 100644 script/verify-action-release.test.mjs diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 4021067a..0ec65b6a 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -52,39 +52,5 @@ jobs: with: persist-credentials: false - - name: Download and check release binaries - run: | - mkdir "$RUNNER_TEMP/assets" - cd "$RUNNER_TEMP/assets" - for a in linux-amd64 linux-arm64 darwin-amd64 darwin-arm64 windows-amd64.exe windows-arm64.exe; do - gh release download "$TAG" --repo "$REPO" --pattern "$a" - gh attestation verify "$a" --repo "$REPO" \ - --signer-workflow "$REPO/.github/workflows/release.yml" \ - --source-ref "refs/tags/$TAG" >/dev/null - done - - - name: Stamp actions/verify - run: script/stamp-verify-action "$TAG" "$RUNNER_TEMP/assets" - - # A commit created through the API is signed by GitHub, which the tag - # ruleset requires. It sits on top of the release commit, off main. - - name: Tag verify-${{ github.ref_name }} - run: | - set -euo pipefail - entries='[]' - for f in actions/verify/action.yml actions/verify/checksums.txt; do - sha="$(base64 -w0 "$f" | jq -Rn '{content: input, encoding: "base64"}' | - gh api "repos/$REPO/git/blobs" --input - --jq .sha)" - entries="$(jq -c --arg p "$f" --arg s "$sha" '. + [{path: $p, mode: "100644", type: "blob", sha: $s}]' <<<"$entries")" - done - tree="$(jq -n --arg b "$(git rev-parse 'HEAD^{tree}')" --argjson t "$entries" '{base_tree: $b, tree: $t}' | - gh api "repos/$REPO/git/trees" --input - --jq .sha)" - commit="$(jq -n --arg m "Stamp actions/verify for $TAG" --arg t "$tree" --arg p "$(git rev-parse HEAD)" \ - '{message: $m, tree: $t, parents: [$p]}' | - gh api "repos/$REPO/git/commits" --input - --jq .sha)" - [ "$(gh api "repos/$REPO/git/commits/$commit" --jq .verification.verified)" = true ] || { - echo "::error::stamp commit $commit is not signed" - exit 1 - } - gh api "repos/$REPO/git/refs" -f "ref=refs/tags/verify-$TAG" -f "sha=$commit" >/dev/null - echo "Tagged verify-$TAG at $commit" + - name: Publish verify-${{ github.ref_name }} + run: node script/verify-action-release.mjs "$TAG" diff --git a/RELEASING.md b/RELEASING.md index 24c368f5..85e9e930 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -42,8 +42,8 @@ The tag workflow verifies the tag, then publishes the binaries, attestations, and GitHub release. It then publishes the [verify action](actions/verify/README.md) for the -release. `script/stamp-verify-action` sets the action's default `version` to -the new tag and records the release binaries' checksums in +release. `script/verify-action-release.mjs` checks the release binaries' +attestations, sets the action's default `version` to the new tag and records the release binaries' checksums in `actions/verify/checksums.txt`. The workflow commits that on top of the release commit and tags it `verify-vX.Y.Z`. That commit isn't on `main`, since it holds checksums of binaries built from its parent. Don't edit the default or diff --git a/script/verify-action-release.mjs b/script/verify-action-release.mjs new file mode 100644 index 00000000..76b959f9 --- /dev/null +++ b/script/verify-action-release.mjs @@ -0,0 +1,134 @@ +// Publishes verify- for a CLI release: checks the release binaries' +// attestations, stamps actions/verify with the tag and their checksums, and tags +// a GitHub-signed commit on top of the release commit. +// +// Usage (release workflow, with GH_TOKEN and REPO set): +// node script/verify-action-release.mjs + +import { spawnSync } from "node:child_process"; +import { createHash } from "node:crypto"; +import { existsSync } from "node:fs"; +import { mkdtemp, readFile, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; + +export const ASSETS = [ + "linux-amd64", + "linux-arm64", + "darwin-amd64", + "darwin-arm64", + "windows-amd64.exe", + "windows-arm64.exe", +]; +export const ACTION = "actions/verify/action.yml"; +export const CHECKSUMS = "actions/verify/checksums.txt"; +const MARKER = 'default: "" # stamped by script/verify-action-release.mjs'; + +export function checkTag(tag) { + if (!/^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-rc\.[1-9]\d*)?$/.test(tag ?? "")) { + throw new Error(`invalid tag '${tag}'; expected vX.Y.Z or vX.Y.Z-rc.N`); + } + return tag; +} + +// stamp defaults the action's version input to tag and writes checksums.txt for +// the release binaries in assetsDir. It refuses an already stamped action. +export async function stamp({ root, tag, assetsDir }) { + checkTag(tag); + const actionPath = join(root, ACTION); + const action = await readFile(actionPath, "utf8"); + if (action.split(MARKER).length !== 2) { + throw new Error(`${ACTION} must contain exactly one line with: ${MARKER}`); + } + const lines = [`# ${tag}`]; + for (const a of ASSETS) { + const path = join(assetsDir, a); + if (!existsSync(path)) throw new Error(`missing release asset ${path}`); + lines.push(`${createHash("sha256").update(await readFile(path)).digest("hex")} ${a}`); + } + await writeFile(join(root, CHECKSUMS), lines.join("\n") + "\n"); + await writeFile(actionPath, action.replace(MARKER, `default: ${tag}`)); +} + +// publish commits files on top of head through the Git Data API, so GitHub signs +// the commit as the tag ruleset requires, and tags it verify-. +export async function publish({ api, token, repo, tag, head, baseTree, files, fetch: fetchFn = fetch }) { + const call = async (method, path, body) => { + const res = await fetchFn(`${api}/repos/${repo}/${path}`, { + method, + headers: { + authorization: `Bearer ${token}`, + accept: "application/vnd.github+json", + "content-type": "application/json", + }, + body: body && JSON.stringify(body), + }); + if (!res.ok) throw new Error(`${method} ${path}: HTTP ${res.status} ${await res.text()}`); + return res.json(); + }; + + const tree = []; + for (const { path, content } of files) { + const blob = await call("POST", "git/blobs", { content: Buffer.from(content).toString("base64"), encoding: "base64" }); + tree.push({ path, mode: "100644", type: "blob", sha: blob.sha }); + } + const { sha: treeSha } = await call("POST", "git/trees", { base_tree: baseTree, tree }); + const { sha: commit } = await call("POST", "git/commits", { + message: `Stamp actions/verify for ${tag}`, + tree: treeSha, + parents: [head], + }); + const { verification } = await call("GET", `git/commits/${commit}`); + if (!verification?.verified) throw new Error(`stamp commit ${commit} is not signed`); + await call("POST", "git/refs", { ref: `refs/tags/verify-${tag}`, sha: commit }); + return commit; +} + +function run(cmd, args, opts = {}) { + const r = spawnSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "inherit"], ...opts }); + if (r.status !== 0) throw new Error(`${cmd} ${args.join(" ")} failed`); + return r.stdout.trim(); +} + +async function main(tag) { + checkTag(tag); + const { REPO: repo, GH_TOKEN: token, GITHUB_API_URL: api = "https://api.github.com" } = process.env; + if (!repo || !token) throw new Error("set REPO and GH_TOKEN"); + const root = resolve(fileURLToPath(import.meta.url), "../.."); + + const assetsDir = await mkdtemp(join(process.env.RUNNER_TEMP ?? tmpdir(), "assets-")); + for (const a of ASSETS) { + run("gh", ["release", "download", tag, "--repo", repo, "--pattern", a, "--dir", assetsDir]); + run("gh", [ + "attestation", "verify", join(assetsDir, a), + "--repo", repo, + "--signer-workflow", `${repo}/.github/workflows/release.yml`, + "--source-ref", `refs/tags/${tag}`, + ]); + } + + await stamp({ root, tag, assetsDir }); + const files = []; + for (const path of [ACTION, CHECKSUMS]) files.push({ path, content: await readFile(join(root, path)) }); + const commit = await publish({ + api, + token, + repo, + tag, + head: run("git", ["rev-parse", "HEAD"], { cwd: root }), + baseTree: run("git", ["rev-parse", "HEAD^{tree}"], { cwd: root }), + files, + }); + console.log(`Tagged verify-${tag} at ${commit}`); +} + +if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { + try { + if (process.argv.length !== 3) throw new Error("usage: node script/verify-action-release.mjs "); + await main(process.argv[2]); + } catch (err) { + console.error(`::error::${err.message}`); + process.exitCode = 1; + } +} diff --git a/script/verify-action-release.test.mjs b/script/verify-action-release.test.mjs new file mode 100644 index 00000000..8220b8cc --- /dev/null +++ b/script/verify-action-release.test.mjs @@ -0,0 +1,120 @@ +import assert from "node:assert/strict"; +import { createHash } from "node:crypto"; +import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { afterEach, beforeEach, describe, test } from "node:test"; +import { ACTION, ASSETS, CHECKSUMS, checkTag, publish, stamp } from "./verify-action-release.mjs"; + +const repoRoot = join(dirname(fileURLToPath(import.meta.url)), ".."); + +describe("checkTag", () => { + for (const t of ["v1.2.3", "v0.0.1", "v1.2.3-rc.1"]) test(`accepts ${t}`, () => assert.equal(checkTag(t), t)); + for (const t of ["1.2.3", "v1.2.3;x", "v01.2.3", "v1.2.3-rc.0", "verify-v1.2.3", undefined]) { + test(`rejects ${t}`, () => assert.throws(() => checkTag(t), /invalid tag/)); + } +}); + +describe("stamp", () => { + let root, assetsDir; + beforeEach(async () => { + root = await mkdtemp(join(tmpdir(), "stamp-")); + assetsDir = join(root, "assets"); + await mkdir(join(root, "actions/verify"), { recursive: true }); + await mkdir(assetsDir); + await writeFile(join(root, ACTION), await readFile(join(repoRoot, ACTION))); + for (const a of ASSETS) await writeFile(join(assetsDir, a), a); + }); + afterEach(async () => { + await rm(root, { recursive: true, force: true }); + }); + + test("defaults the version input to the tag and records checksums", async () => { + await stamp({ root, tag: "v1.2.3-rc.1", assetsDir }); + const action = await readFile(join(root, ACTION), "utf8"); + assert.match(action, /^ {4}default: v1\.2\.3-rc\.1$/m); + assert.doesNotMatch(action, /stamped by/); + const lines = (await readFile(join(root, CHECKSUMS), "utf8")).trimEnd().split("\n"); + assert.equal(lines[0], "# v1.2.3-rc.1"); + assert.equal(lines.length, 1 + ASSETS.length); + const want = createHash("sha256").update("linux-arm64").digest("hex"); + assert.ok(lines.includes(`${want} linux-arm64`)); + }); + + test("rejects an invalid tag", async () => { + await assert.rejects(stamp({ root, tag: "v1.2.3;x", assetsDir }), /invalid tag/); + }); + + test("fails on a missing release asset", async () => { + await rm(join(assetsDir, "windows-arm64.exe")); + await assert.rejects(stamp({ root, tag: "v1.2.3", assetsDir }), /missing release asset/); + }); + + test("refuses to restamp", async () => { + await stamp({ root, tag: "v1.2.3", assetsDir }); + await assert.rejects(stamp({ root, tag: "v1.2.4", assetsDir }), /exactly one line/); + }); +}); + +describe("publish", () => { + function fakeAPI({ verified = true } = {}) { + const calls = []; + const fetch = async (url, { method, body, headers }) => { + assert.equal(headers.authorization, "Bearer tok"); + const path = url.replace("https://api.test/repos/o/r/", ""); + calls.push({ method, path, body: body && JSON.parse(body) }); + const res = { + "git/blobs": { sha: `blob${calls.length}` }, + "git/trees": { sha: "tree1" }, + "git/commits": { sha: "commit1" }, + "git/commits/commit1": { verification: { verified } }, + "git/refs": {}, + }[path]; + return new Response(JSON.stringify(res), { status: 201 }); + }; + return { calls, fetch }; + } + const args = { + api: "https://api.test", + token: "tok", + repo: "o/r", + tag: "v1.2.3", + head: "head1", + baseTree: "base1", + files: [ + { path: ACTION, content: "a" }, + { path: CHECKSUMS, content: "c" }, + ], + }; + + test("tags a signed commit on top of the release commit", async () => { + const { calls, fetch } = fakeAPI(); + assert.equal(await publish({ ...args, fetch }), "commit1"); + assert.deepEqual( + calls.map((c) => `${c.method} ${c.path}`), + ["POST git/blobs", "POST git/blobs", "POST git/trees", "POST git/commits", "GET git/commits/commit1", "POST git/refs"], + ); + assert.deepEqual(calls[0].body, { content: Buffer.from("a").toString("base64"), encoding: "base64" }); + assert.deepEqual(calls[2].body, { + base_tree: "base1", + tree: [ + { path: ACTION, mode: "100644", type: "blob", sha: "blob1" }, + { path: CHECKSUMS, mode: "100644", type: "blob", sha: "blob2" }, + ], + }); + assert.deepEqual(calls[3].body.parents, ["head1"]); + assert.deepEqual(calls[5].body, { ref: "refs/tags/verify-v1.2.3", sha: "commit1" }); + }); + + test("does not tag an unsigned commit", async () => { + const { calls, fetch } = fakeAPI({ verified: false }); + await assert.rejects(publish({ ...args, fetch }), /not signed/); + assert.ok(!calls.some((c) => c.path === "git/refs")); + }); + + test("surfaces API errors", async () => { + const fetch = async () => new Response("Reference already exists", { status: 422 }); + await assert.rejects(publish({ ...args, fetch }), /POST git\/blobs: HTTP 422 Reference already exists/); + }); +}); From 49840684114d9d8e1e3f087c496395f92f837c2c Mon Sep 17 00:00:00 2001 From: Jeff Martin Date: Wed, 18 Nov 2026 20:16:27 -0800 Subject: [PATCH 09/20] Run the Node tests in CI on Linux and Windows --- .github/workflows/test.yml | 2 ++ Makefile | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 7e780c16..ea7a2268 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -33,6 +33,8 @@ jobs: if: runner.os == 'Linux' - run: go test -count=1 ./... if: runner.os == 'Windows' + - run: node --test actions/verify/lib.test.mjs script/verify-action-release.test.mjs + if: runner.os == 'Windows' integration-stub: runs-on: ${{ matrix.os }} diff --git a/Makefile b/Makefile index 0a45e651..208acd6a 100644 --- a/Makefile +++ b/Makefile @@ -17,7 +17,7 @@ test: test-release test-release: script/release-test - script/stamp-verify-action-test + node --test actions/verify/lib.test.mjs script/verify-action-release.test.mjs vet: go vet ./... From a6399a4ec69099e5465c7e54e8590f91e12c9ca3 Mon Sep 17 00:00:00 2001 From: Jeff Martin Date: Thu, 19 Nov 2026 13:51:01 -0800 Subject: [PATCH 10/20] Run the verify action on node24 and download with fetch The action is now a node24 JavaScript action, so it no longer needs a shell step or curl. The download streams fetch to disk with exponential backoff on the statuses curl --retry treated as transient, and goes through HTTPS_PROXY/HTTP_PROXY/NO_PROXY like curl did. Runners whose node24 predates http.setGlobalProxyFromEnv re-run the script with NODE_USE_ENV_PROXY=1. A missing gh now says it's needed for the attestation check. --- actions/verify/README.md | 4 +- actions/verify/action.yml | 11 +---- actions/verify/lib.mjs | 66 +++++++++++++++++++++++--- actions/verify/lib.test.mjs | 94 ++++++++++++++++++++++++++++++++++--- actions/verify/verify.mjs | 24 ++++++---- 5 files changed, 165 insertions(+), 34 deletions(-) diff --git a/actions/verify/README.md b/actions/verify/README.md index e45410b9..87d3bb69 100644 --- a/actions/verify/README.md +++ b/actions/verify/README.md @@ -12,7 +12,7 @@ steps: Use the [latest `verify-v*` tag](https://github.com/github/gh-actions-lock/tags). Every CLI release `vX.Y.Z` publishes `verify-vX.Y.Z`, which runs that CLI version by default, so a Dependabot bump of this action is also a CLI bump. Check out the repository before this step. -The action runs on Linux, macOS and Windows runners, on x64 and arm64. It needs `node` (20 or later) on `PATH`, which GitHub-hosted runners have. +It's a Node action (`node24`) that uses only Node built-ins, so it runs on the runner's own Node on Linux, macOS and Windows, x64 and arm64. Self-hosted runners need [runner v2.327.1](https://github.com/actions/runner/releases/tag/v2.327.1) or later for `node24` actions. Downloads honor `HTTPS_PROXY`, `HTTP_PROXY` and `NO_PROXY`. ## Inputs @@ -22,7 +22,7 @@ The action runs on Linux, macOS and Windows runners, on x64 and arm64. It needs | `version` | the CLI release the tag was cut with | `gh-actions-lock` release to run, such as `v0.4.1`. | | `args` | `--verify` | Arguments passed to `gh-actions-lock`, split on whitespace and newlines. For example, `--verify --fail-on-warning`. | -With the default `version`, the binary is checked against checksums recorded in the tag. With another `version`, it's checked against the release's build attestation on github.com using `token`. On GHE.com, that check uses `GH_ACTIONS_LOCK_GITHUB_COM_TOKEN` instead, so your tenant token never leaves the tenant. +With the default `version`, the binary is checked against checksums recorded in the tag. With another `version`, it's checked against the release's build attestation on github.com using `token`, which needs the GitHub CLI (`gh`) on `PATH`. GitHub-hosted runners have it; self-hosted runners may not. On GHE.com, that check uses `GH_ACTIONS_LOCK_GITHUB_COM_TOKEN` instead, so your tenant token never leaves the tenant. ## Private and internal actions diff --git a/actions/verify/action.yml b/actions/verify/action.yml index 5784c83f..828bca9a 100644 --- a/actions/verify/action.yml +++ b/actions/verify/action.yml @@ -16,12 +16,5 @@ inputs: default: --verify runs: - using: composite - steps: - - name: Verify actions.lock - shell: bash - env: - INPUT_TOKEN: ${{ inputs.token }} - INPUT_VERSION: ${{ inputs.version }} - INPUT_ARGS: ${{ inputs.args }} - run: node "$GITHUB_ACTION_PATH/verify.mjs" + using: node24 + main: verify.mjs diff --git a/actions/verify/lib.mjs b/actions/verify/lib.mjs index f1f228f3..981dcded 100644 --- a/actions/verify/lib.mjs +++ b/actions/verify/lib.mjs @@ -2,9 +2,12 @@ import { spawnSync } from "node:child_process"; import { createHash } from "node:crypto"; -import { existsSync } from "node:fs"; +import { createWriteStream, existsSync } from "node:fs"; import { chmod, mkdir, readFile } from "node:fs/promises"; import { join } from "node:path"; +import { Readable } from "node:stream"; +import { pipeline } from "node:stream/promises"; +import { setTimeout as sleep } from "node:timers/promises"; export const REPO = "github/gh-actions-lock"; @@ -75,20 +78,69 @@ export async function sha256File(path) { return createHash("sha256").update(await readFile(path)).digest("hex"); } -// curl, unlike Node 20's fetch, honors the runner's proxy settings and backs off between retries. -function curl(url, dest) { - const r = spawnSync("curl", ["-fsSL", "--retry", "3", "-o", dest, url], { stdio: ["ignore", "ignore", "inherit"] }); - return r.status === 0; +// The statuses curl --retry treats as transient. +const transient = new Set([408, 429, 500, 502, 503, 504]); + +// downloadFile streams url to dest, retrying network errors and transient statuses +// with exponential backoff. +export async function downloadFile(url, dest, { fetch: get = fetch, retries = 3, delayMs = 1000, wait = sleep } = {}) { + for (let attempt = 0; ; attempt++) { + let retry = true; + try { + const res = await get(url); + if (!res.ok) { + retry = transient.has(res.status); + throw new Error(`HTTP ${res.status}`); + } + await pipeline(Readable.fromWeb(res.body), createWriteStream(dest)); + return; + } catch (err) { + if (!retry || attempt >= retries) throw new ActionError(`download ${url} failed: ${err.cause?.message ?? err.message}`); + await wait(delayMs * 2 ** attempt); + } + } +} + +// withSubdomainNoProxy adds .example.com for each bare NO_PROXY entry example.com. +// curl and node 24.22 let a bare entry match subdomains too, but node24 before that +// matches it exactly, so release-assets.githubusercontent.com would go through the +// proxy despite NO_PROXY=githubusercontent.com. +export function withSubdomainNoProxy(env) { + const out = { ...env }; + for (const key of ["NO_PROXY", "no_proxy"]) { + if (!out[key]) continue; + const entries = out[key].split(",").map((e) => e.trim()).filter(Boolean); + const extra = entries.filter((e) => !/^[.*]/.test(e) && !e.includes("/") && !entries.includes(`.${e}`)).map((e) => `.${e}`); + out[key] = [...entries, ...extra].join(","); + } + return out; +} + +// useEnvProxy routes fetch through the runner's HTTPS_PROXY or HTTP_PROXY, honoring +// NO_PROXY. http.setGlobalProxyFromEnv needs Node 24.14; older node24 runners +// re-run this script with NODE_USE_ENV_PROXY=1 instead. Returns true when the +// caller must re-run. +export function useEnvProxy(env, http) { + const proxied = ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy"].some((k) => env[k]); + if (!proxied) return false; + if (typeof http.setGlobalProxyFromEnv === "function") { + http.setGlobalProxyFromEnv(env); + return false; + } + return env.NODE_USE_ENV_PROXY !== "1"; } function runGh(args, env) { const r = spawnSync("gh", args, { env, stdio: ["ignore", "ignore", "inherit"] }); + if (r.error?.code === "ENOENT") { + throw new ActionError("gh is not on PATH; it's needed to check a version other than the one this action tag was released with"); + } return r.status === 0; } // install downloads the gh-actions-lock binary for this runner into RUNNER_TEMP, // checks it and returns its path. -export async function install({ env, actionDir, download = curl, gh = runGh, log = console.log }) { +export async function install({ env, actionDir, download = downloadFile, gh = runGh, log = console.log }) { const version = checkVersion(env.INPUT_VERSION); const { asset, ext } = assetFor(env.RUNNER_OS, env.RUNNER_ARCH); if (!env.RUNNER_TEMP) throw new ActionError("RUNNER_TEMP is not set"); @@ -102,7 +154,7 @@ export async function install({ env, actionDir, download = curl, gh = runGh, log await mkdir(dir, { recursive: true }); const bin = join(dir, `gh-actions-lock${ext}`); const url = `https://github.com/${REPO}/releases/download/${version}/${asset}`; - if (!(await download(url, bin))) throw new ActionError(`download ${url} failed`); + await download(url, bin); if (check.kind === "checksum") { const got = await sha256File(bin); diff --git a/actions/verify/lib.test.mjs b/actions/verify/lib.test.mjs index 0adcecf3..20e08449 100644 --- a/actions/verify/lib.test.mjs +++ b/actions/verify/lib.test.mjs @@ -4,7 +4,7 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { afterEach, beforeEach, describe, test } from "node:test"; -import { ActionError, assetFor, attestationEnv, checkVersion, install, selectCheck, splitArgs } from "./lib.mjs"; +import { ActionError, assetFor, attestationEnv, checkVersion, downloadFile, install, selectCheck, splitArgs, useEnvProxy, withSubdomainNoProxy } from "./lib.mjs"; const sha = (s) => createHash("sha256").update(s).digest("hex"); @@ -105,7 +105,7 @@ describe("install", () => { }); const binary = "fake gh-actions-lock"; - const okDownload = async (url, dest) => (await writeFile(dest, binary), true); + const okDownload = (url, dest) => writeFile(dest, binary); const quiet = () => {}; async function stampedAction(version, asset, sum = sha(binary)) { @@ -176,6 +176,11 @@ describe("install", () => { ); }); + test("names gh when it's missing for an attestation check", async () => { + const env = { INPUT_VERSION: "v0.4.2", RUNNER_OS: "Linux", RUNNER_ARCH: "X64", RUNNER_TEMP: tmp, PATH: "", Path: "" }; + await assert.rejects(install({ env, actionDir: tmp, download: okDownload, log: quiet }), /gh is not on PATH/); + }); + test("checks the token scope before downloading", async () => { const env = { INPUT_VERSION: "v0.4.2", @@ -189,13 +194,88 @@ describe("install", () => { /GH_ACTIONS_LOCK_GITHUB_COM_TOKEN/, ); }); +}); - test("fails when the download fails", async () => { - const env = { INPUT_VERSION: "v0.4.1", RUNNER_OS: "Linux", RUNNER_ARCH: "X64", RUNNER_TEMP: tmp }; - const actionDir = await stampedAction("v0.4.1", "linux-amd64"); +describe("downloadFile", () => { + let tmp; + beforeEach(async () => { + tmp = await mkdtemp(join(tmpdir(), "verify-download-")); + }); + afterEach(async () => { + await rm(tmp, { recursive: true, force: true }); + }); + + const respond = (status, body = "") => new Response(status === 200 ? body : null, { status }); + + test("retries transient failures with backoff, then streams the body to disk", async () => { + const dest = join(tmp, "bin"); + const replies = [() => { throw new TypeError("fetch failed", { cause: new Error("ECONNRESET") }); }, () => respond(503), () => respond(200, "binary")]; + const waits = []; + await downloadFile("https://example.test/a", dest, { + fetch: async () => replies.shift()(), + wait: async (ms) => waits.push(ms), + }); + assert.equal(await readFile(dest, "utf8"), "binary"); + assert.deepEqual(waits, [1000, 2000]); + }); + + test("does not retry a missing release", async () => { + let calls = 0; await assert.rejects( - install({ env, actionDir, download: () => false, gh: () => true, log: quiet }), - /download https:\/\/github.com\/github\/gh-actions-lock\/releases\/download\/v0.4.1\/linux-amd64 failed/, + downloadFile("https://example.test/v9.9.9/linux-amd64", join(tmp, "bin"), { + fetch: async () => (calls++, respond(404)), + wait: async () => assert.fail("retried"), + }), + (err) => err instanceof ActionError && /download https:\/\/example.test\/v9.9.9\/linux-amd64 failed: HTTP 404/.test(err.message), ); + assert.equal(calls, 1); + }); + + test("gives up after three retries and reports the cause", async () => { + let calls = 0; + await assert.rejects( + downloadFile("https://example.test/a", join(tmp, "bin"), { + fetch: async () => { calls++; throw new TypeError("fetch failed", { cause: new Error("getaddrinfo ENOTFOUND") }); }, + wait: async () => {}, + }), + /failed: getaddrinfo ENOTFOUND/, + ); + assert.equal(calls, 4); + }); +}); + +describe("useEnvProxy", () => { + test("does nothing without a proxy", () => { + const http = { setGlobalProxyFromEnv: () => assert.fail("set proxy") }; + assert.equal(useEnvProxy({ NO_PROXY: "example.test" }, http), false); + }); + for (const key of ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy"]) { + test(`applies ${key} in process when Node supports it`, () => { + const env = { [key]: "http://proxy.test:3128" }; + let got; + assert.equal(useEnvProxy(env, { setGlobalProxyFromEnv: (e) => (got = e) }), false); + assert.equal(got, env); + }); + } + test("asks for a re-run with NODE_USE_ENV_PROXY on older Node", () => { + assert.equal(useEnvProxy({ https_proxy: "http://proxy.test:3128" }, {}), true); + }); + test("does not re-run twice", () => { + assert.equal(useEnvProxy({ https_proxy: "http://proxy.test:3128", NODE_USE_ENV_PROXY: "1" }, {}), false); + }); +}); + +describe("withSubdomainNoProxy", () => { + test("adds a subdomain entry for each bare host, in both cases", () => { + const env = withSubdomainNoProxy({ NO_PROXY: "github.com, .example.test,*.corp,10.0.0.0/8", no_proxy: "githubusercontent.com" }); + assert.equal(env.NO_PROXY, "github.com,.example.test,*.corp,10.0.0.0/8,.github.com"); + assert.equal(env.no_proxy, "githubusercontent.com,.githubusercontent.com"); + }); + test("is idempotent across the proxy re-run", () => { + const once = withSubdomainNoProxy({ no_proxy: "github.com" }); + assert.deepEqual(withSubdomainNoProxy(once), once); + }); + test("leaves env without NO_PROXY alone", () => { + assert.deepEqual(withSubdomainNoProxy({ HTTPS_PROXY: "http://p:1" }), { HTTPS_PROXY: "http://p:1" }); }); }); diff --git a/actions/verify/verify.mjs b/actions/verify/verify.mjs index dbb6aba4..3d46fd50 100644 --- a/actions/verify/verify.mjs +++ b/actions/verify/verify.mjs @@ -1,17 +1,23 @@ import { spawnSync } from "node:child_process"; +import http from "node:http"; import { dirname } from "node:path"; import { fileURLToPath } from "node:url"; -import { install, splitArgs } from "./lib.mjs"; +import { install, splitArgs, useEnvProxy, withSubdomainNoProxy } from "./lib.mjs"; -try { - const env = process.env; - const bin = await install({ env, actionDir: dirname(fileURLToPath(import.meta.url)) }); - const r = spawnSync(bin, splitArgs(env.INPUT_ARGS), { - stdio: "inherit", - env: { ...env, GH_TOKEN: env.INPUT_TOKEN ?? "" }, - }); +const run = (cmd, args, env) => { + const r = spawnSync(cmd, args, { stdio: "inherit", env }); if (r.error) throw r.error; - process.exitCode = r.status ?? 1; + return r.status ?? 1; +}; + +try { + const env = withSubdomainNoProxy(process.env); + if (useEnvProxy(env, http)) { + process.exitCode = run(process.execPath, [fileURLToPath(import.meta.url)], { ...env, NODE_USE_ENV_PROXY: "1" }); + } else { + const bin = await install({ env, actionDir: dirname(fileURLToPath(import.meta.url)) }); + process.exitCode = run(bin, splitArgs(env.INPUT_ARGS), { ...env, GH_TOKEN: env.INPUT_TOKEN ?? "" }); + } } catch (err) { console.error(`::error::${err.message}`); process.exitCode = 1; From 8696c12f4c9a6d6ac3a32d6314fda8acfedcd8cc Mon Sep 17 00:00:00 2001 From: Jeff Martin Date: Thu, 19 Nov 2026 14:18:33 -0800 Subject: [PATCH 11/20] Stamp actions/verify on main so the workflow needs no version --- .github/workflows/verify-lockfile.yml | 8 +++---- RELEASING.md | 15 ++++++++----- actions/verify/README.md | 4 ++-- actions/verify/action.yml | 4 ++-- actions/verify/checksums.txt | 7 ++++++ actions/verify/lib.mjs | 6 +++--- script/verify-action-release.mjs | 31 ++++++++++++++++++--------- script/verify-action-release.test.mjs | 26 +++++++++++++++++++--- 8 files changed, 71 insertions(+), 30 deletions(-) create mode 100644 actions/verify/checksums.txt diff --git a/.github/workflows/verify-lockfile.yml b/.github/workflows/verify-lockfile.yml index ad9af7bd..83cc5252 100644 --- a/.github/workflows/verify-lockfile.yml +++ b/.github/workflows/verify-lockfile.yml @@ -1,9 +1,9 @@ # Fails when .github/workflows/actions.lock is out of sync with the # workflows or a locked pin no longer verifies upstream. # -# This repository runs its own actions/verify at the workflow commit, so the -# version is set here. Other repositories pin a verify-v* tag instead; see -# actions/verify/README.md. +# This repository runs its own actions/verify at the workflow commit, with the +# CLI release stamped on main. Other repositories pin a verify-v* tag instead; +# see actions/verify/README.md. name: verify-lockfile @@ -24,5 +24,3 @@ jobs: with: persist-credentials: false - uses: $/actions/verify - with: - version: v0.4.1 diff --git a/RELEASING.md b/RELEASING.md index 85e9e930..1eee3c36 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -43,11 +43,16 @@ and GitHub release. It then publishes the [verify action](actions/verify/README.md) for the release. `script/verify-action-release.mjs` checks the release binaries' -attestations, sets the action's default `version` to the new tag and records the release binaries' checksums in -`actions/verify/checksums.txt`. The workflow commits that on top of the release -commit and tags it `verify-vX.Y.Z`. That commit isn't on `main`, since it -holds checksums of binaries built from its parent. Don't edit the default or -the checksums by hand. +attestations, sets the action's default `version` to the new tag and records the +release binaries' checksums in `actions/verify/checksums.txt`. The workflow +commits that on top of the release commit and tags it `verify-vX.Y.Z`. Don't +edit the default or the checksums by hand. + +`main` also carries a stamp, so this repository's own `verify-lockfile` +workflow runs the action the way other repositories do. It can trail the latest +release; the release workflow restamps on top of it either way. To move it, run +`node script/verify-action-release.mjs --stamp-only vX.Y.Z` (it checks the +attestations with `gh`) and open a pull request with the result. ## Dependabot compatibility diff --git a/actions/verify/README.md b/actions/verify/README.md index 87d3bb69..8cb0e1d3 100644 --- a/actions/verify/README.md +++ b/actions/verify/README.md @@ -19,10 +19,10 @@ It's a Node action (`node24`) that uses only Node built-ins, so it runs on the r | Input | Default | Description | |---|---|---| | `token` | `${{ github.token }}` | Token the CLI uses to read action repositories. | -| `version` | the CLI release the tag was cut with | `gh-actions-lock` release to run, such as `v0.4.1`. | +| `version` | the CLI release the tag was cut with | `gh-actions-lock` release to run, such as `v0.5.1`. | | `args` | `--verify` | Arguments passed to `gh-actions-lock`, split on whitespace and newlines. For example, `--verify --fail-on-warning`. | -With the default `version`, the binary is checked against checksums recorded in the tag. With another `version`, it's checked against the release's build attestation on github.com using `token`, which needs the GitHub CLI (`gh`) on `PATH`. GitHub-hosted runners have it; self-hosted runners may not. On GHE.com, that check uses `GH_ACTIONS_LOCK_GITHUB_COM_TOKEN` instead, so your tenant token never leaves the tenant. +With the default `version`, the binary is checked against checksums recorded in the action. With another `version`, it's checked against the release's build attestation on github.com using `token`, which needs the GitHub CLI (`gh`) on `PATH`. GitHub-hosted runners have it; self-hosted runners may not. On GHE.com, that check uses `GH_ACTIONS_LOCK_GITHUB_COM_TOKEN` instead, so your tenant token never leaves the tenant. ## Private and internal actions diff --git a/actions/verify/action.yml b/actions/verify/action.yml index 828bca9a..3fd20659 100644 --- a/actions/verify/action.yml +++ b/actions/verify/action.yml @@ -7,9 +7,9 @@ inputs: required: false default: ${{ github.token }} version: - description: gh-actions-lock release to run, such as v0.4.1. Release tags of this action default it to the CLI release they were cut with. + description: gh-actions-lock release to run, such as v0.5.1. Defaults to the CLI release this action was stamped with. required: false - default: "" # stamped by script/verify-action-release.mjs + default: v0.5.1 # stamped by script/verify-action-release.mjs args: description: Arguments passed to gh-actions-lock, split on whitespace. required: false diff --git a/actions/verify/checksums.txt b/actions/verify/checksums.txt new file mode 100644 index 00000000..a09062fe --- /dev/null +++ b/actions/verify/checksums.txt @@ -0,0 +1,7 @@ +# v0.5.1 +94009f287cfcc046ff371824824c203a8a44c981ca2dac344052744897c29c3a linux-amd64 +b51f0ba96784950bf945272c7e0d3f9fb4c53d378b37070f8eb6cdbe71b190a8 linux-arm64 +daed4b624525ca04e088e1310dd80e06a410116ece41554b9f1d582b93a2c909 darwin-amd64 +223fa3e843a560a23964a5d0e037f500ad42b4e0c57b995f1ec99766355ae11e darwin-arm64 +24377e9ed1f53d131157649741ac003fd563f0b4d21b4a7a978881f67a412888 windows-amd64.exe +ef788440a3a822fdffb7b5b6682f91d30d3db0480575401ff5ee5ce70280e886 windows-arm64.exe diff --git a/actions/verify/lib.mjs b/actions/verify/lib.mjs index 981dcded..6227af39 100644 --- a/actions/verify/lib.mjs +++ b/actions/verify/lib.mjs @@ -43,7 +43,7 @@ export function splitArgs(input) { } // selectCheck picks how to check the binary: the checksum stamped into this action -// tag when version is the release it was stamped with, otherwise the release's +// when version is the release it was stamped with, otherwise the release's // build attestation. checksums is the text of checksums.txt, or null. export function selectCheck(version, checksums, asset) { const lines = checksums?.split(/\r?\n/) ?? []; @@ -65,7 +65,7 @@ export function attestationEnv(env) { token = env.GH_ACTIONS_LOCK_GITHUB_COM_TOKEN ?? ""; if (!token) { throw new ActionError( - `set GH_ACTIONS_LOCK_GITHUB_COM_TOKEN to check ${env.INPUT_VERSION}, or use the version this action tag was released with`, + `set GH_ACTIONS_LOCK_GITHUB_COM_TOKEN to check ${env.INPUT_VERSION}, or use the version this action was stamped with`, ); } } @@ -133,7 +133,7 @@ export function useEnvProxy(env, http) { function runGh(args, env) { const r = spawnSync("gh", args, { env, stdio: ["ignore", "ignore", "inherit"] }); if (r.error?.code === "ENOENT") { - throw new ActionError("gh is not on PATH; it's needed to check a version other than the one this action tag was released with"); + throw new ActionError("gh is not on PATH; it's needed to check a version other than the one this action was stamped with"); } return r.status === 0; } diff --git a/script/verify-action-release.mjs b/script/verify-action-release.mjs index 76b959f9..b078cd88 100644 --- a/script/verify-action-release.mjs +++ b/script/verify-action-release.mjs @@ -4,6 +4,8 @@ // // Usage (release workflow, with GH_TOKEN and REPO set): // node script/verify-action-release.mjs +// To restamp the working tree only, for example to move main to a newer release: +// node script/verify-action-release.mjs --stamp-only import { spawnSync } from "node:child_process"; import { createHash } from "node:crypto"; @@ -23,7 +25,8 @@ export const ASSETS = [ ]; export const ACTION = "actions/verify/action.yml"; export const CHECKSUMS = "actions/verify/checksums.txt"; -const MARKER = 'default: "" # stamped by script/verify-action-release.mjs'; +const MARKER = "# stamped by script/verify-action-release.mjs"; +const STAMP = /^(\s*default: )\S+( # stamped by script\/verify-action-release\.mjs)$/m; export function checkTag(tag) { if (!/^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-rc\.[1-9]\d*)?$/.test(tag ?? "")) { @@ -33,13 +36,14 @@ export function checkTag(tag) { } // stamp defaults the action's version input to tag and writes checksums.txt for -// the release binaries in assetsDir. It refuses an already stamped action. +// the release binaries in assetsDir, replacing any earlier stamp. The marker +// comment stays so main and every verify-v* tag can be restamped the same way. export async function stamp({ root, tag, assetsDir }) { checkTag(tag); const actionPath = join(root, ACTION); const action = await readFile(actionPath, "utf8"); - if (action.split(MARKER).length !== 2) { - throw new Error(`${ACTION} must contain exactly one line with: ${MARKER}`); + if (action.split(MARKER).length !== 2 || !STAMP.test(action)) { + throw new Error(`${ACTION} must contain exactly one line like: default: vX.Y.Z ${MARKER}`); } const lines = [`# ${tag}`]; for (const a of ASSETS) { @@ -48,7 +52,7 @@ export async function stamp({ root, tag, assetsDir }) { lines.push(`${createHash("sha256").update(await readFile(path)).digest("hex")} ${a}`); } await writeFile(join(root, CHECKSUMS), lines.join("\n") + "\n"); - await writeFile(actionPath, action.replace(MARKER, `default: ${tag}`)); + await writeFile(actionPath, action.replace(STAMP, `$1${tag}$2`)); } // publish commits files on top of head through the Git Data API, so GitHub signs @@ -91,10 +95,10 @@ function run(cmd, args, opts = {}) { return r.stdout.trim(); } -async function main(tag) { +async function main(tag, { stampOnly = false } = {}) { checkTag(tag); - const { REPO: repo, GH_TOKEN: token, GITHUB_API_URL: api = "https://api.github.com" } = process.env; - if (!repo || !token) throw new Error("set REPO and GH_TOKEN"); + const { REPO: repo = stampOnly ? "github/gh-actions-lock" : undefined, GH_TOKEN: token, GITHUB_API_URL: api = "https://api.github.com" } = process.env; + if (!repo || (!token && !stampOnly)) throw new Error("set REPO and GH_TOKEN"); const root = resolve(fileURLToPath(import.meta.url), "../.."); const assetsDir = await mkdtemp(join(process.env.RUNNER_TEMP ?? tmpdir(), "assets-")); @@ -109,6 +113,10 @@ async function main(tag) { } await stamp({ root, tag, assetsDir }); + if (stampOnly) { + console.log(`Stamped ${ACTION} and ${CHECKSUMS} for ${tag}`); + return; + } const files = []; for (const path of [ACTION, CHECKSUMS]) files.push({ path, content: await readFile(join(root, path)) }); const commit = await publish({ @@ -125,8 +133,11 @@ async function main(tag) { if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { try { - if (process.argv.length !== 3) throw new Error("usage: node script/verify-action-release.mjs "); - await main(process.argv[2]); + const args = process.argv.slice(2); + const stampOnly = args[0] === "--stamp-only"; + if (stampOnly) args.shift(); + if (args.length !== 1) throw new Error("usage: node script/verify-action-release.mjs [--stamp-only] "); + await main(args[0], { stampOnly }); } catch (err) { console.error(`::error::${err.message}`); process.exitCode = 1; diff --git a/script/verify-action-release.test.mjs b/script/verify-action-release.test.mjs index 8220b8cc..ba98eff3 100644 --- a/script/verify-action-release.test.mjs +++ b/script/verify-action-release.test.mjs @@ -16,6 +16,18 @@ describe("checkTag", () => { } }); +describe("checked-in stamp", () => { + test("the version default matches checksums.txt, which covers every asset", async () => { + const action = await readFile(join(repoRoot, ACTION), "utf8"); + const tag = action.match(/^ {4}default: (\S+) # stamped by/m)?.[1]; + assert.equal(checkTag(tag), tag); + const lines = (await readFile(join(repoRoot, CHECKSUMS), "utf8")).trimEnd().split("\n"); + assert.equal(lines[0], `# ${tag}`); + assert.deepEqual(lines.slice(1).map((l) => l.split(/\s+/)[1]), ASSETS); + for (const l of lines.slice(1)) assert.match(l, /^[0-9a-f]{64} \S+$/); + }); +}); + describe("stamp", () => { let root, assetsDir; beforeEach(async () => { @@ -33,8 +45,7 @@ describe("stamp", () => { test("defaults the version input to the tag and records checksums", async () => { await stamp({ root, tag: "v1.2.3-rc.1", assetsDir }); const action = await readFile(join(root, ACTION), "utf8"); - assert.match(action, /^ {4}default: v1\.2\.3-rc\.1$/m); - assert.doesNotMatch(action, /stamped by/); + assert.match(action, /^ {4}default: v1\.2\.3-rc\.1 # stamped by/m); const lines = (await readFile(join(root, CHECKSUMS), "utf8")).trimEnd().split("\n"); assert.equal(lines[0], "# v1.2.3-rc.1"); assert.equal(lines.length, 1 + ASSETS.length); @@ -51,8 +62,17 @@ describe("stamp", () => { await assert.rejects(stamp({ root, tag: "v1.2.3", assetsDir }), /missing release asset/); }); - test("refuses to restamp", async () => { + test("restamps an earlier stamp and keeps the marker", async () => { await stamp({ root, tag: "v1.2.3", assetsDir }); + await stamp({ root, tag: "v1.2.4", assetsDir }); + const action = await readFile(join(root, ACTION), "utf8"); + assert.match(action, /^ default: v1\.2\.4 # stamped by script\/verify-action-release\.mjs$/m); + assert.match(await readFile(join(root, CHECKSUMS), "utf8"), /^# v1\.2\.4\n/); + }); + + test("refuses an action without exactly one stamp line", async () => { + const action = await readFile(join(root, ACTION), "utf8"); + await writeFile(join(root, ACTION), action + action); await assert.rejects(stamp({ root, tag: "v1.2.4", assetsDir }), /exactly one line/); }); }); From 6ea0ff1deee449d02058c3b935c6b4464faa2a72 Mon Sep 17 00:00:00 2001 From: Jeff Martin Date: Thu, 19 Nov 2026 14:21:43 -0800 Subject: [PATCH 12/20] Require main's verify action stamp before the next release --- RELEASING.md | 9 ++++++--- actions/verify/README.md | 2 +- script/release | 15 ++++++++++++++- script/release-test | 21 +++++++++++++++++++++ script/verify-action-release.mjs | 2 +- 5 files changed, 43 insertions(+), 6 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index 1eee3c36..84b4b916 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -49,10 +49,13 @@ commits that on top of the release commit and tags it `verify-vX.Y.Z`. Don't edit the default or the checksums by hand. `main` also carries a stamp, so this repository's own `verify-lockfile` -workflow runs the action the way other repositories do. It can trail the latest -release; the release workflow restamps on top of it either way. To move it, run +workflow runs the action the way other repositories do. The stamp for a release +can only land after it: the binaries embed the commit they're built from. So +after each release, run `node script/verify-action-release.mjs --stamp-only vX.Y.Z` (it checks the -attestations with `gh`) and open a pull request with the result. +attestations with `gh`) and merge the result. `script/release` refuses to cut +the next release, including a release candidate, until `main` is stamped for +the latest stable release. Stamp `main` with stable releases only. ## Dependabot compatibility diff --git a/actions/verify/README.md b/actions/verify/README.md index 8cb0e1d3..5aebb3e0 100644 --- a/actions/verify/README.md +++ b/actions/verify/README.md @@ -19,7 +19,7 @@ It's a Node action (`node24`) that uses only Node built-ins, so it runs on the r | Input | Default | Description | |---|---|---| | `token` | `${{ github.token }}` | Token the CLI uses to read action repositories. | -| `version` | the CLI release the tag was cut with | `gh-actions-lock` release to run, such as `v0.5.1`. | +| `version` | the CLI release the action was stamped with; each `verify-vX.Y.Z` tag uses `vX.Y.Z` | `gh-actions-lock` release to run, such as `v0.5.1`. | | `args` | `--verify` | Arguments passed to `gh-actions-lock`, split on whitespace and newlines. For example, `--verify --fail-on-warning`. | With the default `version`, the binary is checked against checksums recorded in the action. With another `version`, it's checked against the release's build attestation on github.com using `token`, which needs the GitHub CLI (`gh`) on `PATH`. GitHub-hosted runners have it; self-hosted runners may not. On GHE.com, that check uses `GH_ACTIONS_LOCK_GITHUB_COM_TOKEN` instead, so your tenant token never leaves the tenant. diff --git a/script/release b/script/release index d9f6ed1c..7ee1f054 100755 --- a/script/release +++ b/script/release @@ -14,7 +14,8 @@ # RELEASE_DRY_RUN=1 Compute and print the next version, then stop before # tagging or pushing. # -# Requires: git, go, make. +# Requires: git, go, make, and actions/verify on main stamped for the latest +# release (see RELEASING.md). set -euo pipefail @@ -48,6 +49,17 @@ require_current_main() { die "release commit ${commit} is not current main ${main}" } +# The verify action on main must carry the latest release's stamp before the +# next release. The stamp can't land with its own release: the binaries embed the +# commit they're built from, so their checksums only exist after the tag. +require_current_stamp() { + local latest="$1" + local stamped + stamped="$( (git show refs/remotes/origin/main:actions/verify/checksums.txt 2>/dev/null || true) | head -n 1)" + [ "$stamped" = "# ${latest}" ] || + die "actions/verify on main isn't stamped for ${latest} (got '${stamped}'); run 'node script/verify-action-release.mjs --stamp-only ${latest}' and merge that first" +} + require_clean() { if [ -n "$(git status --porcelain)" ]; then git --no-pager status --short >&2 @@ -96,6 +108,7 @@ cut_tag() { base="0.0.0" echo "No existing ${TAG_PREFIX}* release tag; basing bump on v0.0.0." else + require_current_stamp "$latest" base="${latest#"$TAG_PREFIX"}" fi diff --git a/script/release-test b/script/release-test index c8311d45..1f0d51ff 100755 --- a/script/release-test +++ b/script/release-test @@ -15,6 +15,8 @@ mkdir script cp "$root/script/release" script/release cp "$root/script/verify-release-tag" script/verify-release-tag touch tracked +mkdir -p actions/verify +printf '# v1.2.3\n' >actions/verify/checksums.txt git add . git commit --quiet -m initial git push --quiet -u origin main @@ -39,6 +41,25 @@ output="$(RELEASE_DRY_RUN=1 script/release patch --rc)" output="$(RELEASE_DRY_RUN=1 script/release patch)" [[ "$output" == *"Cutting v1.2.4 "* ]] +printf '# v1.2.2\n' >actions/verify/checksums.txt +git commit --quiet -am "stale stamp" +git push --quiet origin main +if output="$(RELEASE_DRY_RUN=1 script/release patch 2>&1)"; then + echo "expected a stale verify action stamp to block the release" >&2 + exit 1 +fi +[[ "$output" == *"isn't stamped for v1.2.3"* ]] +git rm --quiet actions/verify/checksums.txt +git commit --quiet -m "no stamp" +git push --quiet origin main +if output="$(RELEASE_DRY_RUN=1 script/release patch 2>&1)"; then + echo "expected a missing verify action stamp to block the release" >&2 + exit 1 +fi +[[ "$output" == *"isn't stamped for v1.2.3"* ]] +git reset --quiet --hard HEAD~2 +git push --quiet --force origin main + ancestor="$(git rev-parse HEAD)" tree="$(git rev-parse "${ancestor}^{tree}")" descendant="$(printf 'descendant\n' | git -c user.name=test -c user.email=test@example.com commit-tree "$tree" -p "$ancestor")" diff --git a/script/verify-action-release.mjs b/script/verify-action-release.mjs index b078cd88..fae7c190 100644 --- a/script/verify-action-release.mjs +++ b/script/verify-action-release.mjs @@ -45,7 +45,7 @@ export async function stamp({ root, tag, assetsDir }) { if (action.split(MARKER).length !== 2 || !STAMP.test(action)) { throw new Error(`${ACTION} must contain exactly one line like: default: vX.Y.Z ${MARKER}`); } - const lines = [`# ${tag}`]; + const lines = [`# ${tag}`]; // script/release reads this header for (const a of ASSETS) { const path = join(assetsDir, a); if (!existsSync(path)) throw new Error(`missing release asset ${path}`); From fd1fa017d46406e170f16172d5b785dba42e0baf Mon Sep 17 00:00:00 2001 From: Jeff Martin Date: Wed, 18 Nov 2026 20:49:59 -0800 Subject: [PATCH 13/20] script/release-test: remove temp dir without prompting Git object files are read-only, so rm -r prompts for each one when stdin is a terminal and fails the run if any answer isn't yes. --- script/release-test | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/script/release-test b/script/release-test index 1f0d51ff..2a197bd0 100755 --- a/script/release-test +++ b/script/release-test @@ -3,7 +3,7 @@ set -euo pipefail root="$(cd "$(dirname "$0")/.." && pwd)" tmp="$(mktemp -d)" -trap 'rm -r "$tmp"' EXIT +trap 'rm -rf "$tmp"' EXIT git init --quiet --bare "$tmp/origin.git" git clone --quiet "$tmp/origin.git" "$tmp/repo" From e82c348588d06638b1cb619657f5d20245528f16 Mon Sep 17 00:00:00 2001 From: Jeff Martin Date: Thu, 19 Nov 2026 14:25:23 -0800 Subject: [PATCH 14/20] script/release: push a held local tag on rerun --- script/release | 21 +++++++++++++++++---- script/release-test | 26 ++++++++++++++++++++++++++ 2 files changed, 43 insertions(+), 4 deletions(-) diff --git a/script/release b/script/release index 7ee1f054..bb025968 100755 --- a/script/release +++ b/script/release @@ -90,7 +90,9 @@ cut_tag() { branch="$(git symbolic-ref --quiet --short HEAD || true)" [ "$branch" = "main" ] || die "releases must be cut from main (got ${branch:-detached HEAD})" require_clean - require_current_main "$(git rev-parse HEAD)" + local head + head="$(git rev-parse HEAD)" + require_current_main "$head" make fmt-check vet test test-stub @@ -135,8 +137,15 @@ cut_tag() { tag="${tag}-rc.$((rc + 1))" fi validate_tag "$tag" - git rev-parse -q --verify "refs/tags/${tag}" >/dev/null && - die "tag ${tag} already exists" + # A rerun after a held push reuses the local tag if it's the one it would create. + local reuse=0 + if git rev-parse -q --verify "refs/tags/${tag}" >/dev/null; then + [ "$(git cat-file -t "refs/tags/${tag}")" = tag ] || + die "local tag ${tag} is not annotated; delete it and rerun" + [ "$(git rev-parse "${tag}^{commit}")" = "$head" ] || + die "local tag ${tag} points at $(git rev-parse --short "${tag}^{commit}"), not HEAD; delete it and rerun" + reuse=1 + fi echo "Cutting ${tag} (module version ${version}) at $(git rev-parse --short HEAD)" if [ "${RELEASE_DRY_RUN:-}" = "1" ]; then @@ -144,7 +153,11 @@ cut_tag() { return fi - git tag -a "$tag" -m "$tag" + if [ "$reuse" = "1" ]; then + echo "Reusing local tag ${tag}." + else + git tag -a "$tag" -m "$tag" + fi local commit commit="$(git rev-parse "${tag}^{commit}")" require_current_main "$commit" diff --git a/script/release-test b/script/release-test index 2a197bd0..ff8eba62 100755 --- a/script/release-test +++ b/script/release-test @@ -60,6 +60,32 @@ fi git reset --quiet --hard HEAD~2 git push --quiet --force origin main +# A rerun after a held push pushes the existing local tag. +git tag -a v1.2.4 -m v1.2.4 +output="$(script/release patch)" +[[ "$output" == *"Reusing local tag v1.2.4."* ]] +[[ "$output" == *"Pushed v1.2.4"* ]] +[ "$(git ls-remote --tags origin 'refs/tags/v1.2.4^{}' | awk '{ print $1 }')" = "$(git rev-parse HEAD)" ] + +# A rerun after a successful push stops at the next step: stamping main. +if output="$(script/release patch 2>&1)"; then + echo "expected a rerun after a successful push to require the stamp" >&2 + exit 1 +fi +[[ "$output" == *"isn't stamped for v1.2.4"* ]] + +# A leftover local tag at another commit still blocks the release. +printf '# v1.2.4\n' >actions/verify/checksums.txt +git commit --quiet -am "stamp v1.2.4" +git push --quiet origin main +git tag -a v1.2.5 -m v1.2.5 HEAD~1 +if output="$(script/release patch 2>&1)"; then + echo "expected a local tag at another commit to block the release" >&2 + exit 1 +fi +[[ "$output" == *"local tag v1.2.5 points at "* ]] +git tag -d v1.2.5 >/dev/null + ancestor="$(git rev-parse HEAD)" tree="$(git rev-parse "${ancestor}^{tree}")" descendant="$(printf 'descendant\n' | git -c user.name=test -c user.email=test@example.com commit-tree "$tree" -p "$ancestor")" From 623da7e4ee62af9d89497bd6ac9b6ac937db8ea2 Mon Sep 17 00:00:00 2001 From: Jeff Martin Date: Thu, 19 Nov 2026 14:26:21 -0800 Subject: [PATCH 15/20] verify-action-release: skip steps a previous run already did --- script/verify-action-release.mjs | 60 +++++++++++++++++++++++++-- script/verify-action-release.test.mjs | 47 ++++++++++++++++++++- 2 files changed, 103 insertions(+), 4 deletions(-) diff --git a/script/verify-action-release.mjs b/script/verify-action-release.mjs index fae7c190..8be376fe 100644 --- a/script/verify-action-release.mjs +++ b/script/verify-action-release.mjs @@ -57,8 +57,9 @@ export async function stamp({ root, tag, assetsDir }) { // publish commits files on top of head through the Git Data API, so GitHub signs // the commit as the tag ruleset requires, and tags it verify-. -export async function publish({ api, token, repo, tag, head, baseTree, files, fetch: fetchFn = fetch }) { - const call = async (method, path, body) => { +// github returns a caller for repo's REST API. With allow404, a 404 returns null. +function github({ api, token, repo, fetch: fetchFn = fetch }) { + return async (method, path, body, { allow404 = false } = {}) => { const res = await fetchFn(`${api}/repos/${repo}/${path}`, { method, headers: { @@ -68,9 +69,46 @@ export async function publish({ api, token, repo, tag, head, baseTree, files, fe }, body: body && JSON.stringify(body), }); + if (allow404 && res.status === 404) return null; if (!res.ok) throw new Error(`${method} ${path}: HTTP ${res.status} ${await res.text()}`); return res.json(); }; +} + +// stampedFor returns the tag root's action and checksums.txt are both stamped +// for, or null if they disagree. +export async function stampedFor(root) { + const action = (await readFile(join(root, ACTION), "utf8")).match(STAMP)?.[0].match(/default: (\S+)/)[1]; + const header = existsSync(join(root, CHECKSUMS)) + ? (await readFile(join(root, CHECKSUMS), "utf8")).split("\n", 1)[0] + : ""; + return action && header === `# ${action}` ? action : null; +} + +// published returns the commit verify- points at, or null if the tag +// doesn't exist. A rerun only skips the tag if it's a signed commit directly on +// head whose tree is exactly tree, the freshly stamped one; anything else fails. +export async function published({ api, token, repo, tag, head, tree, fetch: fetchFn = fetch }) { + const call = github({ api, token, repo, fetch: fetchFn }); + const ref = await call("GET", `git/ref/tags/verify-${tag}`, undefined, { allow404: true }); + if (!ref) return null; + const sha = ref.object?.sha; + const commit = ref.object?.type === "commit" ? await call("GET", `git/commits/${sha}`) : null; + if ( + commit?.parents?.length !== 1 || + commit.parents[0].sha !== head || + commit.tree?.sha !== tree || + !commit.verification?.verified + ) { + throw new Error(`verify-${tag} already exists at ${sha}, which is not this stamp signed on ${head}`); + } + return sha; +} + +// publish commits files on top of head through the Git Data API, so GitHub signs +// the commit as the tag ruleset requires, and tags it verify-. +export async function publish({ api, token, repo, tag, head, baseTree, files, fetch: fetchFn = fetch }) { + const call = github({ api, token, repo, fetch: fetchFn }); const tree = []; for (const { path, content } of files) { @@ -101,6 +139,12 @@ async function main(tag, { stampOnly = false } = {}) { if (!repo || (!token && !stampOnly)) throw new Error("set REPO and GH_TOKEN"); const root = resolve(fileURLToPath(import.meta.url), "../.."); + const head = run("git", ["rev-parse", "HEAD"], { cwd: root }); + // Each step skips when a previous run already did it. + if (stampOnly && (await stampedFor(root)) === tag) { + console.log(`${ACTION} and ${CHECKSUMS} are already stamped for ${tag}`); + return; + } const assetsDir = await mkdtemp(join(process.env.RUNNER_TEMP ?? tmpdir(), "assets-")); for (const a of ASSETS) { run("gh", ["release", "download", tag, "--repo", repo, "--pattern", a, "--dir", assetsDir]); @@ -117,6 +161,16 @@ async function main(tag, { stampOnly = false } = {}) { console.log(`Stamped ${ACTION} and ${CHECKSUMS} for ${tag}`); return; } + // The tree head would have with the stamp, from a scratch index. + const env = { ...process.env, GIT_INDEX_FILE: join(assetsDir, "index") }; + run("git", ["read-tree", "HEAD"], { cwd: root, env }); + run("git", ["add", "--", ACTION, CHECKSUMS], { cwd: root, env }); + const tree = run("git", ["write-tree"], { cwd: root, env }); + const done = await published({ api, token, repo, tag, head, tree }); + if (done) { + console.log(`verify-${tag} already exists at ${done}`); + return; + } const files = []; for (const path of [ACTION, CHECKSUMS]) files.push({ path, content: await readFile(join(root, path)) }); const commit = await publish({ @@ -124,7 +178,7 @@ async function main(tag, { stampOnly = false } = {}) { token, repo, tag, - head: run("git", ["rev-parse", "HEAD"], { cwd: root }), + head, baseTree: run("git", ["rev-parse", "HEAD^{tree}"], { cwd: root }), files, }); diff --git a/script/verify-action-release.test.mjs b/script/verify-action-release.test.mjs index ba98eff3..6415c839 100644 --- a/script/verify-action-release.test.mjs +++ b/script/verify-action-release.test.mjs @@ -5,7 +5,7 @@ import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; import { afterEach, beforeEach, describe, test } from "node:test"; -import { ACTION, ASSETS, CHECKSUMS, checkTag, publish, stamp } from "./verify-action-release.mjs"; +import { ACTION, ASSETS, CHECKSUMS, checkTag, publish, published, stamp, stampedFor } from "./verify-action-release.mjs"; const repoRoot = join(dirname(fileURLToPath(import.meta.url)), ".."); @@ -70,6 +70,14 @@ describe("stamp", () => { assert.match(await readFile(join(root, CHECKSUMS), "utf8"), /^# v1\.2\.4\n/); }); + test("stampedFor reports the tag only when the action and checksums agree", async () => { + assert.equal(await stampedFor(root), null); + await stamp({ root, tag: "v1.2.3", assetsDir }); + assert.equal(await stampedFor(root), "v1.2.3"); + await writeFile(join(root, CHECKSUMS), "# v1.2.2\n"); + assert.equal(await stampedFor(root), null); + }); + test("refuses an action without exactly one stamp line", async () => { const action = await readFile(join(root, ACTION), "utf8"); await writeFile(join(root, ACTION), action + action); @@ -138,3 +146,40 @@ describe("publish", () => { await assert.rejects(publish({ ...args, fetch }), /POST git\/blobs: HTTP 422 Reference already exists/); }); }); + +describe("published", () => { + const args = { api: "https://api.test", token: "tok", repo: "o/r", tag: "v1.2.3", head: "head1", tree: "tree1" }; + function fakeAPI(responses) { + return async (url) => { + const res = responses[url.replace("https://api.test/repos/o/r/", "")]; + return res ? new Response(JSON.stringify(res), { status: 200 }) : new Response("Not Found", { status: 404 }); + }; + } + const ref = { "git/ref/tags/verify-v1.2.3": { object: { type: "commit", sha: "stamp1" } } }; + + test("returns null when the tag doesn't exist", async () => { + assert.equal(await published({ ...args, fetch: fakeAPI({}) }), null); + }); + + test("returns a signed stamp commit on head", async () => { + const fetch = fakeAPI({ ...ref, "git/commits/stamp1": { parents: [{ sha: "head1" }], tree: { sha: "tree1" }, verification: { verified: true } } }); + assert.equal(await published({ ...args, fetch }), "stamp1"); + }); + + for (const [name, commit] of [ + ["another parent", { parents: [{ sha: "other" }], tree: { sha: "tree1" }, verification: { verified: true } }], + ["another tree", { parents: [{ sha: "head1" }], tree: { sha: "tree2" }, verification: { verified: true } }], + ["an unsigned commit", { parents: [{ sha: "head1" }], tree: { sha: "tree1" }, verification: { verified: false } }], + ["a merge commit", { parents: [{ sha: "head1" }, { sha: "x" }], tree: { sha: "tree1" }, verification: { verified: true } }], + ]) { + test(`fails on ${name}`, async () => { + const fetch = fakeAPI({ ...ref, "git/commits/stamp1": commit }); + await assert.rejects(published({ ...args, fetch }), /verify-v1\.2\.3 already exists at stamp1/); + }); + } + + test("fails on an annotated tag object", async () => { + const fetch = fakeAPI({ "git/ref/tags/verify-v1.2.3": { object: { type: "tag", sha: "tagobj" } } }); + await assert.rejects(published({ ...args, fetch }), /already exists at tagobj/); + }); +}); From 3502a771e1fb24b1858d3831a0945c9435477cc5 Mon Sep 17 00:00:00 2001 From: Jeff Martin Date: Thu, 19 Nov 2026 14:26:33 -0800 Subject: [PATCH 16/20] RELEASING.md: document rerun behavior --- RELEASING.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/RELEASING.md b/RELEASING.md index 84b4b916..927392c8 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -32,6 +32,14 @@ The first candidate is `vX.Y.Z-rc.1`; repeating the same bump increments Release tags are immutable. If publishing fails, fix the publisher and run the release script again for the next RC. +Rerunning a step is safe. If the push was held, rerun the same command: it +pushes the local tag when that tag already points at `HEAD`, and stops if it +points anywhere else. After a successful push, a rerun stops at the next step: +stamping `main`. Rerunning the tag workflow checks the attestations again and skips +tagging when `verify-vX.Y.Z` is already that same signed stamp on the release +commit, and `--stamp-only` skips +a tree that's already stamped for the tag. + Use `patch` for compatible fixes, `minor` for compatible additions, and `major` for breaking changes. From 1732d8d851b16c2f9f7fe6043571adeac72b03fe Mon Sep 17 00:00:00 2001 From: Jeff Martin Date: Thu, 19 Nov 2026 14:54:27 -0800 Subject: [PATCH 17/20] Record the verify action's version and checksums in checksums.json The action read its default version from a stamped comment in action.yml and a '# vX.Y.Z' header in checksums.txt. Both comments were load-bearing. Now checksums.json holds the version and the per-asset sha256, the version input defaults to empty and falls back to it, and only that file is stamped. --- RELEASING.md | 8 +-- actions/verify/README.md | 4 +- actions/verify/action.yml | 3 +- actions/verify/checksums.json | 11 ++++ actions/verify/checksums.txt | 7 --- actions/verify/lib.mjs | 56 +++++++++++++------- actions/verify/lib.test.mjs | 76 +++++++++++++++++++++------ script/release | 7 +-- script/release-test | 8 +-- script/verify-action-release.mjs | 51 +++++++----------- script/verify-action-release.test.mjs | 69 +++++++++--------------- 11 files changed, 166 insertions(+), 134 deletions(-) create mode 100644 actions/verify/checksums.json delete mode 100644 actions/verify/checksums.txt diff --git a/RELEASING.md b/RELEASING.md index 927392c8..0b6fe37c 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -51,10 +51,10 @@ and GitHub release. It then publishes the [verify action](actions/verify/README.md) for the release. `script/verify-action-release.mjs` checks the release binaries' -attestations, sets the action's default `version` to the new tag and records the -release binaries' checksums in `actions/verify/checksums.txt`. The workflow -commits that on top of the release commit and tags it `verify-vX.Y.Z`. Don't -edit the default or the checksums by hand. +attestations and writes the new tag and the release binaries' checksums to +`actions/verify/checksums.json`. The action runs that version when its `version` +input is empty. The workflow commits that file on top of the release commit and +tags it `verify-vX.Y.Z`. Don't edit `checksums.json` by hand. `main` also carries a stamp, so this repository's own `verify-lockfile` workflow runs the action the way other repositories do. The stamp for a release diff --git a/actions/verify/README.md b/actions/verify/README.md index 5aebb3e0..7d970450 100644 --- a/actions/verify/README.md +++ b/actions/verify/README.md @@ -19,10 +19,10 @@ It's a Node action (`node24`) that uses only Node built-ins, so it runs on the r | Input | Default | Description | |---|---|---| | `token` | `${{ github.token }}` | Token the CLI uses to read action repositories. | -| `version` | the CLI release the action was stamped with; each `verify-vX.Y.Z` tag uses `vX.Y.Z` | `gh-actions-lock` release to run, such as `v0.5.1`. | +| `version` | the CLI release recorded in the action's `checksums.json`; each `verify-vX.Y.Z` tag records `vX.Y.Z` | `gh-actions-lock` release to run, such as `v0.5.1`. | | `args` | `--verify` | Arguments passed to `gh-actions-lock`, split on whitespace and newlines. For example, `--verify --fail-on-warning`. | -With the default `version`, the binary is checked against checksums recorded in the action. With another `version`, it's checked against the release's build attestation on github.com using `token`, which needs the GitHub CLI (`gh`) on `PATH`. GitHub-hosted runners have it; self-hosted runners may not. On GHE.com, that check uses `GH_ACTIONS_LOCK_GITHUB_COM_TOKEN` instead, so your tenant token never leaves the tenant. +With the default `version`, the binary is checked against the checksums in `checksums.json`. With another `version`, it's checked against the release's build attestation on github.com using `token`, which needs the GitHub CLI (`gh`) on `PATH`. GitHub-hosted runners have it; self-hosted runners may not. On GHE.com, that check uses `GH_ACTIONS_LOCK_GITHUB_COM_TOKEN` instead, so your tenant token never leaves the tenant. ## Private and internal actions diff --git a/actions/verify/action.yml b/actions/verify/action.yml index 3fd20659..4d187124 100644 --- a/actions/verify/action.yml +++ b/actions/verify/action.yml @@ -7,9 +7,8 @@ inputs: required: false default: ${{ github.token }} version: - description: gh-actions-lock release to run, such as v0.5.1. Defaults to the CLI release this action was stamped with. + description: gh-actions-lock release to run, such as v0.5.1. Defaults to the release recorded in checksums.json. required: false - default: v0.5.1 # stamped by script/verify-action-release.mjs args: description: Arguments passed to gh-actions-lock, split on whitespace. required: false diff --git a/actions/verify/checksums.json b/actions/verify/checksums.json new file mode 100644 index 00000000..57b07868 --- /dev/null +++ b/actions/verify/checksums.json @@ -0,0 +1,11 @@ +{ + "version": "v0.5.1", + "sha256": { + "linux-amd64": "94009f287cfcc046ff371824824c203a8a44c981ca2dac344052744897c29c3a", + "linux-arm64": "b51f0ba96784950bf945272c7e0d3f9fb4c53d378b37070f8eb6cdbe71b190a8", + "darwin-amd64": "daed4b624525ca04e088e1310dd80e06a410116ece41554b9f1d582b93a2c909", + "darwin-arm64": "223fa3e843a560a23964a5d0e037f500ad42b4e0c57b995f1ec99766355ae11e", + "windows-amd64.exe": "24377e9ed1f53d131157649741ac003fd563f0b4d21b4a7a978881f67a412888", + "windows-arm64.exe": "ef788440a3a822fdffb7b5b6682f91d30d3db0480575401ff5ee5ce70280e886" + } +} diff --git a/actions/verify/checksums.txt b/actions/verify/checksums.txt deleted file mode 100644 index a09062fe..00000000 --- a/actions/verify/checksums.txt +++ /dev/null @@ -1,7 +0,0 @@ -# v0.5.1 -94009f287cfcc046ff371824824c203a8a44c981ca2dac344052744897c29c3a linux-amd64 -b51f0ba96784950bf945272c7e0d3f9fb4c53d378b37070f8eb6cdbe71b190a8 linux-arm64 -daed4b624525ca04e088e1310dd80e06a410116ece41554b9f1d582b93a2c909 darwin-amd64 -223fa3e843a560a23964a5d0e037f500ad42b4e0c57b995f1ec99766355ae11e darwin-arm64 -24377e9ed1f53d131157649741ac003fd563f0b4d21b4a7a978881f67a412888 windows-amd64.exe -ef788440a3a822fdffb7b5b6682f91d30d3db0480575401ff5ee5ce70280e886 windows-arm64.exe diff --git a/actions/verify/lib.mjs b/actions/verify/lib.mjs index 6227af39..826bdfcb 100644 --- a/actions/verify/lib.mjs +++ b/actions/verify/lib.mjs @@ -42,19 +42,35 @@ export function splitArgs(input) { return (input ?? "").split(/\s+/).filter(Boolean); } -// selectCheck picks how to check the binary: the checksum stamped into this action -// when version is the release it was stamped with, otherwise the release's -// build attestation. checksums is the text of checksums.txt, or null. -export function selectCheck(version, checksums, asset) { - const lines = checksums?.split(/\r?\n/) ?? []; - const header = lines[0]?.split(/\s+/); - const stamped = header?.[0] === "#" ? header[1] : undefined; - if (version !== stamped) return { kind: "attestation" }; - for (const line of lines.slice(1)) { - const [sum, name] = line.trim().split(/\s+/); - if (name === asset) return { kind: "checksum", want: sum }; +// parseChecksums reads checksums.json, which script/verify-action-release.mjs +// writes: {"version": "vX.Y.Z", "sha256": {"": ""}}. +// Anything else fails. +export function parseChecksums(text) { + let sums; + try { + sums = JSON.parse(text); + } catch (err) { + throw new ActionError(`checksums.json: ${err.message}`); } - throw new ActionError(`no checksum for ${asset} in checksums.txt`); + const { version, sha256, ...extra } = sums ?? {}; + const shaped = + typeof version === "string" && + sha256 !== null && typeof sha256 === "object" && !Array.isArray(sha256) && + Object.keys(extra).length === 0 && + Object.entries(sha256).every(([k, v]) => /^[a-z0-9][a-z0-9.-]*$/.test(k) && /^[0-9a-f]{64}$/.test(v)); + if (!shaped) throw new ActionError('checksums.json must be {"version": "vX.Y.Z", "sha256": {"": ""}}'); + checkVersion(version); + return { version, sha256 }; +} + +// selectCheck picks the version to run and how to check it: the checksum in +// checksums.json when version is empty or the release it records, otherwise the +// release's build attestation. sums is parsed checksums.json, or null. +export function selectCheck(version, sums, asset) { + const v = checkVersion(version || sums?.version); + if (v !== sums?.version) return { version: v, kind: "attestation" }; + if (!Object.hasOwn(sums.sha256, asset)) throw new ActionError(`no checksum for ${asset} in checksums.json`); + return { version: v, kind: "checksum", want: sums.sha256[asset] }; } // attestationEnv builds the environment for `gh attestation verify`. Attestations @@ -65,7 +81,7 @@ export function attestationEnv(env) { token = env.GH_ACTIONS_LOCK_GITHUB_COM_TOKEN ?? ""; if (!token) { throw new ActionError( - `set GH_ACTIONS_LOCK_GITHUB_COM_TOKEN to check ${env.INPUT_VERSION}, or use the version this action was stamped with`, + `set GH_ACTIONS_LOCK_GITHUB_COM_TOKEN to check ${env.INPUT_VERSION}, or leave version empty`, ); } } @@ -133,7 +149,7 @@ export function useEnvProxy(env, http) { function runGh(args, env) { const r = spawnSync("gh", args, { env, stdio: ["ignore", "ignore", "inherit"] }); if (r.error?.code === "ENOENT") { - throw new ActionError("gh is not on PATH; it's needed to check a version other than the one this action was stamped with"); + throw new ActionError("gh is not on PATH; it's needed to check a version other than the one in checksums.json"); } return r.status === 0; } @@ -141,14 +157,14 @@ function runGh(args, env) { // install downloads the gh-actions-lock binary for this runner into RUNNER_TEMP, // checks it and returns its path. export async function install({ env, actionDir, download = downloadFile, gh = runGh, log = console.log }) { - const version = checkVersion(env.INPUT_VERSION); const { asset, ext } = assetFor(env.RUNNER_OS, env.RUNNER_ARCH); if (!env.RUNNER_TEMP) throw new ActionError("RUNNER_TEMP is not set"); - const sumsPath = join(actionDir, "checksums.txt"); - const sums = existsSync(sumsPath) ? await readFile(sumsPath, "utf8") : null; - const check = selectCheck(version, sums, asset); - const ghEnv = check.kind === "attestation" ? attestationEnv(env) : null; + const sumsPath = join(actionDir, "checksums.json"); + const sums = existsSync(sumsPath) ? parseChecksums(await readFile(sumsPath, "utf8")) : null; + const check = selectCheck(env.INPUT_VERSION, sums, asset); + const { version } = check; + const ghEnv = check.kind === "attestation" ? attestationEnv({ ...env, INPUT_VERSION: version }) : null; const dir = join(env.RUNNER_TEMP, "gh-actions-lock"); await mkdir(dir, { recursive: true }); @@ -161,7 +177,7 @@ export async function install({ env, actionDir, download = downloadFile, gh = ru if (got !== check.want) { throw new ActionError(`checksum mismatch for ${asset} ${version}: got ${got}, want ${check.want}`); } - log(`Verified ${asset} ${version} against the stamped checksum.`); + log(`Verified ${asset} ${version} against checksums.json.`); } else { const ok = gh( [ diff --git a/actions/verify/lib.test.mjs b/actions/verify/lib.test.mjs index 20e08449..2f12dd58 100644 --- a/actions/verify/lib.test.mjs +++ b/actions/verify/lib.test.mjs @@ -4,7 +4,7 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join } from "node:path"; import { afterEach, beforeEach, describe, test } from "node:test"; -import { ActionError, assetFor, attestationEnv, checkVersion, downloadFile, install, selectCheck, splitArgs, useEnvProxy, withSubdomainNoProxy } from "./lib.mjs"; +import { ActionError, assetFor, attestationEnv, checkVersion, downloadFile, install, parseChecksums, selectCheck, splitArgs, useEnvProxy, withSubdomainNoProxy } from "./lib.mjs"; const sha = (s) => createHash("sha256").update(s).digest("hex"); @@ -46,25 +46,55 @@ describe("assetFor", () => { }); }); +describe("parseChecksums", () => { + const sums = { version: "v0.4.1", sha256: { "linux-amd64": "a".repeat(64), "windows-amd64.exe": "b".repeat(64) } }; + test("reads the version and checksums", () => { + assert.deepEqual(parseChecksums(JSON.stringify(sums, null, 2)), sums); + }); + const bad = { + "invalid JSON": "version: v0.4.1", + "null": "null", + "an array": "[]", + "a missing version": JSON.stringify({ sha256: sums.sha256 }), + "an invalid version": JSON.stringify({ ...sums, version: "v0.4" }), + "a non-string version": JSON.stringify({ ...sums, version: 1 }), + "an array of checksums": JSON.stringify({ ...sums, sha256: [] }), + "a short digest": JSON.stringify({ ...sums, sha256: { "linux-amd64": "a".repeat(63) } }), + "an uppercase digest": JSON.stringify({ ...sums, sha256: { "linux-amd64": "A".repeat(64) } }), + "a bad asset name": JSON.stringify({ ...sums, sha256: { "../x": "a".repeat(64) } }), + "an unknown key": JSON.stringify({ ...sums, extra: 1 }), + }; + for (const [name, t] of Object.entries(bad)) { + test(`rejects ${name}`, () => assert.throws(() => parseChecksums(t), ActionError)); + } +}); + describe("selectCheck", () => { - const sums = `# v0.4.1\n${"a".repeat(64)} linux-amd64\n${"b".repeat(64)} windows-amd64.exe\n`; - test("uses the stamped checksum for the stamped version", () => { - assert.deepEqual(selectCheck("v0.4.1", sums, "windows-amd64.exe"), { kind: "checksum", want: "b".repeat(64) }); - }); - test("handles CRLF checksums", () => { - assert.deepEqual(selectCheck("v0.4.1", sums.replaceAll("\n", "\r\n"), "linux-amd64"), { - kind: "checksum", - want: "a".repeat(64), - }); + const sums = { version: "v0.4.1", sha256: { "linux-amd64": "a".repeat(64), "windows-amd64.exe": "b".repeat(64) } }; + test("defaults to the recorded version and its checksum", () => { + assert.deepEqual(selectCheck("", sums, "windows-amd64.exe"), { version: "v0.4.1", kind: "checksum", want: "b".repeat(64) }); + assert.deepEqual(selectCheck(undefined, sums, "linux-amd64"), { version: "v0.4.1", kind: "checksum", want: "a".repeat(64) }); + }); + test("uses the checksum when the recorded version is set explicitly", () => { + assert.deepEqual(selectCheck("v0.4.1", sums, "linux-amd64"), { version: "v0.4.1", kind: "checksum", want: "a".repeat(64) }); }); test("uses the attestation for any other version", () => { - assert.deepEqual(selectCheck("v0.4.2", sums, "linux-amd64"), { kind: "attestation" }); + assert.deepEqual(selectCheck("v0.4.2", sums, "linux-amd64"), { version: "v0.4.2", kind: "attestation" }); }); - test("uses the attestation when the action is unstamped", () => { - assert.deepEqual(selectCheck("v0.4.1", null, "linux-amd64"), { kind: "attestation" }); + test("uses the attestation without checksums.json", () => { + assert.deepEqual(selectCheck("v0.4.1", null, "linux-amd64"), { version: "v0.4.1", kind: "attestation" }); }); - test("fails when the stamped version lacks the asset", () => { - assert.throws(() => selectCheck("v0.4.1", sums, "darwin-arm64"), /no checksum for darwin-arm64/); + test("asks for a version with neither input nor checksums.json", () => { + assert.throws(() => selectCheck("", null, "linux-amd64"), /set the version input/); + }); + test("rejects an invalid version input", () => { + assert.throws(() => selectCheck("v0.4", sums, "linux-amd64"), /invalid version/); + }); + test("fails when the recorded version lacks the asset", () => { + assert.throws(() => selectCheck("", sums, "darwin-arm64"), /no checksum for darwin-arm64/); + }); + test("ignores inherited property names", () => { + assert.throws(() => selectCheck("", sums, "constructor"), /no checksum for constructor/); }); }); @@ -109,7 +139,7 @@ describe("install", () => { const quiet = () => {}; async function stampedAction(version, asset, sum = sha(binary)) { - await writeFile(join(tmp, "checksums.txt"), `# ${version}\n${sum} ${asset}\n`); + await writeFile(join(tmp, "checksums.json"), JSON.stringify({ version, sha256: { [asset]: sum } })); return tmp; } @@ -135,6 +165,20 @@ describe("install", () => { assert.equal(await readFile(bin, "utf8"), binary); }); + test("runs the recorded version when the version input is empty", async () => { + const env = { INPUT_VERSION: "", RUNNER_OS: "Linux", RUNNER_ARCH: "ARM64", RUNNER_TEMP: tmp }; + const actionDir = await stampedAction("v0.4.1", "linux-arm64"); + let fetched; + await install({ + env, + actionDir, + download: async (url, dest) => ((fetched = url), okDownload(url, dest)), + gh: () => assert.fail("attestation should not run"), + log: quiet, + }); + assert.equal(fetched, "https://github.com/github/gh-actions-lock/releases/download/v0.4.1/linux-arm64"); + }); + test("fails on a checksum mismatch", async () => { const env = { INPUT_VERSION: "v0.4.1", RUNNER_OS: "Linux", RUNNER_ARCH: "X64", RUNNER_TEMP: tmp }; const actionDir = await stampedAction("v0.4.1", "linux-amd64", "0".repeat(64)); diff --git a/script/release b/script/release index bb025968..c86b9bbf 100755 --- a/script/release +++ b/script/release @@ -14,7 +14,7 @@ # RELEASE_DRY_RUN=1 Compute and print the next version, then stop before # tagging or pushing. # -# Requires: git, go, make, and actions/verify on main stamped for the latest +# Requires: git, go, make, node, and actions/verify on main stamped for the latest # release (see RELEASING.md). set -euo pipefail @@ -55,8 +55,9 @@ require_current_main() { require_current_stamp() { local latest="$1" local stamped - stamped="$( (git show refs/remotes/origin/main:actions/verify/checksums.txt 2>/dev/null || true) | head -n 1)" - [ "$stamped" = "# ${latest}" ] || + stamped="$( (git show refs/remotes/origin/main:actions/verify/checksums.json 2>/dev/null || true) | + node -e 'let s = ""; process.stdin.on("data", (d) => (s += d)).on("end", () => { try { process.stdout.write(String(JSON.parse(s).version)); } catch {} });')" + [ "$stamped" = "${latest}" ] || die "actions/verify on main isn't stamped for ${latest} (got '${stamped}'); run 'node script/verify-action-release.mjs --stamp-only ${latest}' and merge that first" } diff --git a/script/release-test b/script/release-test index ff8eba62..ded104b6 100755 --- a/script/release-test +++ b/script/release-test @@ -16,7 +16,7 @@ cp "$root/script/release" script/release cp "$root/script/verify-release-tag" script/verify-release-tag touch tracked mkdir -p actions/verify -printf '# v1.2.3\n' >actions/verify/checksums.txt +printf '{"version": "v1.2.3", "sha256": {}}\n' >actions/verify/checksums.json git add . git commit --quiet -m initial git push --quiet -u origin main @@ -41,7 +41,7 @@ output="$(RELEASE_DRY_RUN=1 script/release patch --rc)" output="$(RELEASE_DRY_RUN=1 script/release patch)" [[ "$output" == *"Cutting v1.2.4 "* ]] -printf '# v1.2.2\n' >actions/verify/checksums.txt +printf '{"version": "v1.2.2", "sha256": {}}\n' >actions/verify/checksums.json git commit --quiet -am "stale stamp" git push --quiet origin main if output="$(RELEASE_DRY_RUN=1 script/release patch 2>&1)"; then @@ -49,7 +49,7 @@ if output="$(RELEASE_DRY_RUN=1 script/release patch 2>&1)"; then exit 1 fi [[ "$output" == *"isn't stamped for v1.2.3"* ]] -git rm --quiet actions/verify/checksums.txt +git rm --quiet actions/verify/checksums.json git commit --quiet -m "no stamp" git push --quiet origin main if output="$(RELEASE_DRY_RUN=1 script/release patch 2>&1)"; then @@ -75,7 +75,7 @@ fi [[ "$output" == *"isn't stamped for v1.2.4"* ]] # A leftover local tag at another commit still blocks the release. -printf '# v1.2.4\n' >actions/verify/checksums.txt +printf '{"version": "v1.2.4", "sha256": {}}\n' >actions/verify/checksums.json git commit --quiet -am "stamp v1.2.4" git push --quiet origin main git tag -a v1.2.5 -m v1.2.5 HEAD~1 diff --git a/script/verify-action-release.mjs b/script/verify-action-release.mjs index 8be376fe..12441f98 100644 --- a/script/verify-action-release.mjs +++ b/script/verify-action-release.mjs @@ -1,5 +1,6 @@ // Publishes verify- for a CLI release: checks the release binaries' -// attestations, stamps actions/verify with the tag and their checksums, and tags +// attestations, records the tag and their checksums in actions/verify/checksums.json, +// and tags // a GitHub-signed commit on top of the release commit. // // Usage (release workflow, with GH_TOKEN and REPO set): @@ -14,6 +15,7 @@ import { mkdtemp, readFile, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; import { join, resolve } from "node:path"; import { fileURLToPath } from "node:url"; +import { parseChecksums } from "../actions/verify/lib.mjs"; export const ASSETS = [ "linux-amd64", @@ -23,10 +25,7 @@ export const ASSETS = [ "windows-amd64.exe", "windows-arm64.exe", ]; -export const ACTION = "actions/verify/action.yml"; -export const CHECKSUMS = "actions/verify/checksums.txt"; -const MARKER = "# stamped by script/verify-action-release.mjs"; -const STAMP = /^(\s*default: )\S+( # stamped by script\/verify-action-release\.mjs)$/m; +export const CHECKSUMS = "actions/verify/checksums.json"; export function checkTag(tag) { if (!/^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-rc\.[1-9]\d*)?$/.test(tag ?? "")) { @@ -35,28 +34,19 @@ export function checkTag(tag) { return tag; } -// stamp defaults the action's version input to tag and writes checksums.txt for -// the release binaries in assetsDir, replacing any earlier stamp. The marker -// comment stays so main and every verify-v* tag can be restamped the same way. +// stamp writes checksums.json for the release binaries in assetsDir, replacing +// any earlier stamp. The action runs the version it records by default. export async function stamp({ root, tag, assetsDir }) { checkTag(tag); - const actionPath = join(root, ACTION); - const action = await readFile(actionPath, "utf8"); - if (action.split(MARKER).length !== 2 || !STAMP.test(action)) { - throw new Error(`${ACTION} must contain exactly one line like: default: vX.Y.Z ${MARKER}`); - } - const lines = [`# ${tag}`]; // script/release reads this header + const sha256 = {}; for (const a of ASSETS) { const path = join(assetsDir, a); if (!existsSync(path)) throw new Error(`missing release asset ${path}`); - lines.push(`${createHash("sha256").update(await readFile(path)).digest("hex")} ${a}`); + sha256[a] = createHash("sha256").update(await readFile(path)).digest("hex"); } - await writeFile(join(root, CHECKSUMS), lines.join("\n") + "\n"); - await writeFile(actionPath, action.replace(STAMP, `$1${tag}$2`)); + await writeFile(join(root, CHECKSUMS), JSON.stringify({ version: tag, sha256 }, null, 2) + "\n"); } -// publish commits files on top of head through the Git Data API, so GitHub signs -// the commit as the tag ruleset requires, and tags it verify-. // github returns a caller for repo's REST API. With allow404, a 404 returns null. function github({ api, token, repo, fetch: fetchFn = fetch }) { return async (method, path, body, { allow404 = false } = {}) => { @@ -75,14 +65,14 @@ function github({ api, token, repo, fetch: fetchFn = fetch }) { }; } -// stampedFor returns the tag root's action and checksums.txt are both stamped -// for, or null if they disagree. +// stampedFor returns the version root's checksums.json records, or null if it's +// missing or malformed. export async function stampedFor(root) { - const action = (await readFile(join(root, ACTION), "utf8")).match(STAMP)?.[0].match(/default: (\S+)/)[1]; - const header = existsSync(join(root, CHECKSUMS)) - ? (await readFile(join(root, CHECKSUMS), "utf8")).split("\n", 1)[0] - : ""; - return action && header === `# ${action}` ? action : null; + try { + return parseChecksums(await readFile(join(root, CHECKSUMS), "utf8")).version; + } catch { + return null; + } } // published returns the commit verify- points at, or null if the tag @@ -142,7 +132,7 @@ async function main(tag, { stampOnly = false } = {}) { const head = run("git", ["rev-parse", "HEAD"], { cwd: root }); // Each step skips when a previous run already did it. if (stampOnly && (await stampedFor(root)) === tag) { - console.log(`${ACTION} and ${CHECKSUMS} are already stamped for ${tag}`); + console.log(`${CHECKSUMS} is already stamped for ${tag}`); return; } const assetsDir = await mkdtemp(join(process.env.RUNNER_TEMP ?? tmpdir(), "assets-")); @@ -158,21 +148,20 @@ async function main(tag, { stampOnly = false } = {}) { await stamp({ root, tag, assetsDir }); if (stampOnly) { - console.log(`Stamped ${ACTION} and ${CHECKSUMS} for ${tag}`); + console.log(`Stamped ${CHECKSUMS} for ${tag}`); return; } // The tree head would have with the stamp, from a scratch index. const env = { ...process.env, GIT_INDEX_FILE: join(assetsDir, "index") }; run("git", ["read-tree", "HEAD"], { cwd: root, env }); - run("git", ["add", "--", ACTION, CHECKSUMS], { cwd: root, env }); + run("git", ["add", "--", CHECKSUMS], { cwd: root, env }); const tree = run("git", ["write-tree"], { cwd: root, env }); const done = await published({ api, token, repo, tag, head, tree }); if (done) { console.log(`verify-${tag} already exists at ${done}`); return; } - const files = []; - for (const path of [ACTION, CHECKSUMS]) files.push({ path, content: await readFile(join(root, path)) }); + const files = [{ path: CHECKSUMS, content: await readFile(join(root, CHECKSUMS)) }]; const commit = await publish({ api, token, diff --git a/script/verify-action-release.test.mjs b/script/verify-action-release.test.mjs index 6415c839..4624d560 100644 --- a/script/verify-action-release.test.mjs +++ b/script/verify-action-release.test.mjs @@ -5,7 +5,8 @@ import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; import { afterEach, beforeEach, describe, test } from "node:test"; -import { ACTION, ASSETS, CHECKSUMS, checkTag, publish, published, stamp, stampedFor } from "./verify-action-release.mjs"; +import { parseChecksums } from "../actions/verify/lib.mjs"; +import { ASSETS, CHECKSUMS, checkTag, publish, published, stamp, stampedFor } from "./verify-action-release.mjs"; const repoRoot = join(dirname(fileURLToPath(import.meta.url)), ".."); @@ -17,14 +18,12 @@ describe("checkTag", () => { }); describe("checked-in stamp", () => { - test("the version default matches checksums.txt, which covers every asset", async () => { - const action = await readFile(join(repoRoot, ACTION), "utf8"); - const tag = action.match(/^ {4}default: (\S+) # stamped by/m)?.[1]; - assert.equal(checkTag(tag), tag); - const lines = (await readFile(join(repoRoot, CHECKSUMS), "utf8")).trimEnd().split("\n"); - assert.equal(lines[0], `# ${tag}`); - assert.deepEqual(lines.slice(1).map((l) => l.split(/\s+/)[1]), ASSETS); - for (const l of lines.slice(1)) assert.match(l, /^[0-9a-f]{64} \S+$/); + test("checksums.json covers every release asset, and action.yml has no version default", async () => { + const sums = parseChecksums(await readFile(join(repoRoot, CHECKSUMS), "utf8")); + assert.equal(checkTag(sums.version), sums.version); + assert.deepEqual(Object.keys(sums.sha256), ASSETS); + const action = await readFile(join(repoRoot, "actions/verify/action.yml"), "utf8"); + assert.doesNotMatch(action.slice(action.indexOf(" version:"), action.indexOf(" args:")), /default:/); }); }); @@ -35,22 +34,18 @@ describe("stamp", () => { assetsDir = join(root, "assets"); await mkdir(join(root, "actions/verify"), { recursive: true }); await mkdir(assetsDir); - await writeFile(join(root, ACTION), await readFile(join(repoRoot, ACTION))); for (const a of ASSETS) await writeFile(join(assetsDir, a), a); }); afterEach(async () => { await rm(root, { recursive: true, force: true }); }); - test("defaults the version input to the tag and records checksums", async () => { + test("records the tag and every asset's checksum in a form the action reads", async () => { await stamp({ root, tag: "v1.2.3-rc.1", assetsDir }); - const action = await readFile(join(root, ACTION), "utf8"); - assert.match(action, /^ {4}default: v1\.2\.3-rc\.1 # stamped by/m); - const lines = (await readFile(join(root, CHECKSUMS), "utf8")).trimEnd().split("\n"); - assert.equal(lines[0], "# v1.2.3-rc.1"); - assert.equal(lines.length, 1 + ASSETS.length); - const want = createHash("sha256").update("linux-arm64").digest("hex"); - assert.ok(lines.includes(`${want} linux-arm64`)); + const sums = parseChecksums(await readFile(join(root, CHECKSUMS), "utf8")); + assert.equal(sums.version, "v1.2.3-rc.1"); + assert.deepEqual(Object.keys(sums.sha256), ASSETS); + assert.equal(sums.sha256["linux-arm64"], createHash("sha256").update("linux-arm64").digest("hex")); }); test("rejects an invalid tag", async () => { @@ -62,27 +57,17 @@ describe("stamp", () => { await assert.rejects(stamp({ root, tag: "v1.2.3", assetsDir }), /missing release asset/); }); - test("restamps an earlier stamp and keeps the marker", async () => { + test("restamps an earlier stamp", async () => { await stamp({ root, tag: "v1.2.3", assetsDir }); await stamp({ root, tag: "v1.2.4", assetsDir }); - const action = await readFile(join(root, ACTION), "utf8"); - assert.match(action, /^ default: v1\.2\.4 # stamped by script\/verify-action-release\.mjs$/m); - assert.match(await readFile(join(root, CHECKSUMS), "utf8"), /^# v1\.2\.4\n/); + assert.equal(await stampedFor(root), "v1.2.4"); }); - test("stampedFor reports the tag only when the action and checksums agree", async () => { + test("stampedFor is null when checksums.json is missing or malformed", async () => { assert.equal(await stampedFor(root), null); - await stamp({ root, tag: "v1.2.3", assetsDir }); - assert.equal(await stampedFor(root), "v1.2.3"); - await writeFile(join(root, CHECKSUMS), "# v1.2.2\n"); + await writeFile(join(root, CHECKSUMS), "version: v1.2.2\n"); assert.equal(await stampedFor(root), null); }); - - test("refuses an action without exactly one stamp line", async () => { - const action = await readFile(join(root, ACTION), "utf8"); - await writeFile(join(root, ACTION), action + action); - await assert.rejects(stamp({ root, tag: "v1.2.4", assetsDir }), /exactly one line/); - }); }); describe("publish", () => { @@ -110,10 +95,7 @@ describe("publish", () => { tag: "v1.2.3", head: "head1", baseTree: "base1", - files: [ - { path: ACTION, content: "a" }, - { path: CHECKSUMS, content: "c" }, - ], + files: [{ path: CHECKSUMS, content: "c" }], }; test("tags a signed commit on top of the release commit", async () => { @@ -121,18 +103,15 @@ describe("publish", () => { assert.equal(await publish({ ...args, fetch }), "commit1"); assert.deepEqual( calls.map((c) => `${c.method} ${c.path}`), - ["POST git/blobs", "POST git/blobs", "POST git/trees", "POST git/commits", "GET git/commits/commit1", "POST git/refs"], + ["POST git/blobs", "POST git/trees", "POST git/commits", "GET git/commits/commit1", "POST git/refs"], ); - assert.deepEqual(calls[0].body, { content: Buffer.from("a").toString("base64"), encoding: "base64" }); - assert.deepEqual(calls[2].body, { + assert.deepEqual(calls[0].body, { content: Buffer.from("c").toString("base64"), encoding: "base64" }); + assert.deepEqual(calls[1].body, { base_tree: "base1", - tree: [ - { path: ACTION, mode: "100644", type: "blob", sha: "blob1" }, - { path: CHECKSUMS, mode: "100644", type: "blob", sha: "blob2" }, - ], + tree: [{ path: CHECKSUMS, mode: "100644", type: "blob", sha: "blob1" }], }); - assert.deepEqual(calls[3].body.parents, ["head1"]); - assert.deepEqual(calls[5].body, { ref: "refs/tags/verify-v1.2.3", sha: "commit1" }); + assert.deepEqual(calls[2].body.parents, ["head1"]); + assert.deepEqual(calls[4].body, { ref: "refs/tags/verify-v1.2.3", sha: "commit1" }); }); test("does not tag an unsigned commit", async () => { From 7b1f434cfd834c845297ef50070e9ca7d25f6a77 Mon Sep 17 00:00:00 2001 From: Jeff Martin Date: Thu, 19 Nov 2026 14:57:15 -0800 Subject: [PATCH 18/20] Open the pull request that stamps main after a stable release The release workflow commits the new checksums.json on a verify-stamp- branch off main, opens the pull request, and dispatches the test and verify-lockfile workflows on it, since pull requests opened by the workflow token don't trigger pull_request runs. Reruns reuse the branch and pull request. Release candidates and releases that aren't the latest skip it. --- .github/workflows/release.yml | 2 + .github/workflows/test.yml | 3 + .github/workflows/verify-lockfile.yml | 3 + script/verify-action-release.mjs | 102 +++++++++++++++++++++----- script/verify-action-release.test.mjs | 81 +++++++++++++++++++- 5 files changed, 170 insertions(+), 21 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 0ec65b6a..53ad192d 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -42,6 +42,8 @@ jobs: permissions: contents: write attestations: read + pull-requests: write + actions: write runs-on: ubuntu-latest env: GH_TOKEN: ${{ github.token }} diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index ea7a2268..0b42a013 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -2,6 +2,9 @@ name: test on: pull_request: + # The release workflow dispatches this on its stamp pull request, which + # GITHUB_TOKEN can't trigger through pull_request. + workflow_dispatch: push: branches: - main diff --git a/.github/workflows/verify-lockfile.yml b/.github/workflows/verify-lockfile.yml index 83cc5252..2e6f86ec 100644 --- a/.github/workflows/verify-lockfile.yml +++ b/.github/workflows/verify-lockfile.yml @@ -9,6 +9,9 @@ name: verify-lockfile on: pull_request: + # The release workflow dispatches this on its stamp pull request, which + # GITHUB_TOKEN can't trigger through pull_request. + workflow_dispatch: push: branches: - main diff --git a/script/verify-action-release.mjs b/script/verify-action-release.mjs index 12441f98..c3e62113 100644 --- a/script/verify-action-release.mjs +++ b/script/verify-action-release.mjs @@ -1,11 +1,11 @@ // Publishes verify- for a CLI release: checks the release binaries' // attestations, records the tag and their checksums in actions/verify/checksums.json, -// and tags -// a GitHub-signed commit on top of the release commit. +// and tags a GitHub-signed commit on top of the release commit. For a stable +// release it then opens a pull request that stamps main the same way. // // Usage (release workflow, with GH_TOKEN and REPO set): // node script/verify-action-release.mjs -// To restamp the working tree only, for example to move main to a newer release: +// To restamp the working tree only, as a manual fallback for main's stamp pull request: // node script/verify-action-release.mjs --stamp-only import { spawnSync } from "node:child_process"; @@ -61,20 +61,24 @@ function github({ api, token, repo, fetch: fetchFn = fetch }) { }); if (allow404 && res.status === 404) return null; if (!res.ok) throw new Error(`${method} ${path}: HTTP ${res.status} ${await res.text()}`); - return res.json(); + return res.status === 204 ? null : res.json(); }; } -// stampedFor returns the version root's checksums.json records, or null if it's -// missing or malformed. -export async function stampedFor(root) { +function stampedVersion(text) { try { - return parseChecksums(await readFile(join(root, CHECKSUMS), "utf8")).version; + return parseChecksums(text).version; } catch { return null; } } +// stampedFor returns the version root's checksums.json records, or null if it's +// missing or malformed. +export async function stampedFor(root) { + return existsSync(join(root, CHECKSUMS)) ? stampedVersion(await readFile(join(root, CHECKSUMS), "utf8")) : null; +} + // published returns the commit verify- points at, or null if the tag // doesn't exist. A rerun only skips the tag if it's a signed commit directly on // head whose tree is exactly tree, the freshly stamped one; anything else fails. @@ -117,6 +121,61 @@ export async function publish({ api, token, repo, tag, head, baseTree, files, fe return commit; } +export const STAMP_WORKFLOWS = ["test.yml", "verify-lockfile.yml"]; + +// openStampPR opens a pull request that stamps main for tag with content, the +// stamped checksums.json, when tag is the latest release and main isn't stamped +// for it yet. A rerun reuses the branch and pull request. Pull requests opened +// with GITHUB_TOKEN don't start pull_request workflows, so it dispatches the +// required checks on the branch instead; workflow_dispatch is exempt from that. +export async function openStampPR({ api, token, repo, tag, content, fetch: fetchFn = fetch, log = console.log }) { + const call = github({ api, token, repo, fetch: fetchFn }); + const latest = await call("GET", "releases/latest"); + if (latest.tag_name !== tag) { + log(`${tag} isn't the latest release (${latest.tag_name}); not stamping main`); + return null; + } + const main = (await call("GET", "git/ref/heads/main")).object.sha; + const onMain = await call("GET", `contents/${CHECKSUMS}?ref=${main}`, undefined, { allow404: true }); + if (onMain && stampedVersion(Buffer.from(onMain.content, "base64").toString()) === tag) { + log(`main is already stamped for ${tag}`); + return null; + } + + const branch = `verify-stamp-${tag}`; + const existing = await call("GET", `contents/${CHECKSUMS}?ref=${encodeURIComponent(branch)}`, undefined, { allow404: true }); + if (!existing) { + const { tree } = await call("GET", `git/commits/${main}`); + const blob = await call("POST", "git/blobs", { content: Buffer.from(content).toString("base64"), encoding: "base64" }); + const { sha: treeSha } = await call("POST", "git/trees", { + base_tree: tree.sha, + tree: [{ path: CHECKSUMS, mode: "100644", type: "blob", sha: blob.sha }], + }); + const { sha: commit } = await call("POST", "git/commits", { + message: `Stamp actions/verify on main for ${tag}`, + tree: treeSha, + parents: [main], + }); + await call("POST", "git/refs", { ref: `refs/heads/${branch}`, sha: commit }); + } else if (Buffer.from(existing.content, "base64").toString() !== content) { + throw new Error(`branch ${branch} exists with a different ${CHECKSUMS}`); + } + + const owner = repo.split("/")[0]; + const [open] = await call("GET", `pulls?state=open&base=main&head=${encodeURIComponent(`${owner}:${branch}`)}`); + const pr = + open ?? + (await call("POST", "pulls", { + title: `Stamp actions/verify on main for ${tag}`, + head: branch, + base: "main", + body: `Records ${tag} and its release binaries' checksums in \`${CHECKSUMS}\`, so \`script/release\` can cut the next release.`, + })); + for (const wf of STAMP_WORKFLOWS) await call("POST", `actions/workflows/${wf}/dispatches`, { ref: branch }); + log(`Stamp pull request: ${pr.html_url}`); + return pr.html_url; +} + function run(cmd, args, opts = {}) { const r = spawnSync(cmd, args, { encoding: "utf8", stdio: ["ignore", "pipe", "inherit"], ...opts }); if (r.status !== 0) throw new Error(`${cmd} ${args.join(" ")} failed`); @@ -159,19 +218,22 @@ async function main(tag, { stampOnly = false } = {}) { const done = await published({ api, token, repo, tag, head, tree }); if (done) { console.log(`verify-${tag} already exists at ${done}`); - return; + } else { + const commit = await publish({ + api, + token, + repo, + tag, + head, + baseTree: run("git", ["rev-parse", "HEAD^{tree}"], { cwd: root }), + files: [{ path: CHECKSUMS, content: await readFile(join(root, CHECKSUMS)) }], + }); + console.log(`Tagged verify-${tag} at ${commit}`); + } + // main carries stable releases only. + if (!tag.includes("-rc.")) { + await openStampPR({ api, token, repo, tag, content: await readFile(join(root, CHECKSUMS), "utf8") }); } - const files = [{ path: CHECKSUMS, content: await readFile(join(root, CHECKSUMS)) }]; - const commit = await publish({ - api, - token, - repo, - tag, - head, - baseTree: run("git", ["rev-parse", "HEAD^{tree}"], { cwd: root }), - files, - }); - console.log(`Tagged verify-${tag} at ${commit}`); } if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { diff --git a/script/verify-action-release.test.mjs b/script/verify-action-release.test.mjs index 4624d560..fb583aa9 100644 --- a/script/verify-action-release.test.mjs +++ b/script/verify-action-release.test.mjs @@ -6,7 +6,7 @@ import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; import { afterEach, beforeEach, describe, test } from "node:test"; import { parseChecksums } from "../actions/verify/lib.mjs"; -import { ASSETS, CHECKSUMS, checkTag, publish, published, stamp, stampedFor } from "./verify-action-release.mjs"; +import { ASSETS, CHECKSUMS, checkTag, openStampPR, publish, published, stamp, stampedFor } from "./verify-action-release.mjs"; const repoRoot = join(dirname(fileURLToPath(import.meta.url)), ".."); @@ -162,3 +162,82 @@ describe("published", () => { await assert.rejects(published({ ...args, fetch }), /already exists at tagobj/); }); }); + +describe("openStampPR", () => { + const content = JSON.stringify({ version: "v1.2.3", sha256: { "linux-amd64": "a".repeat(64) } }, null, 2) + "\n"; + const file = (text) => ({ content: Buffer.from(text).toString("base64") }); + const old = JSON.stringify({ version: "v1.2.2", sha256: {} }); + const args = { api: "https://api.test", token: "tok", repo: "o/r", tag: "v1.2.3", content, log: () => {} }; + + // fakeAPI answers "METHOD path" keys; a missing GET is a 404. + function fakeAPI(responses) { + const calls = []; + const fetch = async (url, { method, body }) => { + const key = `${method} ${url.replace("https://api.test/repos/o/r/", "")}`; + calls.push({ key, body: body && JSON.parse(body) }); + if (key.includes("/dispatches")) return new Response(null, { status: 204 }); + if (!(key in responses)) { + if (method === "GET") return new Response("Not Found", { status: 404 }); + throw new Error(`unexpected ${key}`); + } + return new Response(JSON.stringify(responses[key]), { status: 200 }); + }; + return { calls, fetch }; + } + const base = { + "GET releases/latest": { tag_name: "v1.2.3" }, + "GET git/ref/heads/main": { object: { sha: "main1" } }, + "GET contents/actions/verify/checksums.json?ref=main1": file(old), + }; + const dispatches = ["POST actions/workflows/test.yml/dispatches", "POST actions/workflows/verify-lockfile.yml/dispatches"]; + + test("commits the stamp on main, opens the pull request and dispatches its checks", async () => { + const { calls, fetch } = fakeAPI({ + ...base, + "GET git/commits/main1": { tree: { sha: "maintree" } }, + "POST git/blobs": { sha: "blob1" }, + "POST git/trees": { sha: "tree1" }, + "POST git/commits": { sha: "commit1" }, + "POST git/refs": {}, + "GET pulls?state=open&base=main&head=o%3Averify-stamp-v1.2.3": [], + "POST pulls": { html_url: "https://github.test/o/r/pull/7" }, + }); + assert.equal(await openStampPR({ ...args, fetch }), "https://github.test/o/r/pull/7"); + const body = (k) => calls.find((c) => c.key === k).body; + assert.equal(Buffer.from(body("POST git/blobs").content, "base64").toString(), content); + assert.deepEqual(body("POST git/trees").base_tree, "maintree"); + assert.deepEqual(body("POST git/commits").parents, ["main1"]); + assert.deepEqual(body("POST git/refs"), { ref: "refs/heads/verify-stamp-v1.2.3", sha: "commit1" }); + assert.equal(body("POST pulls").head, "verify-stamp-v1.2.3"); + assert.equal(body("POST pulls").base, "main"); + assert.deepEqual(calls.filter((c) => c.key.endsWith("/dispatches")).map((c) => c.key), dispatches); + assert.deepEqual(body(dispatches[0]), { ref: "verify-stamp-v1.2.3" }); + }); + + test("a rerun reuses the branch and pull request and dispatches the checks again", async () => { + const { calls, fetch } = fakeAPI({ + ...base, + "GET contents/actions/verify/checksums.json?ref=verify-stamp-v1.2.3": file(content), + "GET pulls?state=open&base=main&head=o%3Averify-stamp-v1.2.3": [{ html_url: "https://github.test/o/r/pull/7" }], + }); + assert.equal(await openStampPR({ ...args, fetch }), "https://github.test/o/r/pull/7"); + assert.deepEqual(calls.filter((c) => c.key.startsWith("POST")).map((c) => c.key), dispatches); + }); + + test("fails when the stamp branch holds something else", async () => { + const { fetch } = fakeAPI({ ...base, "GET contents/actions/verify/checksums.json?ref=verify-stamp-v1.2.3": file(old) }); + await assert.rejects(openStampPR({ ...args, fetch }), /branch verify-stamp-v1\.2\.3 exists with a different/); + }); + + test("does nothing when main is already stamped", async () => { + const { calls, fetch } = fakeAPI({ ...base, "GET contents/actions/verify/checksums.json?ref=main1": file(content) }); + assert.equal(await openStampPR({ ...args, fetch }), null); + assert.ok(calls.every((c) => c.key.startsWith("GET"))); + }); + + test("does nothing for a release that isn't the latest", async () => { + const { calls, fetch } = fakeAPI({ "GET releases/latest": { tag_name: "v1.3.0" } }); + assert.equal(await openStampPR({ ...args, fetch }), null); + assert.equal(calls.length, 1); + }); +}); From 7ddc4a2309df77a05737528457b60aeb36082095 Mon Sep 17 00:00:00 2001 From: Jeff Martin Date: Thu, 19 Nov 2026 14:57:15 -0800 Subject: [PATCH 19/20] Point release docs at the stamp pull request --- RELEASING.md | 21 ++++++++++++++------- script/release | 2 +- 2 files changed, 15 insertions(+), 8 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index 0b6fe37c..adb02919 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -35,10 +35,9 @@ the release script again for the next RC. Rerunning a step is safe. If the push was held, rerun the same command: it pushes the local tag when that tag already points at `HEAD`, and stops if it points anywhere else. After a successful push, a rerun stops at the next step: -stamping `main`. Rerunning the tag workflow checks the attestations again and skips +stamping `main`. Rerunning the tag workflow checks the attestations again, skips tagging when `verify-vX.Y.Z` is already that same signed stamp on the release -commit, and `--stamp-only` skips -a tree that's already stamped for the tag. +commit, and reuses the stamp branch and pull request for `main`. Use `patch` for compatible fixes, `minor` for compatible additions, and `major` for breaking changes. @@ -59,11 +58,19 @@ tags it `verify-vX.Y.Z`. Don't edit `checksums.json` by hand. `main` also carries a stamp, so this repository's own `verify-lockfile` workflow runs the action the way other repositories do. The stamp for a release can only land after it: the binaries embed the commit they're built from. So -after each release, run +for a stable release that's the latest release, the tag workflow also commits +the same `checksums.json` to a `verify-stamp-vX.Y.Z` branch off `main`, opens the +"Stamp actions/verify on main for vX.Y.Z" pull request, and dispatches the +`test` and `verify-lockfile` workflows on it (pull requests opened by the +workflow token don't trigger `pull_request` runs). Review and merge it like any +other pull request. Release candidates don't stamp `main`. + +`script/release` refuses to cut the next release, including a release +candidate, until `main` is stamped for the latest stable release. If the stamp +pull request is missing, run `node script/verify-action-release.mjs --stamp-only vX.Y.Z` (it checks the -attestations with `gh`) and merge the result. `script/release` refuses to cut -the next release, including a release candidate, until `main` is stamped for -the latest stable release. Stamp `main` with stable releases only. +attestations with `gh`) and open one by hand. `--stamp-only` skips a tree that's +already stamped for the tag. ## Dependabot compatibility diff --git a/script/release b/script/release index c86b9bbf..9ff20b65 100755 --- a/script/release +++ b/script/release @@ -58,7 +58,7 @@ require_current_stamp() { stamped="$( (git show refs/remotes/origin/main:actions/verify/checksums.json 2>/dev/null || true) | node -e 'let s = ""; process.stdin.on("data", (d) => (s += d)).on("end", () => { try { process.stdout.write(String(JSON.parse(s).version)); } catch {} });')" [ "$stamped" = "${latest}" ] || - die "actions/verify on main isn't stamped for ${latest} (got '${stamped}'); run 'node script/verify-action-release.mjs --stamp-only ${latest}' and merge that first" + die "actions/verify on main isn't stamped for ${latest} (got '${stamped}'); merge the release workflow's stamp pull request first (see RELEASING.md)" } require_clean() { From 40b8c5574d715100800793d9513f1058e2c30420 Mon Sep 17 00:00:00 2001 From: Jeff Martin Date: Thu, 19 Nov 2026 15:00:35 -0800 Subject: [PATCH 20/20] RELEASING.md: rerun stop point and stamp pull request fallback --- RELEASING.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/RELEASING.md b/RELEASING.md index adb02919..8943beba 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -34,8 +34,8 @@ the release script again for the next RC. Rerunning a step is safe. If the push was held, rerun the same command: it pushes the local tag when that tag already points at `HEAD`, and stops if it -points anywhere else. After a successful push, a rerun stops at the next step: -stamping `main`. Rerunning the tag workflow checks the attestations again, skips +points anywhere else. After a successful push, a rerun stops until the stamp +pull request below is merged. Rerunning the tag workflow checks the attestations again, skips tagging when `verify-vX.Y.Z` is already that same signed stamp on the release commit, and reuses the stamp branch and pull request for `main`. @@ -63,7 +63,9 @@ the same `checksums.json` to a `verify-stamp-vX.Y.Z` branch off `main`, opens th "Stamp actions/verify on main for vX.Y.Z" pull request, and dispatches the `test` and `verify-lockfile` workflows on it (pull requests opened by the workflow token don't trigger `pull_request` runs). Review and merge it like any -other pull request. Release candidates don't stamp `main`. +other pull request. If a required check or code scanning never reports on it, +close and reopen the pull request to start the `pull_request` runs. Release +candidates don't stamp `main`. `script/release` refuses to cut the next release, including a release candidate, until `main` is stamped for the latest stable release. If the stamp