Playbooks · Coding agents
Lock down agent-built GitHub Actions workflows
Written November 2, 2026
Agents write workflows that pull actions and packages by floating names. Lock the workflow to exact commits and fence downloads before the workflow runs.
Audience: Developer letting an agent write or update Actions workflows · Stack: A GitHub repo with Actions workflows, GitHub CLI installed and authenticated · Tools: GitHub Actions workflow lockfiles, gh actions-lock extension, GitHub package firewall (Enterprise Cloud, npm only)
What changed
Two different controls landed in October 2026, and they are not the same feature. The first is workflow dependency lockfiles, which GitHub made generally available on 28 October 2026 on GitHub Enterprise Cloud, GitHub Enterprise Cloud with data residency, Team, and Free plans, after a public preview that opened on 14 October. A lockfile lets a workflow keep a readable tag or branch reference, such as @v3, while the runner executes the exact commit recorded in the lockfile, even if the reference later moves. The second is the package firewall, which GitHub put into public preview on 20 October 2026 for all GitHub Enterprise Cloud customers, including data-resident Enterprise Cloud. The firewall sits between endpoints and upstream package registries and inspects metadata requests and package downloads. It currently supports npm packages only. Keep the two statuses separate: lockfiles are generally available, the firewall is in preview and subject to change.
The problem both controls address is a floating reference. GitHub's lockfile documentation states it plainly: tags and branches can move, so the code that runs is not guaranteed to be the code the workflow author originally reviewed, and if an upstream maintainer's account is compromised and a tag is repointed, a repository could run malicious code. An agent that writes a workflow from memory or from examples will usually write floating references, because that is how examples are written. Locking the workflow after the agent writes it turns a floating reference into a recorded commit. Fencing package downloads turns a registry request nobody checks into a checked one. Neither control reviews the workflow's logic. Both control what code and packages the workflow is allowed to pull.
Lock the workflow to exact commits
A workflow dependency lockfile lives at .github/workflows/actions.lock in the repository. It is generated by gh actions-lock, a GitHub CLI extension, and the documentation says it should never be edited by hand. The lockfile pins a commit SHA to every action a workflow depends on, including transitive dependencies, the actions used by the actions themselves. It also records the numeric identity of the source repository, owner ID and repo ID, so GitHub Actions can confirm at run time that the repository behind a name is still the one that was locked. The lockfile has two sections: workflows, recording which dependencies each onboarded workflow uses, and dependencies, recording which commit each reference resolves to.
Three boundaries matter. First, a lockfile does not pin calls to reusable workflows from another repository, written as jobs.<job_id>.uses. To pin a reusable workflow, reference it by its full commit SHA; a reusable workflow's own dependencies are covered by the lockfile of the repository where it is defined, not by the lockfile of the repository that calls it. Second, the extension never follows or locks a local path action, uses: ./…, which runs whatever is checked out in the runner's workspace. Third, container images are not locked. A lockfile also does not control other build inputs, such as input parameters, secrets, or the runner image. For repositories that adopt a lockfile, pinning actions to a full-length commit SHA inside the workflow file is no longer necessary, and a lockfile satisfies the separate policy that requires actions to be pinned to a full-length commit SHA, for workflows that are onboarded.
Generate the lockfile with the extension, following GitHub's setup documentation. Install the GitHub CLI, then install the extension with gh extension install github/gh-actions-lock. From the root of the repository, run gh actions-lock to onboard every workflow under .github/workflows/, or pass one workflow path, such as gh actions-lock .github/workflows/ci.yml, to onboard a single workflow. The extension changes more than the lockfile, so review the full diff before committing: it also rewrites workflow uses references to the specific version it resolved, so octo-org/deploy-action@v3 can become octo-org/deploy-action@v3.1.0, more specific without changing the commit it resolves to. The extension's own documentation lists the check modes: gh actions-lock --verify checks that the lockfile is up to date without modifying files, for use in CI; gh actions-lock --verify-local checks coverage offline, without network access, and does not prove provenance; gh actions-lock --no-fix produces a read-only report. To advance a moved branch or partial version to its current upstream commit, run gh actions-lock --relock. GitHub Enterprise Server is not supported by the extension; github.com and Enterprise Cloud with data residency are. When Dependabot opens a version update for an action in an onboarded workflow, it also regenerates the matching lockfile entry in the same pull request, so the workflow file and the lockfile cannot drift apart. Administrators can enforce adoption with the Require lockfile policy, at enterprise, organization, or repository level.
Review lockfile changes the way you review any dependency change. A changed commit is the code the workflow will run. A changed owner ID or repo ID should be rare: it means the repository behind that name is not the one originally locked, so investigate before merging. A change that moves a floating reference back to an older commit in its history is not detected by the extension, so review lockfile diffs rather than trusting the tool alone. Never edit the lockfile by hand; fix the workflow files and regenerate it. If the repository, organization, or enterprise only allows specified actions, check the allowlist before committing: after a workflow is onboarded, the allowlist is checked against locked commit SHAs instead of tags, so an entry pinned to a tag no longer matches.
Fence package downloads
The package firewall is a separate control, at a different layer, with narrower availability. It is in public preview, it is available only to GitHub Enterprise Cloud customers, including data-resident Enterprise Cloud, it is free while in the preview period, and it will be charged on metered usage, similar to Actions billing, when it reaches general availability, per the changelog. It currently supports npm packages only. No other ecosystem is covered in the preview, and no lower plan has access.
GitHub's firewall documentation describes five policy controls, set once at the enterprise level by enterprise administrators or enterprise security managers, applying to all requests that pass through the firewall. The firewall checks the GitHub Advisory Database for active malware advisories and blocks matching packages; that control defaults to On. It checks for vulnerability advisories affecting the requested version, at a severity the enterprise selects, Critical only, High or higher, Medium or higher, or Any severity, defaulting to Critical only. It blocks attestation downgrades, where a requested version lacks the SLSA attestations earlier versions had, defaulting to On. It blocks packages that recently added install scripts, such as preinstall or postinstall scripts, defaulting to On. And it sets a minimum package age, a cooldown blocking versions newer than the configured age, from 1 to 365 days, or 0 to disable it, defaulting to 1 day. The firewall evaluates metadata requests as well as package downloads, because a package manager needs registry metadata before it resolves a version.
Only requests routed through the firewall are checked. Endpoints, developer machines, AI agent sessions, and CI runners, must request packages through the firewall's URL instead of directly from the public registry. The documentation gives the endpoint configuration for npm in the user-level .npmrc file, using the enterprise-specific registry URL https://package-firewall.githubapp.com/npm/enterprises/ENTERPRISE, with an authentication token associated with an enterprise member, needing no more than read-only access to public repositories. A client that still points at the public registry bypasses the firewall entirely, whatever the enterprise policy says. When the firewall blocks a package, the npm output or CI log includes a URL for requesting an exception, with the ecosystem, package name, and version pre-filled; enterprise administrators and security managers review exception requests and can approve one version or a whole package. Approved exceptions are added to the policy and can be reviewed and removed later.
What to do about it
- Read the agent-written workflow before locking it. A lockfile records the commits a workflow resolves to; it does not determine whether a dependency is safe, as the changelog states. Read every
usesreference, every step that runs code, and every secret the workflow touches, and confirm each one is a dependency and a behaviour the team accepts. Locking a workflow you have not read freezes code you have not reviewed. - Generate the lockfile on a branch and review the whole diff. Run
gh actions-lockfor one workflow first, not the whole directory. Read the lockfile entries and the rewrittenusesreferences together. Check that each recorded commit is the version the team intended to lock, and investigate any changed owner or repo ID before merging. Commit the lockfile and the workflow changes together. - Add the stale-lockfile check to CI. Use
gh actions-lock --verifyas a check that runs without modifying files, so a pull request that changes a workflow without updating the lockfile fails visibly. Re-run the extension whenever a workflow gains or loses a dependency, and let Dependabot handle version bumps, which regenerate the matching entry in the same pull request. - Handle local actions and reusable workflows separately. If a workflow uses a local
./…action, the extension reports an error and writes nothing. Migrate the reference withgh actions-lock --migrate-local-actions, which rewrites same-repository references to the pinned$/…form, or pass--ignore-local-actionsand give the workflow lockfile entries for the actions the local action uses, following the documentation. If a workflow calls a reusable workflow in another repository, onboard that repository's lockfile too; the calling repository's lockfile does not cover it. - Decide the firewall question on your plan, not on the feature. If the team is not on GitHub Enterprise Cloud, the firewall is not available, and the lockfile plus reviewing agent-written workflows is the control available today. If the team is on Enterprise Cloud, set the five policy controls at the enterprise level, point each endpoint's npm configuration at the firewall URL, and confirm one endpoint's install actually passes through it before relying on the policy. Check the defaults against the team's tolerance for new versions: a 1-day minimum age blocks a same-day security fix until an exception is approved, so agree who approves exceptions and how fast.
- Keep the two controls separate. The lockfile pins action code; the firewall gates package downloads. An agent-written workflow can have a locked action list and still install a package the firewall never sees in a
runstep, and a fenced package install does not pin the actions the workflow calls. Apply both where both are available, and review the workflow's own steps, including what an agent put in them, under neither control's cover. The agentic workflows playbook covers the safeguards that apply when an agent runs inside a workflow at all.
Limits of this evaluation
- This page is grounded in GitHub's changelogs, documentation, and the extension's documentation. No lockfile was generated against a live repository and no workflow run was observed for this page, so no generated lockfile or observed run is claimed. The commands, modes, and policy controls are stated as the documentation states them.
- The lockfile and the firewall are at different stages: lockfiles are generally available on the plans named above, while the firewall is in public preview for Enterprise Cloud and supports npm only. A plan or ecosystem outside those bounds has neither control in the form described here, and the statuses should be rechecked before a team builds a process on them.
Related playbooks
- Run a reasoning task on a schedule with GitHub Agentic Workflows: one Markdown file, one reviewed pull request
- GitHub Agentic Workflows are now GA
- Start agent workflows from GitHub events with OpenBot
- Secret scanning now catches Actions log leaks
Sources
- https://github.blog/changelog/2026-10-28-github-actions-workflow-lockfiles-are-generally-available/
- https://docs.github.com/actions/concepts/security/workflow-dependency-lockfiles
- https://docs.github.com/en/actions/how-tos/secure-your-work/lock-workflow-dependencies
- https://github.com/github/gh-actions-lock
- https://github.blog/changelog/2026-10-20-github-package-firewall-in-public-preview/
- https://docs.github.com/enterprise-cloud@latest/code-security/how-tos/secure-your-supply-chain/secure-your-dependencies/protecting-endpoints-with-package-firewall
Back to: Coding playbooks hub · Also: Audit a repository's git config before any agent opens it · Open an untrusted repo without running code · Run a reasoning task on a schedule with GitHub Agentic Workflows: one Markdown file, one reviewed pull request