[docs] auth: Document Copilot fine-grained PAT auth-prefix override and integration-ID fallback

[github-actions]

Summary

• Scan window: 2026-09-01 through 2026-09-03 (UTC)
• Sources reviewed: repository commit history since the scan window (git log), docs/auth-matrix.md, docs/environment.md, docs/authentication-architecture.md, docs/api-proxy-sidecar.md, docs/awf-config-spec.md, docs/github_actions.md, README.md, and the current-main implementation in containers/api-proxy/providers/copilot.js, containers/api-proxy/providers/copilot-auth.js, src/services/api-proxy-env-config.ts, and their associated Jest test files.
• Corrected authentication paths: GitHub Copilot proxy auth-prefix selection for COPILOT_GITHUB_TOKEN, and Copilot-Integration-Id resolution order.
• Current-main vs. pending behavior clarified: confirmed fix: isolate Actions OIDC from agent container #6894 (Actions OIDC isolation) and Ensure HTTP MCP GitHub OIDC bypasses the AWF agent credential boundary gh-aw#50053 (MCP gateway runner-owned OIDC boundary) are both already resolved/merged and already correctly documented as such across docs/environment.md, docs/auth-matrix.md, and docs/authentication-architecture.md — no changes needed there.

Documentation Changes

• docs/auth-matrix.md

  • Added a "Fine-grained PAT override" callout under the Copilot GitHub OAuth Token section: COPILOT_GITHUB_TOKEN values prefixed github_pat_ always use the Bearer auth prefix on every Copilot target (github.com, GHEC, GHES, Business), never falling back to the token <value> prefix that classic PATs/OAuth tokens require on GHEC/GHES/Business targets.
  • Updated the Copilot-Integration-Id description and its attribution-headers table row to include the GITHUB_COPILOT_INTEGRATION_ID fallback (checked only when COPILOT_INTEGRATION_ID is unset).
  • Updated the "Auth Header Prefix Rules" table: relabeled the GHEC/enterprise/business rows as "classic PAT/OAuth" specific, and added a new row for the fine-grained-PAT override, with the accompanying prose updated to match.

• docs/environment.md

  • Extended remediation option 1 in the "Classic PAT + COPILOT_MODEL Incompatibility" section to note that fine-grained PATs now authenticate with a consistent Bearer prefix across all Copilot targets (not just github.com), linking to the updated docs/auth-matrix.md section.

Validation

• Implementation/tests checked: containers/api-proxy/providers/copilot-auth.js (getGitHubTokenAuthPrefix, isGithubCopilotCatalogTarget, isGhecCopilotApiTarget), containers/api-proxy/providers/copilot.js (integration-ID resolution, auth-prefix selection), src/services/api-proxy-env-config.ts (GITHUB_COPILOT_INTEGRATION_ID forwarding), and their test files containers/api-proxy/copilot-auth.test.js, containers/api-proxy/copilot-adapter-enterprise.test.js, src/services/api-proxy-env-config.test.ts — all confirm the shipped behavior on main (merged via PR Fix Copilot proxy auth and GHEC model discovery #8038).
• Markdown/link review: verified backtick pairing, table column alignment, and that all new links (https://github.com/github/gh-aw-firewall/pull/8038) resolve to a real merged PR; no markdownlint tooling was available offline (network-restricted sandbox), so structure was checked manually.
• Credential-leakage diff review: searched the diff for token/key/JWT patterns (ghp_, gho_, sk-, github_pat_<real value>) — only pre-existing placeholder/documentation strings and the generic github_pat_* pattern reference are present; no real credentials were added.

Sources

• Fix Copilot proxy auth and GHEC model discovery #8038 (Fix Copilot proxy auth and GHEC model discovery — merged 2026-09-02)
• fix(api-proxy): correct auth prefix for derived GHEC Copilot targets #6991 (existing, pre-referenced regression fix for GHEC/enterprise/business auth-prefix 400 errors)
• fix: isolate Actions OIDC from agent container #6894 (Actions OIDC isolation — confirmed merged/closed, already documented)
• Ensure HTTP MCP GitHub OIDC bypasses the AWF agent credential boundary gh-aw#50053 (MCP gateway runner-owned OIDC boundary — confirmed resolved by gh-aw#50054, already documented)
• https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api (GitHub REST API authentication reference, unchanged, already cited in docs)

Warning

Firewall blocked 1 domain

The following domain was blocked by the firewall during workflow execution:

• msfeed25.pkgs.visualstudio.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "msfeed25.pkgs.visualstudio.com"

See Network Configuration for more information.

Generated by Auth Doctor Updater · copilot · auto · 133.6 AIC · ⊞ 10.6K · ◷

[Copilot]

🟢 Approval recommended

The documentation accurately reflects the implementation and tests.

Pull request overview

Documents Copilot authentication behavior introduced by PR #8038.

Changes:

• Clarifies fine-grained PATs always use Bearer.
• Documents integration-ID fallback precedence.

File summaries

File	Description
docs/auth-matrix.md	Updates Copilot authentication and integration-ID rules.
docs/environment.md	Expands fine-grained PAT remediation guidance.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 0
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

✅ Copilot review passed with no inline comments.

@github-actions[bot] Add the ready-for-aw label to this PR to trigger agentic CI smoke tests.

[github-actions]

Documentation Preview

Documentation build failed for this PR. View logs.

Built from commit 20d0c89