GitHub Actions lockfiles pin executed code, but not the entire CI pipeline

Can you trust GitHub Actions if a workflow references an action by a tag such as @v3? A lockfile specifies which commit of the action will run, even if the tag later moves. Teams can review dependency updates in diffs and keep an auditable list of actions used by CI. There is a practical limit: the lockfile covers actions called by steps, while a reusable workflow called at the job level must be pinned separately. The described mechanism is available in GitHub Enterprise Cloud.

What exactly does the lockfile pin?

Branch and tag references are convenient, but the versions they point to can change. A reference such as uses: octo-org/deploy-action@v3 names a tag; GitHub resolves it to a commit when the workflow runs. If the project owner moves the tag, the next run could receive different code unless the dependency is pinned.

According to GitHub’s lockfile documentation, the .github/workflows/actions.lock file stores dependency references and their corresponding commit SHAs, including transitive dependencies—that is, actions used by other actions. The file is generated by the GitHub CLI extension gh actions-lock; it is not edited manually.

The generator can also make uses references in workflow files more specific—for example, replacing a floating tag reference with the commit it resolved to when the lockfile was created. When adopting the mechanism, review the entire diff—changes to both the workflow and lockfile—and verify that the pinned version is the one the team intends to run.

After that, a dependency update becomes a visible repository change: the team can inspect the commit change, discuss it, and approve it through the usual review process. A lockfile helps audit action code and keep dependencies consistent; it does not, by itself, confirm that the selected code is safe.

Where does pinning stop?

A reusable workflow called through jobs.<job_id>.uses is not pinned by the lockfile in the repository that calls it. The reusable workflow’s dependencies belong to the repository where that workflow is defined. To pin the call itself, specify the full commit SHA; to pin its actions, the source repository needs its own lockfile.

A lockfile controls action code, but not other build inputs, such as parameters passed to an action, secrets, or the runner image. It answers a specific question: which commit of the action code will run? Those other elements require their own controls.

There is also a special case: a local action called through a path such as uses: ./. According to GitHub’s instructions, the gh actions-lock extension does not pin or analyze a local action path. If such an action uses other actions, those dependencies must be managed separately; the documentation describes an option to migrate references to local actions to the $/ format.

As a result, a lockfile entry can cover one link in a chain without replacing controls for every link. For an external reusable workflow, check that the call is pinned and review the source repository; for local actions, check how their dependencies are accounted for.

How can you adopt controls without unexpectedly stopping CI?

GitHub recommends starting with a pilot across selected repositories and workflows. The Require lockfile policy blocks targeted workflows from running without a valid lockfile, including workflows with no uses: dependencies. The Evaluate mode for policies is available only in GitHub Enterprise Cloud. So first define the scope and automate updates, then enable the mandatory rule.

1. Check the source references. Before creating a lockfile, make sure the actions point to versions the team actually wants to pin. The generator pins the commit resolved from the current reference.
2. Create and review the lockfile. Install the gh-actions-lock extension, run gh actions-lock from the repository root, and review the full diff, including any rewritten uses references.
3. Set up updates and verification. Dependabot can update the relevant entries for workflows that are already configured. In CI, you can add a verification job to pull requests using gh actions-lock --verify to detect an outdated lockfile before the main build.
4. Assign reviewers. Add .github/workflows/actions.lock to CODEOWNERS and require review by people responsible for build security.
5. Pilot the policy. Start with configured repositories and workflows. Use Evaluate to analyze the results; before switching to Active, confirm that all targeted workflows are ready and their lockfiles are up to date.

Require lockfile and the separate Require actions to be pinned to a full-length commit SHA policy are different rules; GitHub says they can be used together. CI verification and a mandatory policy also serve different purposes: the first detects an outdated file while a pull request is being worked on, while the second blocks workflows that do not meet the requirement.

Example: updating a deployment action

Suppose a workflow publishes an application using octo-org/deploy-action@v3. The team first checks which version that reference resolves to, then runs gh actions-lock and reviews the workflow diff alongside the commit recorded in the lockfile. When the action is updated, the reviewer can see changes to both the references and the pinned commit, making it possible to assess the specific update rather than assume a moving tag will always point to the same code.

If deployment uses a reusable workflow from another repository, the local lockfile does not cover its dependencies. Pin the reusable workflow reference to a full SHA and check that the source repository manages its own action dependencies. In large organizations, this turns scattered rules into a verifiable process while retaining separate controls for parameters, secrets, and the runner.

A lockfile is useful as a control layer for action code: it makes versions and updates visible, including transitive dependencies. For reliable coverage, also check reusable workflows and local actions, automate updates, and introduce a mandatory policy only after a pilot.