Enforcing lockfiles for action dependencies

Requiring lockfiles gives you consistent, auditable assurance that every workflow runs vetted code, without asking each team to adopt the practice on its own. For an introduction, see Workflow dependency lockfiles.

This guide helps you run a pilot in selected repositories and set up automations to keep the lockfiles up to date. When you're confident the lockfiles are working as intended and not introducing developer friction, you can enforce the Require lockfile policy.

Prerequisites

Before you enforce workflow lockfiles and create processes to keep them up to date, the lockfile must exist in your repositories. For instructions, see Locking action dependencies in a repository's workflows. You don't need to be an administrator to create a lockfile. Anyone with write access to a repository can do this, so you can delegate onboarding to individual teams before enforcing the policy centrally.

If your workflows call reusable workflows from other repositories, confirm those source repositories are also onboarded. The calling repository's lockfile doesn't cover them. If a called reusable workflow isn't onboarded in its own repository, the Require lockfile policy blocks the calling workflow's run.

1. Pilot the "Require lockfile" policy

The Require lockfile policy blocks runs of targeted workflows that aren't onboarded to the repository's lockfile, including workflows with no uses: dependencies.

Run a pilot before enforcing this policy in all repositories. You should:

• Scope the policy to specific repositories that have onboarded to lockfiles.
• Target specific workflows that have been onboarded to the lockfile, until all workflows are onboarded and you have automated processes to onboard new ones.
• Start with the policy in Evaluate mode and analyze the results under Policy insights.

Require lockfile is a separate policy from Require actions to be pinned to a full-length commit SHA. You can keep both enabled during your rollout. To configure the policy and see how the two interact, see Governing execution of GitHub Actions workflows.

2. Keep lockfiles current

Enforcement only works if lockfiles stay up to date. Add automations so that developers do not need to remember to run the lock command every time they create or edit workflows.

The following sections give examples for how to prevent stale lockfiles at different points of the development lifecycle:

• Keep the file up to date by enabling Dependabot.
• Create a workflow to run the lock command and verify it as part of your pull request requirements.

Dependabot version updates

When Dependabot bumps an action version, it regenerates the matching lockfile entry in the same pull request.

You don't need any configuration beyond having Dependabot manage GitHub Actions dependencies. See Keeping your actions up to date with Dependabot.

Dependabot will not onboard a workflow that has no lockfile entries yet, so this option maintains coverage rather than extending it.

A dedicated workflow or Copilot

When someone adds or edits a workflow, run another workflow that runs the lock command. Trigger the workflow on changes to .github/workflows/** and to any action.yml or action.yaml file, then give it two jobs:

• An update job that regenerates the lockfile on push and commits the result. This job needs contents: write permissions, and your branch protection rules or rulesets must allow GitHub Actions to push to the branches the workflow runs on. Writing to the lockfile requires the workflow OAuth scope, so confirm your tooling has that scope.
• A verify job that runs gh actions-lock --verify on pull requests. This should exit with an error if the lockfile is stale, making it useful for a required check.

For a ready-to-use example workflow, see verify-lockfile.yml in the gh-actions-lock repository. If you use Copilot to edit workflows, you can also set it up to regenerate the lockfile in the same changeset. See the gh-actions-lock skill and Agent skills.

3. Set up a review process for lockfile changes

A lockfile is only a security control if someone reads the diff. A changed commit SHA, specifically, tells you the code your workflows run has changed.

1. Add .github/workflows/actions.lock to your CODEOWNERS file so that the team responsible for build security is automatically requested for review. See About code owners.
2. Configure a branch protection rule or repository ruleset to require approval from a code owner.
3. Tell reviewers what to look for. For guidance, see Locking action dependencies in a repository's workflows.

4. Enforce the policy

When you're confident that lockfiles are in place and will stay up to date, change the enforcement status of the Require lockfile policy to Active. Make sure all onboarded repositories and workflows are targeted.

Leave the verification from step 2 in place. The policy blocks a workflow run that has no valid lockfile. A verification check, by contrast, tells an author their lockfile is stale while they're still working on the pull request.

If a verification check fails, see the gh-actions-lock troubleshooting guide in the gh-actions-lock repository.