A moving tag is not a review
Your workflow can keep saying uses: vendor/build-action@v3 while the code behind v3 changes. That leaves a gap between the commit your team reviewed and the commit a later workflow run actually executes. Pinning every action by hand to a full commit SHA narrows that gap, but it is easy to miss transitive dependencies and reusable workflow calls.
GitHub Actions workflow dependency lockfiles are now in public preview for Free, Team, and eligible Enterprise Cloud plans. The GitHub CLI extension gh actions-lock generates .github/workflows/actions.lock; GitHub says an onboarded workflow must have its dependencies represented there, and runs use the recorded commits even if a tag or branch moves. The file records direct actions, transitive action dependencies, and reusable-workflow dependencies. GitHub’s October 14 announcement also describes gradual onboarding, stale-lock checks, policy enforcement, and Dependabot updates. The preview is useful for teams whose review process already depends on knowing exactly what automation code will run, but a lockfile does not tell you whether the locked code is trustworthy. GitHub’s announcement explains the current preview scope and behavior.
What the lock changes
A workflow reference such as owner/action@v3 is readable, but a tag is a name that can be moved. A full commit SHA in the workflow pins that one reference directly. The lockfile takes a different approach: your workflow can retain a human-meaningful ref while the generated lock records the exact commit to use. For an onboarded workflow, GitHub requires the needed lock entries and executes the locked commit.
That is most valuable when a workflow uses more than one action or when actions themselves call other actions. The lockfile captures those transitive dependencies too, so your review can see the resolved set rather than relying on each top-level action tag. Reusable workflows need attention as well: a reusable workflow is covered by the lockfile in the repository where it is defined. Locking the caller’s repository does not make a separate reusable-workflow repository’s dependencies disappear from your inventory.
The lockfile is generated by gh actions-lock and should not be edited manually. Its workflow section connects onboarded workflow files to their dependencies; its dependency section records the reference, resolved commit, and repository identity. That gives reviewers a change they can inspect when a ref moves or an action version is deliberately updated.
The lock records which commit a workflow dependency resolves to; it does not assess whether the action is safe.
Adopt it in a small slice first
Do not start by turning on a repository-wide requirement before you know what your workflows depend on. Begin with one workflow that runs on pull requests or deploys a non-production environment. Inventory the uses: references in that file, including reusable workflows, then install the GitHub CLI extension and generate the lockfile using the official getting-started instructions.
Review the generated diff alongside the workflow changes. Confirm that every resolved repository is one you intended to use and that the commit corresponds to the version you meant to adopt. Treat the lockfile as generated source: change the workflow reference or update through the tool, then review the resulting lockfile diff. Avoid hand-editing a commit field to make a check pass. A manually altered lock entry can no longer be trusted to match what the generator resolved.
Onboard workflows gradually. A repository with several pipelines can start with the highest-impact path, such as release or deployment automation, and add other workflows after the team understands the update process. GitHub’s preview requires dependencies for an onboarded workflow to be present in its lockfile. This means onboarding is a meaningful boundary: once a workflow is covered, missing entries should fail visibly rather than falling back to a floating tag.
Start with one workflow, check for stale lock entries, and review dependency updates as code; lockfiles do not replace that review.
Keep the lock current without surprise changes
A lockfile is only useful if the team can tell when it has gone stale. The extension can check whether a lockfile is current without modifying it, which makes that check suitable for CI. Run the check in a lightweight workflow and make its failure actionable: the owner should regenerate the lock, review which references changed, and commit the update with the corresponding workflow change.
Dependabot can keep an onboarded action update and its matching lock entry in the same pull request. That helps avoid a split state where the workflow asks for one version but the lock still resolves another. Still review the update as code. A Dependabot PR tells you what changed; it does not substitute for deciding whether the new action release belongs in your build pipeline.
If you maintain a reusable workflow, keep its lockfile and update process in the repository that defines it. Callers can then consume the reusable workflow without pretending that their own lockfile governs the dependencies inside somebody else’s repository. Document who owns that upstream lock and how callers learn about changes.
Locking is not a security review
The most important limit is also the easiest to blur in a security announcement: a lock makes the executed commit predictable; it does not make that commit safe. It does not assess the action’s code, the maintainer’s practices, the permissions granted to GITHUB_TOKEN, the secrets available to a job, or the trustworthiness of a pull request. If you lock a malicious or vulnerable commit, you have made its execution repeatable, not acceptable.
Keep the rest of your supply-chain controls. Review third-party actions before adoption, grant workflows the smallest permissions they need, keep secrets out of untrusted pull-request contexts, and investigate ownership or repository changes. These measures answer different questions. A lockfile answers “which commit did this workflow execute?” It does not answer “should this code be allowed to run?”
Because the feature is a public preview, check the current GitHub documentation before making it a required repository policy. Start with a low-risk workflow, learn how lock updates appear in pull requests, and only then decide whether to expand onboarding or apply an organization-wide requirement. If the preview changes, your rollout should be small enough that you can adapt without blocking every delivery pipeline.
Where an app template fits
Lockfiles govern GitHub Actions dependencies; they do not create the application those workflows build or deploy. If your team is separately building a SaaS product, OTF’s SaaS Dashboard is an optional editable Vite and Hono application foundation with sign-in, projects, teams, and sample analytics screens. It costs $99 once and includes 12 months of updates. It does not include GitHub Actions workflow lockfiles or configure this feature for your repository. Use it only if an editable app shell is useful alongside your own CI setup.
For another practical way to keep repository automation reviewable, see our guide to building a GitHub App with least-privilege repository creation.
Sources
- GitHub Actions workflow lockfiles in public preview — October 14, 2026. Includes preview availability, lock behavior, gradual onboarding, stale-lock checks, policy enforcement, and Dependabot updates.
Top comments (0)