📚 Update docs with gh-aw-actions and Dependabot guidance

[dsyme]

Summary

• Added a new "The gh-aw-actions Repository" section to the compilation process reference, explaining how github/gh-aw-actions is used and pinned in compiled .lock.yml files
• Added guidance on suppressing Dependabot PRs for github/gh-aw-actions with a sample dependabot.yml ignore config, in both the compilation process docs and FAQ
• Added two new FAQ entries covering what github/gh-aw-actions is and why Dependabot opens PRs for it

[Copilot]

Pull request overview

Updates the documentation to explain what github/gh-aw-actions is, how it’s referenced during compilation, and how to reduce Dependabot noise related to compiled .lock.yml workflows.

Changes:

• Added a new “The gh-aw-actions Repository” section to the compilation process reference.
• Added guidance (and examples) for suppressing Dependabot PRs related to github/gh-aw-actions.
• Added two new FAQ entries explaining what github/gh-aw-actions is and why Dependabot may open PRs for it.

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 new FAQ entries and a Dependabot ignore snippet for github/gh-aw-actions.
docs/src/content/docs/reference/compilation-process.md	Documents how gh-aw-actions is used during compilation and adds Dependabot suppression guidance.

Comments suppressed due to low confidence (2)

docs/src/content/docs/reference/compilation-process.md:242

• The Dependabot snippet is formatted like a complete .github/dependabot.yml fragment but omits required keys (e.g., version: 2 at the top-level and a schedule: for the github-actions update block). Either include a minimal valid config, or clarify that this is an excerpt to be merged into an existing package-ecosystem: github-actions entry.

```yaml
updates:
  - package-ecosystem: github-actions
    directory: "/"
    ignore:
      # ignore updates to gh-aw-actions, which only appears in auto-generated *.lock.yml
      # files managed by 'gh aw compile' and should not be touched by dependabot
      - dependency-name: "github/gh-aw-actions"

**docs/src/content/docs/reference/faq.md:324**
* The Dependabot YAML example is missing required fields for a standalone Dependabot config (at minimum `version: 2` and a `schedule:` under the update entry). If the intent is to show only the `ignore:` block to add into an existing `github-actions` update entry, consider adjusting the snippet/text to make that explicit so readers don't copy an invalid config.

updates:
  - package-ecosystem: github-actions
    directory: "/"
    ignore:
      # ignore updates to gh-aw-actions, which only appears in auto-generated *.lock.yml
      # files managed by 'gh aw compile' and should not be touched by dependabot
      - dependency-name: "github/gh-aw-actions"

</details>



---

💡 <a href="/github/gh-aw/new/main?filename=.github/instructions/*.instructions.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add Copilot custom instructions</a> for smarter, more guided reviews. <a href="https://docs.github.com/en/copilot/customizing-copilot/adding-repository-custom-instructions-for-github-copilot" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn how to get started</a>.

[Copilot]

The example action reference uses github/gh-aw-actions/actions/setup@... and says compiled .lock.yml pins to commit SHAs, but elsewhere in the repo the action-mode reference format is github/gh-aw-actions/setup@<ref> (no /actions/), with SHA pinning only when resolution succeeds and a version-tag fallback. This section should match the established docs (e.g., docs/src/content/docs/reference/frontmatter.md describes uses: github/gh-aw-actions/setup@sha) and the generated lock files (e.g., .github/workflows/daily-fact.lock.yml uses github/gh-aw-actions/setup@v0).

This issue also appears on line 234 of the same file.

[Copilot]

This answer says compiled .lock.yml files reference github/gh-aw-actions/actions/setup@<sha> and that the references are pinned to commit SHAs. In the current repo/docs, action-mode references are github/gh-aw-actions/setup@<ref> (no /actions/), and SHA pinning is not guaranteed (there is a version-tag fallback; e.g. .github/workflows/daily-fact.lock.yml uses .../setup@v0). Updating this wording and the example to match the established reference format would avoid misleading readers.

This issue also appears on line 316 of the same file.

See below for a potential fix:

The `.github/aw/actions-lock.json` file is a cache of resolved `action@version` → ref mappings. During compilation, the compiler **tries** to pin each action reference 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. In those cases, the compiler may fall back to leaving a stable version tag ref (such as `@v0`) instead of a SHA.

The cache avoids this problem: if a ref (typically 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 action refs (SHAs or version tags) 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.

### What is `github/gh-aw-actions`?

`github/gh-aw-actions` is the GitHub Actions repository containing all reusable actions that power compiled agentic workflows. Compiled `.lock.yml` files reference these actions as `github/gh-aw-actions/setup@<ref>` (where `<ref>` is usually a commit SHA, but may be a stable version tag such as `v0`). These references are managed entirely by `gh aw compile` — never edit them manually. See [The gh-aw-actions Repository](/gh-aw/reference/compilation-process/#the-gh-aw-actions-repository) for details.

[pelikhan]

@copilot review comments

[Copilot]

@copilot review comments

Addressed in commit 2b73ca8:

• Fixed action path format from github/gh-aw-actions/actions/setup@... to github/gh-aw-actions/setup@<ref> in both compilation-process.md and faq.md
• Clarified that SHA pinning is attempted but the compiler may fall back to a stable version tag (e.g., @v0) when SHA resolution fails
• Updated the actions-lock.json FAQ entry to describe it as an action@version → ref (not SHA) mapping, and note the version-tag fallback case