GitHub Actions Workflow Lockfile: Pin Dependencies Without Rewriting YAML

A GitHub Actions workflow can run different code on two separate days even when nobody has changed the workflow file. The reason is that references such as actions/checkout@v4 point to a version tag that can move to another commit. On October 14, 2026, GitHub introduced workflow dependency lockfiles in public preview, offering developers a way to record the exact commits behind their action references while keeping workflow files readable. Here is how the new mechanism works, how to add it to a repository, and what you need to automate before enforcing it across a development team.

Why a GitHub Actions workflow lockfile solves a different problem

GitHub Actions runs automated tasks such as testing code, building applications, publishing packages, and deploying websites. These workflows often rely on reusable actions maintained by other repositories. A workflow might specify actions/checkout@v4, for example, because it needs to download the project's source code before running tests. That reference is convenient, but a tag or branch can be moved, meaning the code resolved during a later run may differ from the code a developer originally reviewed.

GitHub has long recommended pinning third-party actions to full-length commit identifiers, which identify specific revisions of code. The trade-off is that a workflow containing several long identifiers becomes harder to read and maintain. A workflow dependency lockfile separates the human-readable reference from the exact commit used at runtime. The workflow can continue to say which version it intends to use, while the lockfile records the resolved commit and dependency information. This resembles the role of lockfiles in package managers, although the mechanism is designed specifically for GitHub Actions dependencies.

What the new lockfile records and what it cannot protect

The generated file lives at .github/workflows/actions.lock and is maintained by GitHub's command-line extension, gh actions-lock. It records the workflows that have been onboarded and the dependencies associated with them, including commit references and source repository identifiers. It also accounts for transitive dependencies, which are actions used internally by other actions. That matters because reviewing only the action named directly in a workflow can leave additional executable code outside the reviewer's immediate view.

Once a workflow is onboarded, GitHub Actions uses the commit recorded in the lockfile rather than blindly trusting the current destination of a tag or branch. The lockfile also helps reviewers identify dependency changes when updates are proposed. It does not, however, certify that the locked action is safe. A malicious or vulnerable commit can be pinned just as precisely as a trustworthy one, so maintainers must review the source and update dependencies when security fixes become available. The feature addresses unexpected changes in dependency resolution, not every risk in the software supply chain.

Check the workflow references before generating the file

Start in the repository you want to protect and inspect the files under .github/workflows/. Look for uses: entries that reference external actions or reusable workflows, and confirm that each reference points to a version you actually intend to run. This step matters because generating a lockfile records the references as they resolve at that moment; it does not independently establish that those versions are the best or safest choices. If a repository relies on shared reusable workflows, review those dependencies too and plan to onboard the repository that defines each reusable workflow.

Enable Dependabot's GitHub Actions version updates if your repository uses it, or establish another controlled process for reviewing upstream releases. Dependabot can regenerate the corresponding lockfile entry when it updates an already-onboarded action, keeping the version change and resolved commit together in the same pull request. However, it does not automatically onboard a workflow that has no lockfile entries. Teams should identify new workflow files as part of their review process instead of assuming dependency automation will cover every new file.

Install the extension and generate the lockfile

Install the GitHub command-line interface first if it is not already available, then authenticate it for the account and repository you intend to manage. From the repository's root directory, install GitHub's official extension with the following command. The extension is still pre-version-1.0 software, and the public-preview feature can change, so check the current repository instructions if its commands or output differ from these steps.

gh auth status
gh extension install github/gh-actions-lock

Next, generate the lockfile for the workflows you are ready to onboard. Running the command from the repository root allows the extension to discover workflow files and resolve their dependencies. You can also pass a workflow path when you want to adopt the mechanism incrementally rather than changing every workflow at once.

gh actions-lock

After the command completes, inspect the generated .github/workflows/actions.lock file and the workflow changes together. Confirm that the expected workflows appear in the file and that the recorded commits correspond to the versions you meant to lock. Commit the lockfile and any related workflow changes to the same branch. The result should be a reviewable record of the exact dependency code that the onboarded workflows will execute.

Verify the lockfile before relying on it in CI

Generating the file is only the first step; it can become stale when someone changes a workflow without updating its dependency records. Run the extension in verification mode to check the lockfile without intentionally regenerating it. This is suitable for a continuous integration (CI) check, which automatically tests proposed changes before they are merged. A verification failure should send the developer back to the workflow and lockfile changes, rather than letting the mismatch pass unnoticed.

gh actions-lock --verify

The extension also offers a local verification mode for checking that dependency entries are present without contacting GitHub to re-verify the pins. A pre-commit hook can use the following command to catch missing entries before a commit is created.

gh actions-lock --verify-local --no-fix

These checks serve different purposes. The network-based verification can validate the locked references against their upstream history, while local verification checks structural completeness without re-establishing that remote relationship. Neither mode substitutes for reviewing a changed commit or investigating an action's source code. For teams, the strongest workflow combines automated verification with human review of dependency changes.

Automate updates before turning on mandatory enforcement

GitHub's public preview includes a policy called Require lockfile, which administrators can use to require lockfiles at repository, organization, or enterprise scope. When the policy is active for a targeted workflow, runs can be blocked if its action dependencies have not been onboarded to the lockfile. This is useful for preventing teams from bypassing the process, but it also means that enabling enforcement too early can interrupt builds and deployments. GitHub recommends piloting the policy on selected repositories and using Evaluate mode where available before moving to Active mode.

For a reliable rollout, add automation that reacts when workflow files or local action definitions change. One job can regenerate the lockfile when changes are pushed, while a separate pull-request check verifies that the committed lockfile is current. GitHub's enforcement documentation also recommends using code ownership rules to request review of lockfile changes from the people responsible for build security. The important operational detail is that enforcement and maintenance must be introduced together: a policy that demands a lockfile is not enough if developers have no dependable way to update it.

Teams should also plan for workflows that call reusable workflows maintained in other repositories. A lockfile covers dependencies belonging to the workflows defined in its own repository, and dependencies of a reusable workflow are covered by the lockfile in the repository where that reusable workflow is defined. A consumer repository should not assume its own lockfile completely governs every action inside a centrally maintained reusable workflow. Onboarding shared workflow repositories first can make the eventual rollout easier to manage.

Understand the public-preview limits before adopting it widely

GitHub announced the feature for GitHub Free, Team, GitHub Enterprise Cloud, and GitHub Enterprise Cloud with data residency. It remains in public preview, so developers should expect the interface, file format, and behavior to evolve. The announcement does not establish support for GitHub Enterprise Server, so self-hosted enterprise installations should not assume they can enable the same feature. Teams should verify their plan and deployment type before writing an organization-wide migration plan.

There is also a maintenance cost: every meaningful action update can produce a lockfile change that deserves review, and automated updates need the appropriate permissions to commit or propose changes. That work is worthwhile when workflows build or deploy important software, but it should be accounted for rather than treated as a one-time security switch. Start with a representative repository, confirm that generation and verification work in the actual development environment, and test the behavior of the enforcement policy before applying it to production pipelines. A lockfile becomes a useful control when the team can keep it accurate and explain why every change is acceptable.

Who should adopt workflow lockfiles first

Projects that deploy production services, publish packages, or run workflows with access to deployment credentials have a strong reason to consider dependency locking early. Smaller repositories can begin with a single workflow and a verification check, while organizations with many repositories can use policy evaluation to identify gaps before enforcing a standard. The feature is most effective when the people who approve workflow changes also review the commits recorded in the lockfile and when dependency updates remain routine rather than exceptional. For a repository that is ready to start, the next step is straightforward: generate the file, review the exact commits, commit the result, and prove that the verification check catches an outdated lockfile before making the policy mandatory.