README
¶
gh-actions-lock
Lock your workflow dependencies.
Install
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.
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 must use a hosted runner. In the meantime, we will skip onboarding self-hosted runners. Discerning a self-hosted runner from a Larger runner requires the
manage_runners:orgwhich users are unlikely to have on their CLI in the typical case, if workflows are skipped during onboarding, the cli will output the command to run to allow onboarding those workflows. The requirement for hosted runners is enforced at runtime. This is a short-term gap. - Workflows in the lockfile cannot use local-path actions, these will be skipped for onboarding. This is also a short-term gap.
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. |
Click to show internal directories.
Click to hide internal directories.