Before onboarding a GitHub Actions workflow to dependency locking, review the workflow changes and generated lockfile together. Record which commits will execute, who owns dependencies inside reusable workflows, and what evidence supports the change. A lockfile records exact dependency commits and source repository identities; it is not a certificate that the dependency is safe.
GitHub announced workflow dependency lockfiles in public preview on October 14, 2026. The practical opportunity is a reviewable dependency record, not a reason to approve a large generated diff on sight. This guide supplies a proposed PR worksheet and pilot checks, not results from a deployment we performed. GitHub's announcement describes the preview and explicitly separates locking from evaluating code safety.
Draw the boundary before generating the file
Pick one workflow and name it in the PR. Write down which other workflows remain outside the pilot. GitHub's conceptual documentation describes per-workflow adoption and the generated .github/workflows/actions.lock file. Do not describe a one-workflow pilot as repository-wide protection.
The important boundary is a reusable workflow call. The caller's lockfile does not cover the dependencies inside that reusable workflow; its defining repository owns those entries. Put that repository and its coverage evidence in the review record. “The caller is locked” and “the called workflow's internals are locked” are two different statements.
Make an inventory before changing anything:
- Selected workflow paths and their owner.
- Direct remote actions and newly discovered transitive actions.
- Reusable workflow calls, their defining repositories and the person who can answer coverage questions.
- Other execution inputs that need separate review, such as downloads in shell steps. Do not assume an action lockfile freezes everything a job obtains at runtime.
Review the complete generated diff
Use the official setup instructions for installation and generation. Their one-workflow example is gh actions-lock .github/workflows/ci.yml; substitute the actual selected path. Generate in a review branch, not as an unexamined production edit. Do not hand-edit the generated lockfile.
Onboarding can change more than the new file. Current instructions describe narrowing partial version references and rewriting valid same-repository ./ action references to $/, including action definitions. Review those changes alongside the pins. A surprisingly small lockfile does not mean the workflow diff is unimportant.
For each changed dependency, classify the change before approving it:
| Change you see | Question to answer | Evidence to retain |
|---|---|---|
| A commit recorded for the first time | Does this preserve the intended executable code, or introduce a different revision? | Old resolution if known, proposed commit and upstream comparison. |
| An existing commit replaced | What behavior changed, and why is this update wanted? | Relevant release or code-review link and reviewer conclusion. |
| Source identity or dependency graph changes | Why is a different repository identity or new nested action involved? | Explanation from the owner, not just a green check. |
| Workflow or local-action text changes | Is this an expected migration or an unrelated edit? | File-by-file explanation and selected pilot run. |
If the previous resolution was never recorded, say “unknown.” Do not manufacture an old SHA to make the comparison look complete. Ask the owner whether the remaining evidence is enough to proceed.
Copy this PR evidence worksheet
This is our suggested review form, not a GitHub-required schema. Keep one dependency row per distinct change, plus a short summary for the whole PR.
- Scope: Selected workflow paths; explicitly excluded paths; review owner.
- Dependency: Reference; previous commit or unknown; proposed commit; upstream comparison link.
- Reason: What task requires this change? What did the reviewer inspect?
- Boundary: New transitive actions; reusable-workflow defining repository; evidence for its internal coverage or a named unresolved question.
- Migration: Changed workflow and action-definition files; explanation of each unexpected edit.
- Policy: Applicable allowed-action rule; evidence the locked commit still fits the intended scope.
- Verification: Extension version; exact selected paths and command; observed result; pilot run URL and actual outcome.
- Decision: Approve, request evidence or defer; next dependency-update owner.
For a fictional example, a documentation workflow calls a shared build workflow in another repository. The caller's PR can record its own locked reference, but the reviewer still writes “shared workflow internal coverage: awaiting owner evidence” rather than marking the entire chain complete. That is a useful handoff, not a failed form.
Check the failure cases in a disposable pilot
These are proposed checks, not executed test results. Record actual outcomes beside the expectation. The version-specific expectations below refer to gh-actions-lock v0.2.0, released October 12, 2026, which tightened verification for unused entries and missing workflow coverage. Recheck behavior when the extension changes.
| Pilot case | What to inspect | Next step |
|---|---|---|
| Baseline | Generate for the chosen workflow, then verify the same selected scope. Keep the complete diff and result. | Investigate discrepancies before introducing a deliberate failure. |
| New remote reference without regeneration | Confirm verification rejects missing dependency coverage. | Regenerate, review the added dependency, then verify again. |
| Removed use with an old entry left behind | Confirm stale coverage is detected under the checked version. | Regenerate rather than editing lockfile text by hand. |
| Reusable workflow call | Find separate evidence for dependencies inside the defining repository. | Leave that boundary explicitly unresolved if evidence is unavailable. |
Keep generation and verification scope aligned. A check across the entire workflows directory may correctly complain about workflows deliberately excluded from your first pilot. Record the actual command instead of reducing all outcomes to “the lockfile passed.” The versioned CLI README distinguishes online verification from offline local verification; the latter is not a check of current upstream state.
Do not fix a policy mismatch by widening access
There is a migration detail worth checking before the pilot run: GitHub's repository Actions settings documentation says locked dependencies are evaluated against their locked SHA for allowed-action policies. A tag-specific allowance can therefore stop matching.
Write down the intended permission boundary and ask its owner to review the matching rule. “Allow everything so the pilot runs” changes a different decision from dependency locking. Do not bury that change in the onboarding PR or treat a successful run after broadening the policy as evidence that the original boundary still holds.
Close with two conclusions, not one badge
Finish the PR with a dependency-review conclusion and an operational conclusion. For example: “The listed commits and migration edits have been reviewed; the selected workflow completed at this run URL.” If either statement is unsupported, keep it pending and name the missing evidence.
Choose who will review the next generated change. For longer-lived releases, our release evidence handoff guide explains how to preserve the observed run information before it becomes unavailable. A locked file is a useful record. The useful review is the explanation someone can still follow later.