docs: document actions-lock.json purpose in FAQ and compilation reference#22869
Merged
docs: document actions-lock.json purpose in FAQ and compilation reference#22869
Conversation
Co-authored-by: dsyme <7204669+dsyme@users.noreply.github.com> Agent-Logs-Url: https://github.com/github/gh-aw/sessions/fbe27ece-3609-4b48-9ff2-d0a9ee03a37b
Copilot
AI
changed the title
[WIP] Update FAQ and compilation documentation for actions-lock.json
docs: document actions-lock.json purpose in FAQ and compilation reference
Mar 25, 2026
dsyme
approved these changes
Mar 25, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
Documents the purpose and expected handling of .github/aw/actions-lock.json so users understand why it exists and why it should be committed.
Changes:
- Adds an FAQ entry explaining what
actions-lock.jsonis, why resolution can fail with restricted tokens (e.g., CCA), and that it should be committed. - Adds a compilation docs subsection describing how the cache stabilizes action SHA pinning across environments and tokens.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/src/content/docs/reference/faq.md | Adds a new FAQ entry describing actions-lock.json, why it exists, and guidance to commit/refresh it. |
| docs/src/content/docs/reference/compilation-process.md | Adds an “actions-lock.json Cache” subsection under Action Pinning explaining the stability rationale and maintenance guidance. |
Comments suppressed due to low confidence (1)
docs/src/content/docs/reference/faq.md:304
gh aw update-actionsdoes not appear to be a valid CLI command in this repo. The documented way to update/refreshactions-lock.jsonis viagh aw update(which callsUpdateActions) orgh aw upgradedepending on intent. Please update this command reference so users can actually run it.
Commit `actions-lock.json` to version control so that all contributors and automated tools (including CCA) use consistent SHA pins without needing to re-resolve them. Refresh the cache periodically with `gh aw update-actions`, or delete it and recompile to force a full re-resolution when you have an appropriate token. See [Action Pinning](/gh-aw/reference/compilation-process/#action-pinning) for details.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+300
to
+304
| The `.github/aw/actions-lock.json` file is a cache of resolved `action@version` → SHA mappings. During compilation, every action reference must be pinned to an immutable commit SHA for security. Resolving a version tag to a SHA requires querying the GitHub API (scanning releases), which can fail when the available token has limited permissions — for example, when compiling via GitHub Copilot Coding Agent (CCA) where the token may not have access to external repositories. | ||
|
|
||
| The cache avoids this problem: if a SHA was previously resolved (using a user PAT or a GitHub Actions token with broader access), the result is stored in `actions-lock.json` and reused on subsequent compilations, regardless of the current token's capabilities. Without this cache, compilation is unstable — it succeeds with a permissive token but fails when token access is restricted. | ||
|
|
||
| Commit `actions-lock.json` to version control so that all contributors and automated tools (including CCA) use consistent SHA pins without needing to re-resolve them. Refresh the cache periodically with `gh aw update-actions`, or delete it and recompile to force a full re-resolution when you have an appropriate token. See [Action Pinning](/gh-aw/reference/compilation-process/#action-pinning) for details. |
There was a problem hiding this comment.
This explanation says SHA resolution requires querying the GitHub API by “scanning releases”, but compilation-time resolution uses the git ref API for tags (e.g. /repos/{owner}/{repo}/git/ref/tags/{tag}) rather than enumerating releases. Consider rewording to match the actual mechanism so readers don’t infer it depends on GitHub Releases being present.
This issue also appears on line 304 of the same file.
Suggested change
| The `.github/aw/actions-lock.json` file is a cache of resolved `action@version` → SHA mappings. During compilation, every action reference must be pinned to an immutable commit SHA for security. Resolving a version tag to a SHA requires querying the GitHub API (scanning releases), which can fail when the available token has limited permissions — for example, when compiling via GitHub Copilot Coding Agent (CCA) where the token may not have access to external repositories. | |
| The cache avoids this problem: if a SHA was previously resolved (using a user PAT or a GitHub Actions token with broader access), the result is stored in `actions-lock.json` and reused on subsequent compilations, regardless of the current token's capabilities. Without this cache, compilation is unstable — it succeeds with a permissive token but fails when token access is restricted. | |
| Commit `actions-lock.json` to version control so that all contributors and automated tools (including CCA) use consistent SHA pins without needing to re-resolve them. Refresh the cache periodically with `gh aw update-actions`, or delete it and recompile to force a full re-resolution when you have an appropriate token. See [Action Pinning](/gh-aw/reference/compilation-process/#action-pinning) for details. | |
| The `.github/aw/actions-lock.json` file is a cache of resolved `action@version` → SHA mappings. During compilation, every action reference must be pinned to an immutable commit SHA for security. Resolving a version tag to a SHA requires querying the GitHub API for the tag's git ref (for example, `/repos/{owner}/{repo}/git/ref/tags/{tag}`), which can fail when the available token has limited permissions — for example, when compiling via GitHub Copilot Coding Agent (CCA) where the token may not have access to external repositories. | |
| The cache avoids this problem: if a SHA was previously resolved (using a user PAT or a GitHub Actions token with broader access), the result is stored in `actions-lock.json` and reused on subsequent compilations, regardless of the current token's capabilities. Without this cache, compilation is unstable — it succeeds with a permissive token but fails when token access is restricted. | |
| Commit `actions-lock.json` to version control so that all contributors and automated tools (including CCA) use consistent SHA pins without needing to re-resolve them via the Git ref API. Refresh the cache periodically with `gh aw update-actions`, or delete it and recompile to force a full re-resolution when you have an appropriate token. See [Action Pinning](/gh-aw/reference/compilation-process/#action-pinning) for details. |
|
|
||
| By caching SHA resolutions from a prior compilation (done with a user PAT or a GitHub Actions token with broader scope), subsequent compilations reuse those SHAs without making API calls. Without the cache, compilation is unstable: it succeeds with a permissive token but fails when token access is restricted. | ||
|
|
||
| **Commit `actions-lock.json` to version control.** This ensures all contributors and automated tools, including CCA, use the same immutable pins. Refresh it periodically with `gh aw update-actions`, or delete it and recompile with an appropriate token to force full re-resolution. |
There was a problem hiding this comment.
gh aw update-actions does not appear to be a valid CLI command in this repo. To refresh/update actions-lock.json, docs elsewhere point to gh aw update (and gh aw upgrade also updates it). Please align this command reference with the actual CLI.
Suggested change
| **Commit `actions-lock.json` to version control.** This ensures all contributors and automated tools, including CCA, use the same immutable pins. Refresh it periodically with `gh aw update-actions`, or delete it and recompile with an appropriate token to force full re-resolution. | |
| **Commit `actions-lock.json` to version control.** This ensures all contributors and automated tools, including CCA, use the same immutable pins. Refresh it periodically with `gh aw update` (or `gh aw upgrade`), or delete it and recompile with an appropriate token to force full re-resolution. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
actions-lock.jsonwas undocumented, leaving users (and CCA) confused about why it exists and whether it should be committed.Changes
reference/faq.md): new entry "What is the actions-lock.json file?" under Configuration & Setup — explains the file as a cache ofaction@version→ SHA mappings, why SHA resolution fails with restricted tokens (e.g. CCA), and that the file must be committed to version controlreference/compilation-process.md): new "The actions-lock.json Cache" subsection under Action Pinning — provides the technical rationale: resolution requires GitHub API access, CCA tokens are commonly too restricted for this, caching prior resolutions eliminates the instability💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.