Conversation
…e, CLAUDE_CODE_OAUTH_TOKEN docs, and troubleshooting Agent-Logs-Url: https://github.com/github/gh-aw/sessions/f0876716-b750-4880-b124-1adc7b474341 Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Expands the authentication reference to make engine-specific secrets, custom endpoints, and common auth failures easier to understand and troubleshoot.
Changes:
- Adds a top-of-page quick-reference table mapping engine → required secret (and alternatives).
- Expands engine sections with custom endpoint environment variables and clarifies supported auth methods (notably
CLAUDE_CODE_OAUTH_TOKENis not supported). - Adds a consolidated “Troubleshooting auth errors” section covering common 401/403/400 scenarios.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/reference/auth.mdx | Adds quick secret lookup, engine-specific endpoint/auth notes, and an auth troubleshooting section. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 4
| ## Which secret do I need? | ||
|
|
||
| You will need one of the following GitHub Actions secrets configured in your repository to authenticate the AI engine you choose: | ||
| Configure one GitHub Actions secret per engine before running your first workflow: |
There was a problem hiding this comment.
The wording here can be read as “configure one secret for each engine”, which implies users need to set up all four secrets before their first run. Since a workflow uses only the selected engine:, consider rephrasing to “Configure the GitHub Actions secret for the engine you plan to use…” (or similar) to avoid confusion.
| Configure one GitHub Actions secret per engine before running your first workflow: | |
| Configure the GitHub Actions secret for the engine you plan to use before running your first workflow: |
| **Azure OpenAI and custom endpoints**: | ||
|
|
||
| To use Azure OpenAI or an internal LLM router instead of the default OpenAI endpoint, set `OPENAI_BASE_URL` in `engine.env` and store the corresponding key as a GitHub Actions secret referenced from `engine.env`: | ||
|
|
||
| ```aw wrap |
There was a problem hiding this comment.
This section is titled “Azure OpenAI and custom endpoints”, but the example only changes OPENAI_BASE_URL. For direct Azure OpenAI usage, users typically also need Azure-specific request shaping (deployment path template and api-version query), which is documented elsewhere (e.g., docs/src/content/docs/reference/glossary.md shows an azure-openai provider with request.path-template and request.query.api-version). Consider clarifying that the OPENAI_BASE_URL approach assumes an OpenAI-compatible gateway/router, or add a link/brief note pointing readers to the inline provider configuration required for native Azure OpenAI.
|
|
||
| **`403 "Resource not accessible by personal access token"` (Copilot)** | ||
|
|
||
| The PAT is missing the required permission. Use a fine-grained PAT with **Account permissions → Copilot Requests: Read**. The resource owner must be your personal account, not an organization. See [`COPILOT_GITHUB_TOKEN`](#copilot_github_token) for the setup link. |
There was a problem hiding this comment.
This troubleshooting guidance conflicts with docs/src/content/docs/troubleshooting/common-issues.md (“Copilot GHES: Common Error Messages”), which also documents classic PATs with the copilot scope as an option for this error. Consider either mentioning the classic PAT alternative here as well, or linking directly to the existing troubleshooting entry to keep the guidance consistent.
| The PAT is missing the required permission. Use a fine-grained PAT with **Account permissions → Copilot Requests: Read**. The resource owner must be your personal account, not an organization. See [`COPILOT_GITHUB_TOKEN`](#copilot_github_token) for the setup link. | |
| The PAT is missing the required permission. Use either a fine-grained PAT with **Account permissions → Copilot Requests: Read** (with your personal account as the resource owner, not an organization) or a classic PAT with the `copilot` scope. See [`COPILOT_GITHUB_TOKEN`](#copilot_github_token) for the setup link. |
|
|
||
| **`401 Unauthorized` or `403 Forbidden` (Claude)** | ||
|
|
||
| The `ANTHROPIC_API_KEY` secret is missing, expired, or invalid. Verify the key is active in the [Anthropic Console](https://console.anthropic.com/). Re-set the secret with `gh aw secrets set ANTHROPIC_API_KEY --value "<key>"`. Also check that you have not accidentally set `CLAUDE_CODE_OAUTH_TOKEN` instead — it is not supported. |
There was a problem hiding this comment.
Spelling: “Re-set the secret” is usually written as “Reset the secret”.
| The `ANTHROPIC_API_KEY` secret is missing, expired, or invalid. Verify the key is active in the [Anthropic Console](https://console.anthropic.com/). Re-set the secret with `gh aw secrets set ANTHROPIC_API_KEY --value "<key>"`. Also check that you have not accidentally set `CLAUDE_CODE_OAUTH_TOKEN` instead — it is not supported. | |
| The `ANTHROPIC_API_KEY` secret is missing, expired, or invalid. Verify the key is active in the [Anthropic Console](https://console.anthropic.com/). Reset the secret with `gh aw secrets set ANTHROPIC_API_KEY --value "<key>"`. Also check that you have not accidentally set `CLAUDE_CODE_OAUTH_TOKEN` instead — it is not supported. |
auth.mdxonly documented the API key method per engine with no coverage of OAuth alternatives, custom endpoints, or common auth failures.CLAUDE_CODE_OAUTH_TOKENappeared in user questions but was entirely undocumented.Changes
Quick-reference table — engine → required secret → alternative → notes, at the top of the page so users find the answer immediately
Engine-specific expansions:
GITHUB_COPILOT_BASE_URLfor custom/proxy endpoints; clarifies PAT-only requirement (no GitHub Apps, no OAuth)ANTHROPIC_BASE_URLcustom endpoint guidance; explicitCLAUDE_CODE_OAUTH_TOKENsubsection stating it is not supported andANTHROPIC_API_KEYis the only valid auth methodCODEX_API_KEYruntime fallback precedence; adds Azure OpenAI / custom LLM router example usingOPENAI_BASE_URLwith proper secret referencingTroubleshooting auth errors section — covers
401/403errors for all four engines, Copilot license/inference access failures, and GHES400 Bad Request, each with the direct fix or link to the relevant checklist