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 uses dependencies.
• An existing workflow adds or removes uses dependencies.

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.