docs: add consolidated token reference page

[lpcox]

Adds a new Token Reference page (docs/src/content/docs/reference/tokens.md) that consolidates documentation for all tokens and secrets used by GitHub Agentic Workflows.

What's included

• Quick reference table — all tokens at a glance with purpose, required status, and fallback chains
• AI Engine Tokens — COPILOT_GITHUB_TOKEN, ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY
• GitHub API Tokens — GH_AW_GITHUB_MCP_SERVER_TOKEN (magic secret), GH_AW_GITHUB_TOKEN, GITHUB_TOKEN
• Purpose-Specific Tokens — GH_AW_AGENT_TOKEN, GH_AW_PROJECT_GITHUB_TOKEN, GH_AW_CI_TRIGGER_TOKEN, GH_AW_PLUGINS_TOKEN
• GitHub App Tokens — configuration, mint step locations, App vs PAT precedence
• Internal Runtime Tokens — GITHUB_MCP_SERVER_TOKEN, GITHUB_PERSONAL_ACCESS_TOKEN, GH_TOKEN
• Token Precedence Chains — exact resolution order for each operation context (MCP server, safe outputs, Copilot, agent assignment, Projects, CI trigger, APM)
• Tokens that don't fall back to GITHUB_TOKEN — explains why three tokens intentionally have no fallback

Changes

• New file: docs/src/content/docs/reference/tokens.md
• Updated sidebar: docs/astro.config.mjs (added Token Reference entry)
• Updated cross-refs: docs/src/content/docs/reference/auth.mdx (linked to new page)

[Copilot]

Pull request overview

Adds a new consolidated Token Reference documentation page for GitHub Agentic Workflows, plus navigation and cross-reference updates so it’s discoverable from existing auth docs and the sidebar.

Changes:

• Add Token Reference page documenting token purposes, precedence chains, and GitHub App vs PAT behavior
• Link to the new page from the existing Authentication reference
• Add the page to the docs sidebar navigation

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
docs/src/content/docs/reference/tokens.md	New consolidated reference page for all tokens/secrets, including precedence chains and GitHub App behavior
docs/src/content/docs/reference/auth.mdx	Adds a related-docs link to the new Token Reference page
docs/astro.config.mjs	Adds “Token Reference” entry to the Reference sidebar

Comments suppressed due to low confidence (3)

docs/src/content/docs/reference/tokens.md:455

• The statement that missing COPILOT_GITHUB_TOKEN will cause runtime failure isn’t always true: when the copilot-requests feature flag is enabled, the Copilot engine uses ${{ github.token }} instead of secrets.COPILOT_GITHUB_TOKEN. Suggest updating this paragraph (or the table row for COPILOT_GITHUB_TOKEN) to note the feature-flag exception while keeping the “no fallback” behavior for the default mode.

If these secrets are not configured and no custom `github-token` is provided, the relevant workflow steps will fail at runtime.

docs/src/content/docs/reference/tokens.md:84

• The OPENAI_API_KEY section lists fallback as CODEX_API_KEY, but the compiler uses ${{ secrets.CODEX_API_KEY || secrets.OPENAI_API_KEY }} for Codex authentication (so CODEX_API_KEY wins when both are present). Consider documenting the fallback as CODEX_API_KEY → OPENAI_API_KEY (and optionally noting both names are accepted).

| **Source** | OpenAI API key stored as repository secret |
| **Required** | Yes, when using `engine: codex` |
| **Permissions** | OpenAI API access (external service) |
| **Fallback** | `CODEX_API_KEY` (alternative secret name) |
| **Used by** | Codex inference step |

docs/src/content/docs/reference/tokens.md:317

• This section states that GitHub App tokens “override all PAT-based tokens” / “always take precedence”, but assign-to-agent safe outputs intentionally do not use GitHub App installation tokens (the Copilot assignment API rejects them) and instead fall back to GH_AW_AGENT_TOKEN → GH_AW_GITHUB_TOKEN → GITHUB_TOKEN or an explicit github-token. Please call out this exception here (similar to the existing note for COPILOT_GITHUB_TOKEN).

- **Override all PAT-based tokens** — when configured, App tokens take highest precedence
- **Are scoped to the job's `permissions:` block** — the token receives only the permissions declared in your workflow
- **Are automatically revoked** at the end of the workflow run (even on failure)
- **Support repository scoping** — limit access to specific repositories for least privilege

### Where App tokens are minted

The compiler generates App token mint steps in multiple locations depending on what features your workflow uses:

| Location | Step ID | Used For |
|---|---|---|
| Pre-activation job | `pre-activation-app-token` | Membership checks, skip-if evaluations |
| Agent job (GitHub MCP) | `github-mcp-app-token` | GitHub MCP server authentication |
| Safe outputs job | `safe-outputs-app-token` | Write operations (issues, PRs, comments) |
| APM dependencies | `apm-app-token` | Plugin and dependency access |

Each mint step includes `github-api-url: ${{ github.api_url }}` for [GitHub Enterprise compatibility](/gh-aw/troubleshooting/debug-ghe/).

### App token vs PAT precedence

When a GitHub App is configured, it always takes precedence:

GitHub App token (highest priority)
└── Custom github-token field
└── Purpose-specific secret (e.g., GH_AW_GITHUB_MCP_SERVER_TOKEN)
└── GH_AW_GITHUB_TOKEN
└── GITHUB_TOKEN (lowest priority)

> [!NOTE]
> `COPILOT_GITHUB_TOKEN` is the one token that **cannot** use a GitHub App. It must be a fine-grained PAT with Copilot Requests permission on a personal account.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

In the quick reference table, the Codex token fallback is shown as OPENAI_API_KEY → CODEX_API_KEY, but the compiler resolves Codex auth using ${{ secrets.CODEX_API_KEY || secrets.OPENAI_API_KEY }} (i.e., CODEX_API_KEY takes precedence when both are set). Please update the table to match the actual resolution order (or align the implementation if the docs are intended).

This issue also appears in the following locations of the same file:

• line 80
• line 286
• line 454

Suggested change

	| [`OPENAI_API_KEY`](#openai_api_key) | Codex engine authentication | Yes (Codex engine) | `CODEX_API_KEY` |
	| [`OPENAI_API_KEY`](#openai_api_key) | Codex engine authentication | Yes (Codex engine) | `CODEX_API_KEY` → `OPENAI_API_KEY` |

[pelikhan]

wait we already have a tokens page

[pelikhan]

let's check that we don't have the same page

[lpcox]

@pelikhan i asked the agent if there was a comprehensive token guide and it said that there wasn't.

[lpcox]

@pelikhan if you search 'token' in the docs a bunch of stuff comes but nothing comprehensive.

[github-actions]

Contribution Check Feedback

Thanks for the documentation PR, @lpcox! The overall structure looks great — the page is well-organized and covers the right scope. A couple of things to address before this is ready to merge:

Open review question 🔍

There's an active CHANGES_REQUESTED review from @pelikhan asking whether a token reference page already exists and how this overlaps with auth.mdx. It would help to clarify (or resolve) that overlap to avoid long-term content drift. Worth checking whether the new page supersedes content in auth.mdx or whether they can coexist cleanly.

Technical accuracy items ✍️

The automated Copilot review flagged three issues worth addressing:

1. CODEX vs OPENAI precedence — the page currently reverses the correct precedence order for these two environment variables.
2. COPILOT_GITHUB_TOKEN feature-flag exception — the token behavior when the MCP Gateway feature flag is enabled isn't captured; this case needs a note or table row.
3. GitHub App token precedence for assign-to-agent — the page describes GitHub App tokens as always taking precedence, but that's only true in specific routing scenarios.

Once these are resolved, this should be ready for a final review pass. Looking forward to seeing this land! 🚀

---

This feedback was generated by the automated Contribution Check workflow.

Generated by Contribution Check · ◷

[pelikhan]

@copilot review the auth page

[Copilot]

@copilot review the auth page

Reviewed auth.mdx (bdacf9b). The page is accurate and serves its purpose well as a task-oriented setup guide. A few observations:

• No duplication with tokens.md: auth.mdx focuses on how to set up authentication (step-by-step PAT creation, CLI commands, GitHub App config), while tokens.md is a reference covering permissions, fallback chains, and all token types in one place — complementary, not overlapping.
• One minor gap: The OPENAI_API_KEY section doesn't mention that CODEX_API_KEY is also accepted and takes precedence. This doesn't affect users (OPENAI_API_KEY works correctly) but users who want the canonical secret name aren't told about it. The tokens.md reference page now documents this accurately.
• GitHub App section: Complete and accurate, including the safe-outputs App token configuration.
• Links: The Related Documentation footer correctly points to tokens.md and other relevant pages.

No changes needed on auth.mdx — it's correct as-is.

[pelikhan]

@dsyme you do a bunch of edits around tokens back in the shipping days... didn't we have a tokens page?