Docs: adoption guides for repository and enterprise lockfile rollout by Steve-Glass · Pull Request #136 · github/gh-actions-lock

Steve-Glass · 2026-09-30T22:48:28Z

Public preview proposal

Note

Reusable workflow guidance is under review. Guidance for job-level uses: is intentionally left out of these docs for now. The affected spots carry an inline note and should be revisited once it is settled:

docs/repository-developer-experience.md - "Reusable workflows"
docs/organization-and-enterprise-rollout.md - note under the comparison table
docs/examples/actions-lock-workflow.yml - header comment
docs/examples/actions-lock-SKILL.md - closing guidance

Documents one way to wrap gh actions-lock so nobody has to remember to run it: a Copilot skill for the authoring path and a workflow for the push and pull request path. Adapted from octodemo/actions-security-demo, with corrections found while auditing the claims against the CLI. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Covers the division of labor (Dependabot owns workflow YAML, the CLI owns the lockfile), why --no-onboard means only onboarded workflows are updated, and how Dependabot cooldowns feed the CLI. Documents two things verified against the CLI that are easy to get wrong: cooldown does not gate ref narrowing, because narrowing only considers tags already pointing at the resolved commit; and a fix run reports the pre-fix diagnosis, so valid:false with exit 0 is expected. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Covers the sequence for adopting lockfiles at scale: inventory repositories with workflows, dispatch lockfile pull requests, track them to merge, ship the per-repository automation, then enable the Require lockfile actions policy. Enforcement comes last because the policy blocks workflows in repositories that have no lockfile yet. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Examples used actions/checkout v4 and v5, which are well behind the current v7.0.1. The Dependabot walkthrough now bumps v6.1.0 to v7 with the commits those refs actually resolve to, verified against the CLI. Rename the enterprise rollout guide to cover organizations as well. The sequence is identical at either scope; only repository enumeration and where the policy lives differ. Note that an enterprise has no REST endpoint listing its organizations, so that step is GraphQL. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Remote reusable workflow calls are not pinned. ParseActionRef rejects paths under .github/workflows/, so a job-level `uses: owner/repo/.github/workflows/ x.yml@ref` gets no lockfile entry and --verify still reports valid. The comparison table claimed these were covered, which is wrong in the direction that matters. State the gap in the guide, the skill, and the table. Fix the concurrency caveat: verify does not run on push, so the two jobs only overlap when the branch has an open pull request. Note that the bot commit makes the next push non-fast-forward. Show `gh extension install --pin <tag>`, since the update job rewrites source files and preview releases can change that behavior. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

The previous wording said remote reusable workflows are simply not pinned. That understates it. The lockfile format covers job-level uses: and the Actions runtime enforces it; the CLI is the piece that does not read it yet (github#129). Reproduced against v0.1.6 and current HEAD: a required entry is reported as stale, and a fix run deletes it while reporting the workflow valid. The example automation commits whatever the fix run produces, so it would commit that deletion and the next run can fail to start. Say so in the guide, the skill, the rollout table, and at the top of the example workflow, and tell repositories that call remote reusable workflows to run verify-only until github#129 is fixed. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

A lockfile stops at the repository edge. The actions a reusable workflow runs resolve in the callee repository against its own lockfile, so calling one means trusting that repository to have locked its dependencies. What the caller controls is which commit of the callee it gets, which is what makes the callee's locking meaningful in the first place. Say that before describing the CLI gap, so the gap reads as breaking the anchor of the chain rather than an isolated missing entry. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

github#129 is not yet triaged, so flag the sections that depend on it rather than presenting the behavior as settled. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Remove the specific claims about job-level uses: handling and note that the guidance is under review instead. Keep the conservative recommendation to run verify-only automation in repositories that call remote reusable workflows. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

The rollout guide described dispatching agents but left the scripted path as a placeholder comment, which undersold what is possible today. Both the locking wave and the automation wave can be driven programmatically across every repository you own. Fill in both loops. Tested the locking loop end to end against a local remote: it locks, stages the lockfile and the rewritten workflow YAML, and the staged-diff check makes it safe to re-run over a list that is partly done. Note the workflow OAuth scope requirement on the second wave, since pushing a branch that touches .github/workflows/ is rejected without it. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Pushing a branch that adds files under .github/workflows/ fails without the workflow OAuth scope, and an environment GH_TOKEN silently overrides the logged-in account. Hitting that on the first repository of a long list is a waste of a run, so check once up front and fail with the fix. Tokens that report no classic scopes are fine-grained or app tokens, which the check passes through rather than guessing at. Verified against all three cases. Also drop the duplicate preview notice. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

The rule was stated in the repository guide and the skill but missing from the Dependabot and rollout guides, both of which tell a reader to review a lockfile diff without saying what to do when it looks wrong. Add it at each of those points, tell the at-scale agent prompt never to write one, and rename the "Editing by hand" heading, which described editing workflows but sat next to lockfile guidance. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

The rollout guide only described enterprise and organization policies, which left out repository level entirely and gave no navigation path for the organization case. Replace the prose with a table of the three levels and where each lives, and a second table showing which targeting fields appear at each. Repository level also gives a pilot path: one team can enforce on their own repository before anything is required more broadly. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Enforcing at a level above the repository affects repositories that had no say in the timing, so turning the policy on before they have lockfiles blocks their workflow runs. Merged pull requests are not the same as coverage, so give the per-repository check as the actual gate. Repository-level policy is the exception and says so: it only affects the repository that opted in. Also make the repository guide explicit that two of the three pieces are files you add and the third is generated. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

nebuk89

A few catches and then mainly it has, at least to me, a few Ai heavy 'intro phrases and titles' which would be good to strip back

nebuk89 · 2026-10-02T11:53:18Z

@@ -0,0 +1,379 @@
+# Rolling out lockfiles across an organization or enterprise


Should we put these into a repo as well under the Actions org?

Explain manual-edit risks, document common findings and remediation, and clarify when an unsupported local action should defer workflow onboarding. Simplify introductions and headings in response to review. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

nodeselector · 2026-10-02T17:29:47Z

+lockfile. Use the finding's detail and remediation to identify the next step;
+do not delete lockfile entries or accept moved pins just to make a check pass.


At this point, escalate it to the human. AI can suggest a path forward, but this is a human decision IMO.

nodeselector · 2026-10-02T17:30:47Z

+For `local path actions are not yet supported`, check that each `./…` path
+resolves from the repository root to an `action.yml` or `action.yaml`. Fix an
+incorrect path and re-run the CLI. If the action is generated, checked out from
+another repository, or otherwise unavailable for inspection, defer onboarding
+that workflow and report the limitation. Other workflows can still be locked.
+If the affected workflow is already onboarded, report the blocking finding
+rather than removing its lockfile entry.


We can use this skill to attempt to migrate to $/.

nodeselector · 2026-10-02T17:33:26Z

+    if: github.event_name == 'push' && github.ref_type == 'branch'
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write


This isn't the same as the workflow scope permission. And the workflow scope permission is not one that we'll issue to a job. The options there are a PAT with the workflow scope, or to just have this be CI that doesn't auto-fix things for you, and just blocks bad changes from merging.

nodeselector · 2026-10-02T17:34:32Z

+## Onboarding
+
+Dependabot invokes the CLI with `--no-onboard`, which refuses to add lockfile
+entries for workflows or actions that do not already have them. A dependency


Suggested change

entries for workflows or actions that do not already have them. A dependency

entries for workflows that do not already have them. A dependency

nodeselector · 2026-10-02T17:35:32Z

+Dependabot invokes the CLI with `--no-onboard`, which refuses to add lockfile
+entries for workflows or actions that do not already have them. A dependency
+Dependabot bumps in a workflow you never locked produces a non-blocking
+`onboarding-required` finding and no lockfile write:


This isn't surfaced to the user from the Dependabot flow. Silently skipped. The user would see this if they inspected output locally.

nodeselector · 2026-10-02T17:37:35Z

+         repo_id: 197814629
+```
+
+Review the changed commit SHA the way you would review any dependency change. A


repo_id move suggests a transfer, owner_id change suggests namespace squatting attack. The CLI isn't aware of the transfers being okay yet. There's a draft PR that I'm getting to for that here #118 but owner_id change will raise a message to the operator as this is really something that should not happen ever. This will also continue to fail at runtime, whereas repo transfers will not fail.

nodeselector · 2026-10-02T17:39:18Z

+## Rollout sequence
+
+Actions policies are generally available, and one of the workflow execution
+protections they can apply is **Require lockfile**, which requires workflows to


Including reusable/required workflows in other repos, fwiw.

Steve-Glass and others added 15 commits September 30, 2026 18:12

Docs: say public preview and drop editorializing

7641e52

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Docs: mark the reusable workflow guidance as under review

2466833

github#129 is not yet triaged, so flag the sections that depend on it rather than presenting the behavior as settled. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

nebuk89 suggested changes Oct 2, 2026

View reviewed changes

nodeselector reviewed Oct 2, 2026

View reviewed changes

Steve-Glass closed this Oct 5, 2026

Navigation Menu

Repository navigation

Docs: adoption guides for repository and enterprise lockfile rollout - #136

Docs: adoption guides for repository and enterprise lockfile rollout#136
Steve-Glass wants to merge 16 commits into
github:mainfrom
Steve-Glass:steve-glass-actions-lock-dx-docs

Steve-Glass commented Sep 30, 2026 •

edited

Loading

Uh oh!

nebuk89 left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nebuk89 Oct 2, 2026

Uh oh!

Uh oh!

nodeselector Oct 2, 2026

Uh oh!

nodeselector Oct 2, 2026

Uh oh!

nodeselector Oct 2, 2026

Uh oh!

nodeselector Oct 2, 2026

Uh oh!

nodeselector Oct 2, 2026

Uh oh!

nodeselector Oct 2, 2026

Uh oh!

nodeselector Oct 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		@@ -0,0 +1,379 @@
		# Rolling out lockfiles across an organization or enterprise

		lockfile. Use the finding's detail and remediation to identify the next step;
		do not delete lockfile entries or accept moved pins just to make a check pass.

	entries for workflows or actions that do not already have them. A dependency
	entries for workflows that do not already have them. A dependency

Conversation

Steve-Glass commented Sep 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nebuk89 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Steve-Glass commented Sep 30, 2026 •

edited

Loading