Documentation missing for GH_AW_GITHUB_TOKEN magic secret

[shea-parkes]

Alright, this is me the human writing this paragraph. I think there was a documentation regression in #17990 that caused me a lot of pain over the last couple hours. I'll leave the opus-generated summary below (and I did read it and think it covers it pretty well). I just don't like posting pure GenAI issues without a human-authored frontmatter at this point.

Summary

Recent documentation refactoring (especially PR #17990) has removed specific guidance about the GH_AW_GITHUB_TOKEN magic secret. Users are left without clear instructions about:

• When and why GH_AW_GITHUB_TOKEN is required (especially for tools.github in lockdown mode, safe outputs writing content, etc.)
• What permissions are needed for the PAT used as this secret
• How to create the token for both individual and organization-owned repos
• How it interacts with the fallback chain ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}

Context / Impact

• Workflows compiled by add-wizard and others routinely reference ${{ secrets.GH_AW_GITHUB_TOKEN || secrets.GITHUB_TOKEN }}, but the only documentation left are scattered code comments and snippets in lockdown-mode.md, with no coherent, full description.
• This leaves new users confused about requirements for agentic workflows that WRITE to issues/discussions, especially in public repos with lockdown mode enabled.
• Previous docs in auth.mdx provided detailed guidance; that section was deleted and not fully reincorporated into new dedicated pages.

Recommendation

• Restore comprehensive documentation for GH_AW_GITHUB_TOKEN.
• Include:
  • Clear description of WHEN it's required
  • Step-by-step PAT creation instructions (with links to GitHub's PAT UI)
  • Explicit list of required scopes/permissions for agentic workflows
  • Notes on public vs. private repos, lockdown mode, and fallback logic
  • References to relevant YAML snippets/code to make requirements obvious
• Ideally, the docs should live in auth-projects.mdx, github-tools.md, or a new dedicated page (as appropriate).

Related files / evidence

• Current auth.mdx — no mention of GH_AW_GITHUB_TOKEN
• lockdown-mode.md — only brief examples referencing the secret
• PR 🔐 Refactor auth docs and add GH_AW_CI_TRIGGER_TOKEN magic secret support #17990 — removed old auth guidance
• Compiled workflow YAML routinely references this secret

Tactful ask:
Could maintainers please add back clear documentation for GH_AW_GITHUB_TOKEN and its requirements so new and existing users can correctly configure authentication for writing agentic workflows?