diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 84105eee..53ad192d 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,24 @@ 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 + pull-requests: write + actions: write + 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: Publish verify-${{ github.ref_name }} + run: node script/verify-action-release.mjs "$TAG" diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 7e780c16..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 @@ -33,6 +36,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/.github/workflows/verify-lockfile.yml b/.github/workflows/verify-lockfile.yml index c54560d5..2e6f86ec 100644 --- a/.github/workflows/verify-lockfile.yml +++ b/.github/workflows/verify-lockfile.yml @@ -1,10 +1,17 @@ # 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, with the +# CLI release stamped on main. Other repositories pin a verify-v* tag instead; +# see actions/verify/README.md. 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 @@ -15,11 +22,8 @@ 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 diff --git a/Makefile b/Makefile index 460e6730..208acd6a 100644 --- a/Makefile +++ b/Makefile @@ -17,6 +17,7 @@ test: test-release test-release: script/release-test + node --test actions/verify/lib.test.mjs script/verify-action-release.test.mjs vet: go vet ./... 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/RELEASING.md b/RELEASING.md index 264ce23e..8943beba 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -32,6 +32,13 @@ 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 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`. + Use `patch` for compatible fixes, `minor` for compatible additions, and `major` for breaking changes. @@ -41,6 +48,32 @@ 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/verify-action-release.mjs` checks the release binaries' +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 +can only land after it: the binaries embed the commit they're built from. So +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. 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 +pull request is missing, run +`node script/verify-action-release.mjs --stamp-only vX.Y.Z` (it checks the +attestations with `gh`) and open one by hand. `--stamp-only` skips a tree that's +already stamped for the tag. + ## Dependabot compatibility Before releasing, decide whether diff --git a/actions/verify/README.md b/actions/verify/README.md new file mode 100644 index 00000000..7d970450 --- /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. + +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 + +| Input | Default | Description | +|---|---|---| +| `token` | `${{ github.token }}` | Token the CLI uses to read action repositories. | +| `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 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 + +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..4d187124 --- /dev/null +++ b/actions/verify/action.yml @@ -0,0 +1,19 @@ +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.5.1. Defaults to the release recorded in checksums.json. + required: false + args: + description: Arguments passed to gh-actions-lock, split on whitespace. + required: false + default: --verify + +runs: + using: node24 + main: verify.mjs 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/lib.mjs b/actions/verify/lib.mjs new file mode 100644 index 00000000..826bdfcb --- /dev/null +++ b/actions/verify/lib.mjs @@ -0,0 +1,197 @@ +// 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 { 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"; + +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); +} + +// 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}`); + } + 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 +// 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 leave version empty`, + ); + } + } + 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"); +} + +// 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 in checksums.json"); + } + 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 = downloadFile, gh = runGh, log = console.log }) { + 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.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 }); + const bin = join(dir, `gh-actions-lock${ext}`); + const url = `https://github.com/${REPO}/releases/download/${version}/${asset}`; + await download(url, bin); + + 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 checksums.json.`); + } 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..2f12dd58 --- /dev/null +++ b/actions/verify/lib.test.mjs @@ -0,0 +1,325 @@ +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, downloadFile, install, parseChecksums, selectCheck, splitArgs, useEnvProxy, withSubdomainNoProxy } 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("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 = { 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"), { version: "v0.4.2", 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("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/); + }); +}); + +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 = (url, dest) => writeFile(dest, binary); + const quiet = () => {}; + + async function stampedAction(version, asset, sum = sha(binary)) { + await writeFile(join(tmp, "checksums.json"), JSON.stringify({ version, sha256: { [asset]: sum } })); + 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("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)); + 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("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", + 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/, + ); + }); +}); + +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( + 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 new file mode 100644 index 00000000..3d46fd50 --- /dev/null +++ b/actions/verify/verify.mjs @@ -0,0 +1,24 @@ +import { spawnSync } from "node:child_process"; +import http from "node:http"; +import { dirname } from "node:path"; +import { fileURLToPath } from "node:url"; +import { install, splitArgs, useEnvProxy, withSubdomainNoProxy } from "./lib.mjs"; + +const run = (cmd, args, env) => { + const r = spawnSync(cmd, args, { stdio: "inherit", env }); + if (r.error) throw r.error; + 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; +} diff --git a/script/release b/script/release index d9f6ed1c..9ff20b65 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, node, and actions/verify on main stamped for the latest +# release (see RELEASING.md). set -euo pipefail @@ -48,6 +49,18 @@ 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.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}'); merge the release workflow's stamp pull request first (see RELEASING.md)" +} + require_clean() { if [ -n "$(git status --porcelain)" ]; then git --no-pager status --short >&2 @@ -78,7 +91,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 @@ -96,6 +111,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 @@ -122,8 +138,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 @@ -131,7 +154,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 c8311d45..ded104b6 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" @@ -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 '{"version": "v1.2.3", "sha256": {}}\n' >actions/verify/checksums.json git add . git commit --quiet -m initial git push --quiet -u origin main @@ -39,6 +41,51 @@ output="$(RELEASE_DRY_RUN=1 script/release patch --rc)" output="$(RELEASE_DRY_RUN=1 script/release patch)" [[ "$output" == *"Cutting v1.2.4 "* ]] +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 + 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.json +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 + +# 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 '{"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 +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")" diff --git a/script/verify-action-release.mjs b/script/verify-action-release.mjs new file mode 100644 index 00000000..c3e62113 --- /dev/null +++ b/script/verify-action-release.mjs @@ -0,0 +1,250 @@ +// 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. 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, as a manual fallback for main's stamp pull request: +// node script/verify-action-release.mjs --stamp-only + +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"; +import { parseChecksums } from "../actions/verify/lib.mjs"; + +export const ASSETS = [ + "linux-amd64", + "linux-arm64", + "darwin-amd64", + "darwin-arm64", + "windows-amd64.exe", + "windows-arm64.exe", +]; +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 ?? "")) { + throw new Error(`invalid tag '${tag}'; expected vX.Y.Z or vX.Y.Z-rc.N`); + } + return tag; +} + +// 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 sha256 = {}; + for (const a of ASSETS) { + const path = join(assetsDir, a); + if (!existsSync(path)) throw new Error(`missing release asset ${path}`); + sha256[a] = createHash("sha256").update(await readFile(path)).digest("hex"); + } + await writeFile(join(root, CHECKSUMS), JSON.stringify({ version: tag, sha256 }, null, 2) + "\n"); +} + +// 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: { + authorization: `Bearer ${token}`, + accept: "application/vnd.github+json", + "content-type": "application/json", + }, + 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.status === 204 ? null : res.json(); + }; +} + +function stampedVersion(text) { + try { + 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. +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) { + 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; +} + +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`); + return r.stdout.trim(); +} + +async function main(tag, { stampOnly = false } = {}) { + checkTag(tag); + 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 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(`${CHECKSUMS} is 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]); + 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 }); + if (stampOnly) { + 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", "--", 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}`); + } 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") }); + } +} + +if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) { + try { + 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 new file mode 100644 index 00000000..fb583aa9 --- /dev/null +++ b/script/verify-action-release.test.mjs @@ -0,0 +1,243 @@ +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 { parseChecksums } from "../actions/verify/lib.mjs"; +import { ASSETS, CHECKSUMS, checkTag, openStampPR, publish, published, stamp, stampedFor } 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("checked-in stamp", () => { + 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:/); + }); +}); + +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); + for (const a of ASSETS) await writeFile(join(assetsDir, a), a); + }); + afterEach(async () => { + await rm(root, { recursive: true, force: true }); + }); + + 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 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 () => { + 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("restamps an earlier stamp", async () => { + await stamp({ root, tag: "v1.2.3", assetsDir }); + await stamp({ root, tag: "v1.2.4", assetsDir }); + assert.equal(await stampedFor(root), "v1.2.4"); + }); + + test("stampedFor is null when checksums.json is missing or malformed", async () => { + assert.equal(await stampedFor(root), null); + await writeFile(join(root, CHECKSUMS), "version: v1.2.2\n"); + assert.equal(await stampedFor(root), null); + }); +}); + +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: 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/trees", "POST git/commits", "GET git/commits/commit1", "POST git/refs"], + ); + assert.deepEqual(calls[0].body, { content: Buffer.from("c").toString("base64"), encoding: "base64" }); + assert.deepEqual(calls[1].body, { + base_tree: "base1", + tree: [{ path: CHECKSUMS, mode: "100644", type: "blob", sha: "blob1" }], + }); + 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 () => { + 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/); + }); +}); + +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/); + }); +}); + +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); + }); +}); 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