Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
dc8dd99
Add actions/verify composite action
nodeselector Nov 19, 2026
31be556
Publish verify-vX.Y.Z action tags from the release workflow
nodeselector Nov 19, 2026
8f6ad9c
Verify this repository's lockfile with actions/verify
nodeselector Nov 19, 2026
195b118
Document the verify action and its token caveat
nodeselector Nov 19, 2026
fbafe8e
verify action: hash via stdin, split multiline args, keep GHE.com tok…
nodeselector Nov 19, 2026
b1b70c4
Run this repository's verify action through $/
nodeselector Nov 19, 2026
edefb67
Run the verify action's install and CLI from Node
nodeselector Nov 19, 2026
c65397e
Stamp and tag the verify action from a Node script
nodeselector Nov 19, 2026
4984068
Run the Node tests in CI on Linux and Windows
nodeselector Nov 19, 2026
a6399a4
Run the verify action on node24 and download with fetch
nodeselector Nov 19, 2026
8696c12
Stamp actions/verify on main so the workflow needs no version
nodeselector Nov 19, 2026
6ea0ff1
Require main's verify action stamp before the next release
nodeselector Nov 19, 2026
fd1fa01
script/release-test: remove temp dir without prompting
nodeselector Nov 19, 2026
e82c348
script/release: push a held local tag on rerun
nodeselector Nov 19, 2026
623da7e
verify-action-release: skip steps a previous run already did
nodeselector Nov 19, 2026
3502a77
RELEASING.md: document rerun behavior
nodeselector Nov 19, 2026
1732d8d
Record the verify action's version and checksums in checksums.json
nodeselector Nov 19, 2026
7b1f434
Open the pull request that stamps main after a stable release
nodeselector Nov 19, 2026
7ddc4a2
Point release docs at the stamp pull request
nodeselector Nov 19, 2026
40b8c55
RELEASING.md: rerun stop point and stamp pull request fallback
nodeselector Nov 19, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ on:
push:
tags:
- v*
- "!verify-v*"

permissions:
contents: read
Expand Down Expand Up @@ -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"
5 changes: 5 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 }}
Expand Down
12 changes: 8 additions & 4 deletions .github/workflows/verify-lockfile.yml
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
1 change: 1 addition & 0 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -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 ./...
Expand Down
32 changes: 31 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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:
Expand Down
33 changes: 33 additions & 0 deletions RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
Expand Down
49 changes: 49 additions & 0 deletions actions/verify/README.md
Original file line number Diff line number Diff line change
@@ -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).
19 changes: 19 additions & 0 deletions actions/verify/action.yml
Original file line number Diff line number Diff line change
@@ -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
11 changes: 11 additions & 0 deletions actions/verify/checksums.json
Original file line number Diff line number Diff line change
@@ -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"
}
}
Loading
Loading