GitHub Actions Lockfiles: Your First Adoption Pull Request

Adopt a GitHub Actions lockfile through one workflow change your team can explain and review. Check which action commits it records, give uncovered inputs their own controls, and assign someone to review future updates. The first useful result is a pull request with clear coverage and a successful run at the reviewed revision.

That sounds modest beside a repository-wide security upgrade. It is also something a small team can finish. A generated file becomes useful when reviewers understand which executable code they have approved and what can still change around it.

GitHub made workflow lockfiles generally available on October 28 for its Free, Team and Enterprise Cloud plans, including Enterprise Cloud with data residency. Hugo van Kemenade’s November 11 walkthrough brought fresh attention to adoption. The question for your team is how to introduce that control without losing sight of the rest of the workflow.

What you approve when you lock a workflow

A workflow lockfile records the action commits an onboarded workflow should execute, including transitive action dependencies. According to GitHub’s concepts reference, the runner enforces that resolution, checks source repository identity, and rejects a recorded commit that is unreachable from its recorded upstream reference.

This gives you a concrete dependency set to approve. An action’s visible reference may be easy to read, but its execution can involve other actions. Recording those dependencies gives reviewers a broader view of the code entering the run.

Approval still requires judgment. The recorded commit could contain code that reads more files, contacts a new service, or uses privileges your workflow should never have granted. A lockfile can faithfully preserve that choice. GitHub’s secure-use guidance therefore remains relevant: review action source, limit token permissions, and handle untrusted pull-request content carefully.

Ask two questions during review: “Will this run use the recorded action code?” and “Should we allow that code to run here?” Locking helps answer the first. The second depends on the code, the triggering event, the runner and the authority available to it.

Make the first pull request small enough to understand

Imagine a four-person startup with a test workflow, a deployment workflow, a shared reusable workflow and a Docker step. This is a hypothetical adoption example. Start with the workflow whose purpose, inputs and expected results an owner can explain. For this team, assume that is the test workflow.

Before generating anything, write its current execution path in the PR description. Name the event that starts it, where checked-out code comes from, what the token can do, which secrets are available and which runner executes it. If outside contributors can trigger it, account for their code as an input. An apparently routine test job can still exercise a sensitive trust boundary.

GitHub’s onboarding guide allows generation to be scoped to one workflow. Use that scope to keep the first change reviewable. Follow the current guide for installation and generation, then inspect both the workflow edits and actions.lock.

Pay particular attention to local actions. A ./ reference uses checked-out workspace contents. Migration to $/ changes the reference to the workflow’s own commit. That can change behavior when the workflow revision and the checked-out revision differ. Review the intended source explicitly before accepting the rewrite; an unresolved local dependency deserves investigation.

Give a teammate enough evidence to decide on your first PR:

1. Scope: the workflow being onboarded and the workflows left for later.
2. Resolution: the generated dependency changes, including transitive actions.
3. Behavior: any local-reference migration or other workflow edit.
4. Validation: the verification method and a successful workflow run at the revision under review.
5. Exceptions: executable inputs the lockfile leaves uncovered, with an owner and a decision for each.

A green test run shows that the observed run completed successfully. Read the relevant job output too: did the intended tests execute, did expected artifacts appear, and did any step start taking a different path? Keep the link to that run beside the diff so the reviewer can inspect both.

Account for inputs outside the lockfile

The lockfile’s boundary matters most where your workflow calls something else. The official CLI README documents limits including external reusable-workflow calls and container images. Your first PR needs a short record of how those inputs are controlled.

Reusable workflows need particular care. GitHub’s concepts reference explains that the caller’s lockfile does not pin calls at jobs.<job_id>.uses. To pin a reusable workflow call, reference its full commit SHA. Action dependencies inside the called workflow belong to that repository’s lockfile. Inspecting the caller’s generated file alone cannot establish coverage inside the called repository.

For the hypothetical startup, the test-workflow PR can use this worksheet. Replace the example responsibilities with actual names before review.

The downloaded-tool row follows from reading what the shell executes. A command can fetch executable bytes beyond the action references recorded in the lockfile. Inspect that path and decide how your team will identify and review the artifact. Treat an unresolved input as an explicit exception requiring a decision.

Also review execution access separately. Runner images, inputs and credentials remain separate from the recorded action resolution. Our agent sandbox access checklist develops that wider question: what can a run read, change and contact? Apply the same question to CI without assuming a dependency file settles it.

Give the next dependency update an owner

The next update turns adoption into a maintenance practice. Write down who reviews lockfile changes, what evidence they expect and how a newly added workflow gets onboarded.

GitHub’s enforcement guidance supports a pilot before broader enforcement. Dependabot maintains entries for onboarded workflows; it does not automatically onboard new ones. Include onboarding in the review checklist for a new workflow, rather than assuming the update bot will discover and complete the task.

Choose verification to match the question. The CLI reference distinguishes offline coverage checking with --verify-local from online provenance checks with --verify. Record which ran and inspect failures before expanding coverage. A successful local coverage check and an online provenance check provide different evidence.

The CLI also documents a limit reviewers should remember: rolling a floating reference back within its history is not detected. Review the actual dependency change even when verification passes. Ask what code changed, whether behavior or required permissions changed, and whether the selected revision is the one you intend to approve.

If your organization uses policy rollout modes, check availability before promising a particular process. GitHub identifies Enterprise Cloud scope for Evaluate mode. A team without that mode can still start with one reviewed workflow and a required verification check.

Expand when the owner can explain the pilot’s coverage, exceptions and update path. Keep the deployment workflow as its own decision, because it has different consequences and may receive different credentials.

Keep verification evidence with a reported CI finding

Routine lockfile adoption belongs in your engineering PR. If the work follows a vulnerability report, keep the finding connected to that PR and its verification evidence. Record what was exposed, what changed, which revision was checked and what remains unresolved.

That is a different task from reconstructing an incident. Our repository-compromise and release-boundary guide explains how to establish whether suspicious source reached a release or consumers. Use it when those questions arise; completing this adoption worksheet cannot establish past exposure.

Kit’s Security workflow can keep a report’s ownership, linked engineering evidence and human verification decision together. Its lifecycle separates resolution from fix verification, and a verifier can add a note. Your engineering team still generates the lockfile, inspects the workflow and decides whether the fix works. Kit does not run that assessment or require documentary proof with every verification.

For your first PR, choose one workflow, review the executable changes, name the uncovered inputs and assign the next update. If a security report prompted the work, put the PR and run references beside that report. Leave your next reviewer enough evidence to understand exactly what the team approved.