docs: add Anthropic WIF as a first-class Claude auth option

[Copilot]

auth.mdx incorrectly stated ANTHROPIC_API_KEY is the only Claude auth method. Anthropic WIF (keyless OIDC-based auth via engine.auth.type: github-oidc + provider: anthropic) has been supported since v0.79.6 and was entirely undocumented.

docs/reference/auth.mdx

• "Which secret do I need?" — Claude bullet: replaced "Required / Alternative: None" with two labelled paths: ANTHROPIC_API_KEY (standard) and engine.auth Anthropic WIF (keyless)
• ANTHROPIC_API_KEY section: removed false "only supported method" claim; added forward-link to new WIF section. Statement that CLAUDE_CODE_OAUTH_TOKEN is unsupported is preserved.
• New ### Anthropic Workload Identity Federation (WIF) section: prerequisites, full frontmatter example, field reference table, emitted AWF_AUTH_ANTHROPIC_* env var table, link to Anthropic's GitHub Actions WIF docs, available-since version.

permissions:
  contents: read
  id-token: write

engine:
  id: claude
  auth:
    type: github-oidc
    provider: anthropic
    federation-rule-id: fdrl_xxxxxxxxxxxx
    organization-id: org_xxxxxxxxxxxx
    service-account-id: svac_xxxxxxxxxxxx
    workspace-id: ws_xxxxxxxxxxxx

docs/reference/engines.md

• "Available Coding Agents" table — Claude row: auth column now links to both ANTHROPIC_API_KEY (standard) and the new WIF section (keyless).

[pelikhan]

@copilot validate all env vars with awf specification

[Copilot]

@copilot validate all env vars with awf specification

Validated against pkg/workflow/schemas/awf-config.schema.json. Added missing env vars:

• AWF_AUTH_TYPE (from type: github-oidc)
• AWF_AUTH_OIDC_AUDIENCE (optional, default: https://api.anthropic.com)
• AWF_AUTH_ANTHROPIC_TOKEN_URL (optional, default: https://api.anthropic.com/v1/oauth/token)

All documented env vars now match the AWF specification. Commit: 7a8b9c1

[github-actions]

✅ Test Quality Sentinel completed test quality analysis.

No test files were added or modified in this PR. PR #39241 only modifies documentation files (auth.mdx and engines.md). Test Quality Sentinel skipped.

[github-actions]

✅ Design Decision Gate 🏗️ completed the design decision gate check.

No ADR enforcement needed: PR #39241 does not have the implementation label (has_implementation_label=false) and has 0 new lines of code in business logic directories (default_business_additions=0, threshold=100). Neither enforcement condition is met.

[github-actions]

🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅

[github-actions]

✅ PR Code Quality Reviewer completed the code quality review.

[Copilot]

Pull request overview

Updates the documentation to describe Anthropic Workload Identity Federation (WIF) as a first-class, keyless authentication option for the Claude engine, correcting prior guidance that implied ANTHROPIC_API_KEY was the only supported method.

Changes:

• Updates the Claude authentication guidance in auth.mdx to include a new Anthropic WIF section and cross-links from the ANTHROPIC_API_KEY section.
• Updates the “Available Coding Agents” table to link Claude authentication to both ANTHROPIC_API_KEY and the new WIF section.

Show a summary per file

File	Description
docs/src/content/docs/reference/engines.md	Updates the Claude engine row to reference both standard API key auth and keyless WIF docs.
docs/src/content/docs/reference/auth.mdx	Documents Anthropic WIF configuration and updates Claude auth guidance/cross-links.

Copilot's findings

Tip

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

• Files reviewed: 2/2 changed files
• Comments generated: 5

[github-actions]

REQUEST_CHANGES — one factually wrong version claim, two FAQ entries that directly contradict this PR's stated purpose, and minor consistency issues in the new WIF section.

Blocking issues in faq.md (not in diff — needs a separate fix)

faq.md line 370 — FAQ still declares ANTHROPIC_API_KEY the only supported Claude auth

"No. The Claude engine only supports ANTHROPIC_API_KEY as a GitHub Actions secret."

This PR exists to correct exactly this false claim in auth.mdx, but the identical claim survives untouched in faq.md. Users who read the FAQ will be actively mis-directed. Suggested replacement:

No. The Claude engine does not support `CLAUDE_CODE_OAUTH_TOKEN`. Supported Claude auth methods are [`ANTHROPIC_API_KEY`](/gh-aw/reference/auth/#anthropic_api_key) (standard) and [Anthropic WIF](/gh-aw/reference/auth/#anthropic-workload-identity-federation-wif) (keyless OIDC). Provider-based OAuth (e.g., Claude Teams billing) is not supported.

faq.md line 579 — WIF users have no cost-attribution guidance

"Claude: the Anthropic account tied to the ANTHROPIC_API_KEY secret."

When using WIF there is no ANTHROPIC_API_KEY. The billing identity is the WIF service account/organization. Without updating this line, users who switch to WIF have no idea how costs are attributed.

Non-blocking inline findings (3 comments posted)

• auth.mdx:271 — Available since: v0.79.6 contradicts the blog post that places WIF introduction at v0.77.4 (May 31 2026)
• auth.mdx:216 — Prerequisite says "in the workflow job" but the frontmatter example (and all other auth sections) uses top-level permissions:
• auth.mdx:258 — Env var table mixes key: value inline notation (rows 1–2) with bare key names (rows 3–6)

🔎 Code quality review by PR Code Quality Reviewer · 529.2 AIC · ⌖ 13.6 AIC · ⊞ 16.7K

[github-actions]

Wrong Available since version — contradicts the repo blog post.

The new section claims Available since: v0.79.6 (2026-06-11), but docs/src/content/docs/blog/2026-06-01-weekly-update.md explicitly states WIF was introduced in v0.77.4 (published May 31, 2026) via PR #35939.

💡 Suggested fix

Change to:

Available since: v0.77.4 (2026-05-31).

Or, if v0.79.6 stabilised the Anthropic-specific provider (as opposed to the generic github-oidc type), add a clarifying note:

Available since: v0.77.4 (2026-05-31); Anthropic provider stable since v0.79.6 (2026-06-11).

Either way, the current claim contradicts repo-owned release documentation and will actively mislead users triaging whether their version supports WIF.

[github-actions]

Wrong Available-since version — contradicts the repo blog post. The new section claims v0.79.6 (2026-06-11), but docs/src/content/docs/blog/2026-06-01-weekly-update.md states WIF shipped in v0.77.4 (May 31 2026).

[github-actions]

Inconsistent Field column format: first two rows embed the assigned value, the rest use only the key name.

💡 Details

Rows 1–2 show type: github-oidc and provider: anthropic (key + value inline), while rows 3–6 show bare keys like federation-rule-id. Since type and provider are fixed constants (not user-supplied), the cleanest fix is to drop them from this table entirely — they are already documented in the frontmatter example — and only tabulate the user-configurable mappings. If they must be listed, use a uniform format across all rows.

[github-actions]

"In the workflow job" is inconsistent with the frontmatter example immediately below, which uses top-level permissions.

💡 Suggested fix

The prerequisite says permissions: id-token: write "in the workflow job", but the frontmatter example shows it at the workflow (top) level — which is how gh-aw frontmatter works. Compare the Copilot section which correctly says "Add copilot-requests: write to the permissions: block of your workflow frontmatter."

Change:

- `permissions: id-token: write` in the workflow job

To:

- `id-token: write` in the workflow frontmatter `permissions:` block

[github-actions]

Skills-Based Review 🧠

Applied /grill-with-docs — requesting changes on field name accuracy and docs-vs-implementation alignment.

�� Key Themes & Highlights

Key Issues

• Field name mismatch: The frontmatter example and field table use oidc-audience but the compiler parses audience (engine_config_parser.go line 121). A user copying the example verbatim will silently skip the audience override.
• Unverified env-var emission: token-url → AWF_AUTH_ANTHROPIC_TOKEN_URL is described in the schema but not emitted in engine.go; the optional-fields table should reflect actual compiler behaviour.
• workspace-id cardinality: Schema says "Required when the federation rule covers multiple workspaces" but the table marks it ✅ unconditionally — needs alignment.
• Prerequisites notation: `permissions: id-token: write` looks like a flat YAML key; clearer as `id-token: write` under `permissions:`.

Positive Highlights

• ✅ Excellent initiative to document a previously undocumented but already-shipped feature
• ✅ The env-var mapping tables are a great addition for debugging
• ✅ The Available since: v0.79.6 note is a useful versioning anchor
• ✅ The dual-option update to the engines.md quick-reference table keeps it consistent

🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 406.3 AIC · ⌖ 13.8 AIC · ⊞ 27.9K

[github-actions]

[/grill-with-docs] The code span `permissions: id-token: write` reads as a flat YAML key, but permissions and id-token are separate nested keys — a reader unfamiliar with GitHub Actions OIDC config could write this as-is and get an invalid workflow.

💡 Suggested rewording

-- `permissions: id-token: write` in the workflow job
+- `id-token: write` under `permissions:` in the workflow job

Alternatively, drop this bullet and add a brief forward reference to the Frontmatter code block below, which already shows the correct structure.

[github-actions]

[/grill-with-docs] workspace-id is marked as always required but the compiler schema says "Required when the federation rule covers multiple workspaces" — it may be optional for single-workspace setups.

💡 Suggested fix

From pkg/workflow/schemas/awf-config.schema.json:

"Anthropic workspace ID. Required when the federation rule covers multiple workspaces. Maps to AWF_AUTH_ANTHROPIC_WORKSPACE_ID."

If conditionally required, update the table row to say "Conditional" instead of ✅ and document the exact condition. If always required in practice, correct the schema description to match.