GitHub Actions Workflow Lockfile Tutorial: Pin CI Dependencies Securely

A GitHub Actions workflow can run different code tomorrow even when nobody has changed your repository. That happens when a workflow references an action through a movable branch or version tag, and the upstream repository changes what that reference points to. On October 14, 2026, GitHub announced the public preview of workflow dependency lockfiles, which let developers keep readable action references while locking execution to reviewed commits. This tutorial walks through generating a lockfile, reviewing the changes, verifying it in continuous integration, and keeping it updated as dependencies change.

Why GitHub Actions needs a dependency lockfile

GitHub Actions automates tasks such as running tests, building applications, publishing packages, and deploying software. A workflow usually lives in a YAML file under .github/workflows/ and uses reusable actions through entries such as uses: actions/checkout@v4. The version tag is convenient because it communicates which release the workflow expects, but a tag or branch can move to another commit. As a result, a future run might execute code that was not present when the original workflow change was reviewed.

A workflow dependency lockfile records the exact commit associated with each action dependency, including supported transitive dependencies, which are dependencies used by other actions. GitHub Actions can then use the recorded commits rather than resolving movable references afresh at run time. The generated file also records source repository identity information, helping GitHub check that a dependency still comes from the repository that was originally locked. The result is more predictable automation and a reviewable record of changes to the code your workflows execute.

GitHub announced the feature as a public preview on October 14, 2026, for GitHub Free, Team, GitHub Enterprise Cloud, and GitHub Enterprise Cloud with data residency. Because it remains in preview, its behavior and tooling may change. Locking also does not prove that an action is trustworthy: it preserves the selected code, including potentially vulnerable code, so security review still matters.

Check your workflow references before generating the lockfile

Start in the root directory of the repository you want to protect. Inspect the workflow files under .github/workflows/ and identify their action references, including calls to reusable workflows in other repositories. Make sure each reference points to the version you actually intend to use before locking it. Otherwise, the lockfile may faithfully preserve a dependency that you should have upgraded or replaced first.

For example, a workflow might contain a checkout action followed by a testing action. Both references should be reviewed for ownership, maintenance status, permissions, and suitability for the job. Do not treat a popular action or a version tag as proof of safety. GitHub recommends reviewing third-party action code and keeping dependencies updated; enabling Dependabot for GitHub Actions can help maintain that process.

Install the GitHub CLI extension

The lockfile is generated by gh actions-lock, an extension for the GitHub command-line interface (CLI). Install the GitHub CLI first if it is not already available, then open a terminal in your repository. You can check whether the command is installed by running gh --version. If the command is missing, install the CLI using the official instructions for your operating system before continuing.

Install the extension with the following command:

gh extension install github/gh-actions-lock

The installation adds the actions-lock subcommand to the GitHub CLI. You can confirm that the extension is available by asking it to display its help information. If installation fails, check that the CLI is working and that your environment can access GitHub repositories. The extension is still part of a public-preview workflow, so check its current documentation if its options differ from those shown here.

Generate actions.lock for your repository

From the repository root, run the extension without arguments to scan the workflows directory and generate the lockfile:

gh actions-lock

The command creates .github/workflows/actions.lock and may also update workflow files. It records the resolved commit for each supported dependency and can rewrite a broad reference such as owner/action@v3 to a more specific version reference. That rewrite makes the workflow easier to read and review, while the lockfile provides the exact commit used during execution. If you prefer to onboard one workflow at a time, pass its path instead:

gh actions-lock.github/workflows/ci.yml

After the command finishes, check that the expected lockfile exists and that the intended workflow appears in its contents. If a workflow is skipped because a local action cannot be resolved, inspect its uses:./… path. Local paths are resolved from the repository root, not from the directory containing the workflow file. Correct the reference and regenerate the lockfile rather than accepting incomplete coverage.

Review the generated changes before committing them

Do not commit the generated files immediately just because the command completed successfully. Inspect the full Git diff, including both workflow changes and actions.lock. The lockfile contains commit identifiers and source repository identity values; a changed commit means that the workflow will run different code, while an unexpected repository identity change deserves investigation. Treat these changes like dependency upgrades, not routine formatting.

Also review repository or organization rules that restrict which actions are permitted. Because the lockfile evaluates dependencies using their locked commits, an allowlist that previously matched a version tag may need adjustment. GitHub's documentation explains that locked dependencies can satisfy its full-length commit SHA pinning requirement, but dependencies not covered by the lockfile still need to comply with applicable policy. Resolve any permission or allowlist conflicts before merging the change.

Once the diff is understood, commit the workflow changes and the generated lockfile together. Keeping them in the same change makes it easier for reviewers to confirm that every workflow reference has corresponding lockfile coverage. Never edit the generated lockfile manually; change the workflow or dependency reference and rerun the extension instead.

Verify that the lockfile stays synchronized

A lockfile is useful only while it matches the workflows it is meant to protect. Whenever you add a workflow, introduce an action, or change a workflow's uses references, run gh actions-lock again and review the resulting diff. For a verification step that checks whether the lockfile is current without updating it, use:

gh actions-lock --verify

This check is suitable for a continuous integration job or another automated validation step. Run it after workflow changes so stale lockfile entries are caught before the pull request is merged. Check the installed extension's help output if the verification options have changed in a later preview release.

Dependabot can help keep existing locked workflows current. When it updates an action reference in a workflow that has already been onboarded, GitHub says it also regenerates the corresponding lockfile entry in the same pull request. However, Dependabot does not automatically onboard workflows that lack lockfile entries, so you still need a process for new workflows and newly introduced dependencies.

Understand what the lockfile does not cover

The lockfile protects the action dependency graph associated with onboarded workflows, but it does not make every part of a software build reproducible. Your workflow may also install operating-system packages, download tools, use container images, fetch application dependencies, or call external services. Those components need their own versioning and integrity controls. A locked action can still download a mutable container tag or an unpinned package unless that dependency is independently controlled.

Reusable workflows need particular care. A workflow lockfile covers the workflows in the repository where it lives, including supported dependencies used by actions. Dependencies of a reusable workflow call are covered by the lockfile in the repository that defines that reusable workflow. If your organization maintains shared workflow repositories, onboard and maintain those repositories as well rather than assuming that locking a caller protects every dependency in the chain.

Finally, distinguish dependency integrity from dependency trust. A lockfile makes the selected code stable and reviewable; it does not certify that the code is free of vulnerabilities, malicious behavior, or excessive permissions. Review what an action can access, use least-privilege workflow permissions, and investigate unexpected changes to locked commits before accepting them.

Roll out enforcement only after verification works

For teams managing multiple repositories, GitHub also provides a preview policy called Require lockfile. Administrators can use it to require workflow lockfiles across targeted repositories or organizations. Turning enforcement on before workflows are onboarded can block automation, so begin with a small pilot and verify that every targeted workflow has a current lockfile. Where the available policy controls support evaluation mode, use it to understand which runs would be affected before switching to active enforcement.

Build the maintenance process before expanding the policy. A verification job can catch stale files in pull requests, while Dependabot can update many existing action references and their corresponding lockfile entries. Assign reviewers to the generated lockfile changes and investigate changes to commit or repository identity values instead of approving them automatically. Once the process is reliable in a small set of repositories, expand coverage and enforcement in stages.

The practical next step is to select one frequently used workflow, review its dependencies, generate the lockfile, and run the verification command in your existing automation. That small pilot will reveal whether local actions, allowlists, shared workflows, and dependency-update routines need attention before the same control is applied across the rest of your repositories.