Minimal illustration of workflow dependency files, locked versions, and verified CI execution.

Dependency lockfiles are familiar to developers working with npm, Composer, Cargo, and other package managers. They provide a record of the exact dependency versions selected for an application, making installations more reproducible.

Continuous integration workflows face a similar problem. A workflow may reference an external GitHub Action using a version tag or branch name, but that reference does not necessarily identify immutable code.

On October 28, 2026, GitHub announced the general availability of workflow dependency lockfiles for GitHub Actions.

The feature is available on GitHub Enterprise Cloud, Enterprise Cloud with data residency, Team, and Free plans.

It introduces a more structured way to control which action commits execute inside CI pipelines.

The Problem with Mutable References

Consider a workflow that uses a third-party action through a tag:

steps:
  - uses: actions/checkout@v4

This is readable and convenient, but a tag is a reference rather than an immutable commit identifier.

If the reference moves, future workflow executions may use different action code even though the workflow file itself has not changed.

One established defense is to reference an action using its complete commit SHA. That approach improves immutability but makes workflow files less readable and can complicate dependency maintenance.

GitHub’s workflow lockfiles aim to preserve readable references while ensuring that the selected commits remain fixed.

How Workflow Lockfiles Work

GitHub stores workflow dependency information in a file located at:

.github/workflows/actions.lock

The file is generated using the gh actions-lock GitHub CLI extension.

Once a workflow is onboarded, GitHub Actions requires its action dependencies to be represented in the lockfile.

At execution time, the workflow runs the commits recorded in the lockfile rather than resolving the mutable references independently.

This also covers transitive action dependencies within the repository’s workflow dependency graph.

Reusable workflows are handled separately: their dependencies are governed by the lockfile in the repository where the reusable workflow is defined.

A Gradual Adoption Model

One practical advantage is that repositories do not need to migrate every workflow simultaneously.

Teams can onboard workflows individually, beginning with those that have the greatest security exposure or operational importance.

For example, a repository might initially lock its release workflow while leaving less sensitive development workflows unchanged.

After validating the process, the team can extend locking to the remaining workflows.

This incremental approach is useful for established repositories with many external actions and complicated dependency relationships.

Dependabot Integration

GitHub has also integrated workflow lockfiles with Dependabot.

When Dependabot proposes an action version update for an onboarded workflow, it regenerates the corresponding lockfile entry in the same pull request.

This allows reviewers to inspect both the readable dependency reference and the actual commit selected for execution.

Keeping these changes together reduces the risk that workflow references and locked dependencies drift apart.

GitHub also supports checking whether lockfiles are current without modifying repository files, making it possible to detect stale lockfiles during CI.

Policy Enforcement

Repository, organization, and enterprise administrators can enforce adoption through a Require lockfile policy.

This makes workflow locking relevant beyond individual repositories.

Organizations managing many development teams can establish consistent expectations for action dependency resolution while allowing teams to retain readable workflow definitions.

However, policy enforcement should be introduced with appropriate testing. Existing workflows may depend on assumptions about mutable references or third-party action behavior.

Locking Does Not Mean Trusting

A lockfile improves reproducibility, but it does not determine whether the locked code is safe.

If a dependency already contains malicious or vulnerable code, locking that dependency preserves the problem rather than eliminating it.

Security reviews should therefore continue to examine action publishers, requested permissions, dependency updates, and the scope of credentials available to workflows.

Workflow permissions should follow the principle of least privilege. Sensitive release credentials should not be available to unrelated jobs merely because their dependencies are locked.

Teams should also remember that lockfiles are not a substitute for reviewing changes introduced through Dependabot pull requests.

What About Reproducible Builds?

Workflow lockfiles improve the reproducibility of action dependency resolution. They do not make the entire CI environment reproducible.

A workflow may still depend on changing operating-system packages, container images, network services, external APIs, or application dependencies.

For highly controlled build environments, action locking should be combined with pinned container images, application dependency lockfiles, controlled toolchain versions, and artifact verification.

These measures address different sources of variability.

A Practical Adoption Checklist

  • Inventory external actions used by important workflows.
  • Review the security and maintenance history of those actions.
  • Install the official gh actions-lock extension.
  • Generate and review the workflow lockfile.
  • Commit the lockfile and associated workflow changes together.
  • Verify that workflows execute successfully with locked dependencies.
  • Enable Dependabot updates and stale-lockfile checks.
  • Consider enforcement policies after successful adoption.

The lockfile should be generated by the supported tooling rather than edited manually.

Conclusion

GitHub Actions workflow lockfiles bring a familiar dependency-management concept into CI infrastructure.

The general availability release makes the feature accessible across GitHub’s major account plans and adds a practical mechanism for combining readable workflow definitions with immutable action resolution.

Its value is not that it eliminates software supply-chain risk. It makes one important part of that risk more visible, reviewable, and predictable.

LEAVE A REPLY

Please enter your comment!
Please enter your name here