README
¶
gh-actions-lock
Lock your workflow dependencies.
[!WARNING] Technical Preview. gh-actions-lock is pre-1.0 and under active development. The lockfile format, command flags, and behavior may change without notice between releases. Use it, file issues, and expect rough edges.
Background
gh-actions-lock is part of GitHub's Workflow Dependency Pinning effort. It gives repositories a lockfile that pins every workflow dependency to a verified commit, so what runs on the runner is exactly what you locked. Development is ongoing and behavior may still change.
Contributions are welcome. See CONTRIBUTING.md to get started.
Requirements
Requires the gh CLI. Install it first, then install the extension:
gh extension install github/gh-actions-lock
Usage
Scan every workflow under .github/workflows/ directory, pin each resolvable action to a SHA, and update the lockfile:
gh actions-lock
After the initial run to onboard workflows, you will need to run gh actions-lock when:
- A new workflow is created that has
usesdependencies. - An existing workflow adds or removes
usesdependencies.
A full-directory run (gh actions-lock with no path arguments) also prunes lockfile entries for workflows that have been deleted from .github/workflows/, dropping any dependencies left orphaned by the removal. Scoped runs that name specific workflows never prune out-of-scope entries.
Pins to branches or partial versions (e.g. main, v4) are trusted from the
lockfile and not re-resolved on a normal run. To bump them to the current
upstream commit, run:
gh actions-lock --relock
--relock re-resolves refs that have legitimately moved and rewrites the
lockfile to the new SHA. Suspicious pins whose recorded commit is no longer
reachable upstream are left as errors — use --accept-moved to re-resolve
those as well.
Self repository actions ($/…)
uses: $/… references an action or reusable workflow in the same repository as
the defining file, resolved at the running commit. Because it always resolves to
that repository's running SHA it is inherently pinned — no lockfile entry is
required, and it is valid anywhere a relative ./… reference is:
steps:
- uses: $/actions/my-action # same-repo action, inherently pinned
jobs:
call:
uses: $/.github/workflows/reusable.yml # same-repo reusable workflow
A trailing @ref (e.g. $/actions/my-action@v1) is rejected — the ref is always
the running commit.
Same-repo ./… composite action references are automatically converted to $/…
on fix runs. This rewrites ./… steps both in your workflows and in your in-repo
composite action definitions (action.yml). Only ./… paths that resolve to an
in-repo action file are rewritten. To leave ./… refs untouched, opt out with
--no-migrate-local-actions:
gh actions-lock --no-migrate-local-actions
How it works
A repo gets a lockfile (located at .github/workflows/actions.lock) and workflows are onboarded to the lockfile on a per-workflow basis.
Workflows that are onboarded to the lockfile enforce that all dependencies are present in the lockfile and guarantees that the locked commit for an Action is what's executed on the runner. Lockfiles are also verified for forgeries. The sha must exist in the refs it's stated to exist in. Repository identity is recorded and redirects and mismatches are blocked at runtime.
Finally, locked actions must have a branch that the commit being locked exists within. This is to make impostor commit style attacks harder.
Limitations
There are currently eligibility limitations for workflows that can be onboarded to lockfiles:
- Workflows in the lockfile cannot use local-path actions, these will be skipped for onboarding. This is also a short-term gap.
License
This project is licensed under the terms of the MIT open source license. See LICENSE for the full terms.
Maintainers
gh-actions-lock is maintained by @github/actions-dispatch-reviewers. See CODEOWNERS.
Support
Support is best-effort and community-based. Please file bugs and feature requests as GitHub issues. See SUPPORT.md for details.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
gh-actions-lock
command
Command gh-actions-lock scans workflows and pins GitHub Actions to immutable commit SHAs.
|
Command gh-actions-lock scans workflows and pins GitHub Actions to immutable commit SHAs. |
|
gh-actions-lock/format
Package format renders check reports for the `check` command.
|
Package format renders check reports for the `check` command. |
|
internal
|
|
|
config
Package config loads CLI configuration from file and environment.
|
Package config loads CLI configuration from file and environment. |
|
dep
Package dep defines the working dependency types shared between the resolver and the lockfile.
|
Package dep defines the working dependency types shared between the resolver and the lockfile. |
|
ghapi
Package ghapi provides a unified GitHub API client that owns both REST and GraphQL connections, retry transport, and profiling instrumentation.
|
Package ghapi provides a unified GitHub API client that owns both REST and GraphQL connections, retry transport, and profiling instrumentation. |
|
ghapi/httpmock
Package httpmock provides HTTP test fakes for the ghapi client.
|
Package httpmock provides HTTP test fakes for the ghapi client. |
|
lockfile
Package lockfile manages CLI lockfile state: loading, saving, and converting the on-disk format.
|
Package lockfile manages CLI lockfile state: loading, saving, and converting the on-disk format. |
|
pin
Package pin implements the two-phase pin lifecycle: Plan builds a complete Record of what to pin (pure computation + network reads), and Commit writes the Record to disk (workflow files + lockfile).
|
Package pin implements the two-phase pin lifecycle: Plan builds a complete Record of what to pin (pure computation + network reads), and Commit writes the Record to disk (workflow files + lockfile). |
|
pinpool
Package pinpool is a small generic worker pool with a Reporter hook for per-slot UI status.
|
Package pinpool is a small generic worker pool with a Reporter hook for per-slot UI status. |
|
pipeline
Package pipeline orchestrates the scan, resolve, check, and report flow for a single run.
|
Package pipeline orchestrates the scan, resolve, check, and report flow for a single run. |
|
pipeline/checks
Package checks implements the structural, misleading-sha, and resolver-bound validators run against parsed workflows.
|
Package checks implements the structural, misleading-sha, and resolver-bound validators run against parsed workflows. |
|
profile
Package profile captures phase timing, CPU profiles, and HTTP round-trip logs for performance analysis.
|
Package profile captures phase timing, CPU profiles, and HTTP round-trip logs for performance analysis. |
|
resolve
Package resolve resolves action refs to commit SHAs, recursively discovers transitive dependencies, and verifies commit reachability.
|
Package resolve resolves action refs to commit SHAs, recursively discovers transitive dependencies, and verifies commit reachability. |
|
syncmap
Package syncmap provides a simple generic mutex-guarded map.
|
Package syncmap provides a simple generic mutex-guarded map. |
|
tag
Package tag lists tags, classifies versions, and applies release cooldown.
|
Package tag lists tags, classifies versions, and applies release cooldown. |
|
ui
Package ui provides terminal-aware output formatting for gh-actions-lock.
|
Package ui provides terminal-aware output formatting for gh-actions-lock. |
|
workflowfile
Package workflowfile owns the parsed workflow YAML representation: loading, extraction of action refs, local composite discovery, and comment-preserving rewriting.
|
Package workflowfile owns the parsed workflow YAML representation: loading, extraction of action refs, local composite discovery, and comment-preserving rewriting. |
|
test
|
|
|
scenarios
Package scenarios provides a shared scenario catalog consumable by both Go tests and the Ruby integration harness.
|
Package scenarios provides a shared scenario catalog consumable by both Go tests and the Ruby integration harness. |