Actions lockfiles GA: map the reusable-workflow boundary
Adopt the 28 October GA release with explicit coverage for actions, reusable workflows, local actions and mutable container images; verify before policy enforcement.
Quick answer
GitHub announced workflow dependency lockfiles as generally available on 28 October 2026. They record exact commits for action dependencies, including transitive actions. Cross-repository reusable-workflow calls remain a separate pinning and repository-coverage concern. Pilot one workflow, review generated changes, verify the lockfile and confirm shared-workflow coverage before enforcing a Require lockfile policy.
On this page
GitHub announced workflow dependency lockfiles as generally available on 28 October 2026. The practical migration question is which dependencies a repository's lockfile actually covers. Action dependencies and cross-repository reusable-workflow calls have different boundaries. Map those boundaries before enforcing a policy, so a generated file does not become evidence for coverage it never provided. [1][2]
This dated adoption analysis uses documentation read during editorial review. It is not a report of a Dopstack production rollout. The worked repository and team below are fictional, and no extension installation, customer tenant or GitHub policy change was performed for this article.
What became generally available on 28 October?#
GitHub's announcement names Enterprise Cloud, Enterprise Cloud with data residency, Team and Free plans. It describes exact action-commit locking, incremental workflow onboarding, matching Dependabot updates, a Require lockfile policy and stale-file checks. The release expands the feature beyond its earlier preview; it does not establish that every dependency is safe merely because a tool can resolve it. [1]
The release changes how action references resolve; reviewers still decide whether the locked code is acceptable.
The mechanism matters. An ordinary action tag or branch can move. A locked workflow uses the recorded action commit, with checks on its provenance and repository identity. That makes dependency changes inspectable. The review still has to decide whether the selected action code is appropriate for the workflow's credentials, inputs and responsibilities. [2]
There is a documentation caveat worth keeping with the availability claim. At this observation, the GA announcement lists the broader plans while setup and enforcement pages retain Enterprise Cloud labels. Treat the announcement as the dated release statement and verify the available controls in the target account during a pilot. This article does not infer GitHub Enterprise Server support; the extension explicitly excludes it. [1][3][4][5]
Which repository owns each dependency lock?#
Imagine example-shop/catalog contains a test workflow, a local composite action and a deployment job that calls a reusable workflow in example-platform/workflows. The reusable workflow invokes a third-party publishing action. A lockfile generated in catalog is not a universal lock for everything reached by that deployment call.
The conceptual documentation says the calling lockfile does not pin the reusable-workflow call itself. Pin that call to a reviewed full commit SHA. The called repository owns coverage for action dependencies inside its reusable workflow. If several applications share that workflow, onboarding the shared repository first creates a clearer adoption path than treating each caller as self-contained. [2][4]
| Dependency in the fictional deployment | Relevant control | Evidence to retain |
|---|---|---|
| Remote action in catalog's own workflow | Catalog action lockfile | Locked commit and repository identity |
| Reusable workflow in platform repository | Full commit reference on the call | Reviewed shared-workflow revision |
| Remote action used inside shared workflow | Shared repository's lockfile | Coverage at the called revision |
| Local composite action | Explicit local-action handling | Resolved reference semantics and nested actions |
| Container image or runtime download | Separate digest or integrity control | Reviewed immutable input and update process |
The table separates code resolution from execution context. Even a correctly locked action can download another executable, read an untrusted input or run with excessive token permissions. Review those behaviors in the action and workflow. A dependency lockfile narrows one source of change; it does not make the runner image, secrets or every network response immutable. [2][3]
Local actions deserve explicit attention. A ./ action reference reads the checked-out workspace. The extension does not follow and lock those paths automatically. Its migration option can rewrite them to the same-repository $/ form, which executes at the workflow's commit. That is a semantic change to review, not a cosmetic path normalization. [4]
How should a mixed workflow be onboarded?#
Onboard one workflow and the shared workflow repository it calls before expanding policy scope.
Begin with a dependency inventory for the selected workflow. Identify every remote action, each reusable-workflow call, each local action and each image or download used during execution. Keep the inventory small enough that a reviewer can follow the entire path. In the fictional example, the shared deployment repository is an upstream dependency with its own adoption owner.
Use a disposable branch and an authenticated GitHub CLI in an appropriate test repository. The following commands are documented setup and inspection commands, not commands executed during this research. Review the extension and its supported host before installation. Do not hand-author an actions.lock file to imitate the generator's output. [3][4]
gh extension install github/gh-actions-lock
gh actions-lock .github/workflows/ci.yml
git diff -- .github/workflows/
gh actions-lock --verifyThe generator can change workflow references as well as the lockfile. For example, it can narrow a partial version reference to a specific version without changing the resolved commit. Review the full diff. If the workflow uses a local composite action with remote nested actions, stop and choose supported local-action handling rather than suppressing the error without understanding the resulting coverage. [4]
Migrating ./ references is appropriate only if running the same-repository action at the workflow commit matches the intended behavior. Some workflows deliberately check out a different revision before invoking a local path. The new form can change which action code executes in that case. Preserve the intended source identity and test it; do not migrate paths merely because that makes generation finish. [4]
If the team keeps a local path, document why and how its nested action dependencies receive the required entries for that workflow. GitHub's setup guide describes the relevant workaround and the possibility of failure when the local step is reached. Earlier steps may already have run. A generated lockfile is therefore not a substitute for reviewing the whole job's side effects and its failure point. [4]
Review changed commit and repository-identity fields, regenerate the lockfile and run online verification before merge.
The fictional pilot decision record now has explicit owners: the platform team reviews and locks shared workflow internals; the application team pins the cross-repository call and onboards its own test workflow; both inspect generated changes. Image digests and runtime-download integrity stay visible as separate tasks. This ownership record is the useful deliverable of the pilot, not just the presence of another YAML file.
What should fail the pilot?#
Online verification and offline coverage checks answer different questions. The extension's --verify-local mode does not use the network and checks coverage. Its --verify mode includes provenance checks. Use local checks for quick author feedback and online verification before merge, with enough authenticated access to resolve the dependencies under the intended host. [3]
# Fast local coverage feedback:
gh actions-lock --verify-local
# Online verification for the reviewed dependency state:
gh actions-lock --verifyRehearse adding a remote action without regenerating the file. The authoring check should expose the missing coverage. Rehearse adding a reusable-workflow call and confirm the review asks about the call's pinned revision and the source repository's own lockfile. Passing the caller's coverage check is not an answer about the called repository. [2][3]
Rehearse a moved upstream reference in a dedicated test repository. The documented handling differs for floating branches, partial versions, full version tags and histories where the locked commit is no longer reachable. Do not write an automatic “fix” that always advances the lock. A changed dependency commit is a code-change decision that belongs in a reviewed diff. [3][4]
The extension offers a flag to accept a moved history, and its own documentation says not to use that in automation. Preserve that boundary. An upstream rewrite may be legitimate, but a CI job cannot infer legitimacy from the fact that accepting it makes verification pass. Inspect the upstream history and make the decision explicitly. [3][4]
Test the allowed-actions policy at the same time. Once a workflow is onboarded, GitHub checks the locked commits against allowed actions. A tag-only allowlist entry can stop matching. Adjust the narrow policy entry to the reviewed commit or an intentionally accepted pattern through the organization's normal review, instead of broadly disabling the allowlist to finish migration. [2][4]
Keep resolution tests separate from workload tests#
A successful lock verification establishes a property of dependency resolution. A successful test run establishes something about this workflow's execution under its current inputs. The pilot needs both. Retain the reviewed lockfile diff and the representative run result together, and describe failures at the layer where they occurred.
For the fictional deployment, a read-only test workflow is a better first candidate than a production release job. It can exercise action resolution and nested local handling without introducing deployment side effects. After that path is understood, test the shared deployment workflow in an environment designed for a failed or blocked run. No live pilot result is claimed here.
When is Require lockfile ready to enforce?#
Enforcement depends on workflow coverage, not merely repository participation. GitHub documents that an active Require lockfile policy blocks targeted workflows that are not onboarded, including workflows without action dependencies. A repository where the main CI workflow is locked can still contain an uncovered maintenance or release workflow. Inventory targeted workflows before activation. [5]
For Enterprise Cloud, the enforcement guide describes a scoped Evaluate pilot and Policy insights. Use that evidence to locate missed workflows before moving to Active. Do not assume the same policy modes exist in every plan named by the GA announcement. For another account type, check the actual controls available and use a bounded rollout appropriate to them. [1][5]
Dependabot helps maintain already onboarded dependencies. It does not onboard every newly created workflow. Give new-workflow detection a separate place in the developer workflow: a required verification check, a reviewed generation step or another controlled process that makes missing coverage visible before the workflow becomes operational. The update path also needs an owner when generation fails. [5]
The adoption record should list the workflows in scope, shared repository revisions, local-action decisions, independent image controls, verification coverage and the policy mode actually tested. Record unresolved boundaries as unresolved. A staged policy can be a sound result when a shared dependency still needs work; overstating complete coverage creates a harder problem for the next team.
The release is useful because it makes more action dependency resolution explicit and reviewable. Its value survives a careful rollout. For the fictional repositories, the next action is to finish shared-workflow coverage and inspect the generated dependency changes, then enforce only the workflows whose resolution and execution paths have been demonstrated.
Keep the pilot record with the resulting review, so later dependency updates can repeat the same coverage checks.
Frequently asked questions#
- Does the lockfile pin a reusable-workflow call?
- No. GitHub documents cross-repository jobs.<job_id>.uses calls as outside that lockfile pinning. Pin the call itself to a reviewed full commit SHA. The called repository can maintain its own lockfile for the action dependencies used inside its reusable workflow. [2][3]
- Can verification run without network access?
- The extension has a verify-local mode for offline coverage checks. Its online verify mode also checks provenance. Treat those as different tests: a local coverage pass does not establish that the locked commit remains acceptable to the remote provenance checks. [3]
- Will Dependabot onboard new workflows automatically?
- No. GitHub says Dependabot regenerates matching entries when it updates actions in already onboarded workflows. It does not onboard workflows that have no lockfile entries yet. Maintain a separate process for new-workflow coverage. [5]
- Should Require lockfile immediately target every workflow?
- Run a scoped pilot first. An active policy blocks targeted workflows that are not onboarded, including workflows without uses dependencies. GitHub documents Evaluate mode for Enterprise Cloud; use the controls actually available to your account and confirm coverage before enforcement. [5]
