Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 4 commits into from
Jun 14, 2026
+72 −5
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3820662
Initial plan
Copilot Jun 14, 2026
a618499
docs: document Anthropic WIF authentication for Claude engine
Copilot Jun 14, 2026
8dd52cc
docs: remove internal implementation note from Anthropic WIF section
Copilot Jun 14, 2026
1638791
docs: complete Anthropic WIF env var table per AWF spec
Copilot Jun 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 71 additions & 4 deletions docs/src/content/docs/reference/auth.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,8 @@ Configure one GitHub Actions secret per engine before running your first workflo

### Claude

- **Required secret:** [`ANTHROPIC_API_KEY`](#anthropic_api_key)
- **Alternative:** None
- **Notes:** API key from Anthropic Console
- **Standard:** [`ANTHROPIC_API_KEY`](#anthropic_api_key) — static API key from Anthropic Console
- **Keyless alternative:** [`engine.auth` Anthropic WIF](#anthropic-workload-identity-federation-wif) — short-lived OIDC token via federation rule; no long-lived secret on the repo

### Codex

Expand Down Expand Up @@ -199,12 +198,80 @@ To route Claude through a custom Anthropic-compatible endpoint (e.g., an interna

**`CLAUDE_CODE_OAUTH_TOKEN`**:

`CLAUDE_CODE_OAUTH_TOKEN` is not supported by GitHub Agentic Workflows. The only supported authentication method for the Claude engine is `ANTHROPIC_API_KEY`. Provider-based OAuth authentication (such as billing through a Claude Teams or Claude Max subscription) is not supported. If you have set `CLAUDE_CODE_OAUTH_TOKEN` as a repository secret, it will be ignored — configure `ANTHROPIC_API_KEY` instead.
`CLAUDE_CODE_OAUTH_TOKEN` is not supported by GitHub Agentic Workflows. Provider-based OAuth authentication (such as billing through a Claude Teams or Claude Max subscription) is not supported. If you have set `CLAUDE_CODE_OAUTH_TOKEN` as a repository secret, it will be ignored — configure `ANTHROPIC_API_KEY` instead. For keyless authentication via Workload Identity Federation, see [Anthropic WIF](#anthropic-workload-identity-federation-wif) below.

See also [AI Engines](/gh-aw/reference/engines/#available-coding-agents) for additional configuration needed when using Claude with GitHub MCP.

---

### Anthropic Workload Identity Federation (WIF)

Workload Identity Federation lets workflows authenticate with Anthropic using short-lived
GitHub OIDC tokens instead of a long-lived `ANTHROPIC_API_KEY` secret. When WIF is active,
the compiler suppresses the static-key requirement and emits `AWF_AUTH_ANTHROPIC_*` environment
variables consumed by the AWF firewall api-proxy sidecar.

**Prerequisites:**
- An Anthropic federation rule configured in your Anthropic workspace (obtain the IDs from your [Anthropic Console](https://platform.claude.com/docs/en/manage-claude/wif-providers/github-actions))
- `permissions: id-token: write` in the workflow job

@github-actions github-actions Bot Jun 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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 github-actions Bot Jun 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[/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.


**Frontmatter:**

```yaml wrap
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
# Optional: override OIDC audience claim (default: https://api.anthropic.com)
# oidc-audience: https://api.anthropic.com
# Optional: override token exchange endpoint (default: https://api.anthropic.com/v1/oauth/token)
# token-url: https://api.anthropic.com/v1/oauth/token
Comment on lines +234 to +237
```

**Fields:**

| Field | Required | Description |
|---|---|---|
| `federation-rule-id` | ✅ | ID of the Anthropic WIF federation rule (prefix `fdrl_`) |
| `organization-id` | ✅ | Anthropic organization ID (prefix `org_`) |
| `service-account-id` | ✅ | Anthropic service account ID (prefix `svac_`) |
| `workspace-id` | ✅ | Anthropic workspace ID (prefix `ws_`) |

@github-actions github-actions Bot Jun 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[/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.

| `oidc-audience` | Optional | Audience claim for GitHub OIDC token (default: `https://api.anthropic.com`) |
| `token-url` | Optional | Token exchange endpoint override (default: `https://api.anthropic.com/v1/oauth/token`) |
Comment on lines +248 to +249

**Emitted environment variables:**

The compiler maps each field to an env var passed to the AWF api-proxy sidecar:

| Field | Env var |
|---|---|
| `type: github-oidc` | `AWF_AUTH_TYPE=github-oidc` |
| `provider: anthropic` | `AWF_AUTH_PROVIDER=anthropic` |

@github-actions github-actions Bot Jun 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

| `federation-rule-id` | `AWF_AUTH_ANTHROPIC_FEDERATION_RULE_ID` |
| `organization-id` | `AWF_AUTH_ANTHROPIC_ORGANIZATION_ID` |
| `service-account-id` | `AWF_AUTH_ANTHROPIC_SERVICE_ACCOUNT_ID` |
| `workspace-id` | `AWF_AUTH_ANTHROPIC_WORKSPACE_ID` |

Optional fields:

| Field | Env var | Default |
|---|---|---|
| `oidc-audience` | `AWF_AUTH_OIDC_AUDIENCE` | `https://api.anthropic.com` |
| `token-url` | `AWF_AUTH_ANTHROPIC_TOKEN_URL` | `https://api.anthropic.com/v1/oauth/token` |
Comment on lines +268 to +269

Available since: v0.79.6 (2026-06-11).

@github-actions github-actions Bot Jun 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 github-actions Bot Jun 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).


---

### `OPENAI_API_KEY`

If using the Codex by OpenAI engine, you need to set a GitHub Actions secret `OPENAI_API_KEY` with an API key from OpenAI.
Expand Down
2 changes: 1 addition & 1 deletion docs/src/content/docs/reference/engines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ Set `engine:` in your workflow frontmatter and configure the corresponding secre
| Engine | `engine:` value | Required Secret |
|--------|-----------------|-----------------|
| [GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli) (default) | `copilot` | [`copilot-requests: write`](/gh-aw/reference/auth/#copilot-requests-write-permission) (recommended) or [`COPILOT_GITHUB_TOKEN`](/gh-aw/reference/auth/#copilot_github_token) |
| [Claude by Anthropic (Claude Code)](https://www.anthropic.com/index/claude) | `claude` | [ANTHROPIC_API_KEY](/gh-aw/reference/auth/#anthropic_api_key) |
| [Claude by Anthropic (Claude Code)](https://www.anthropic.com/index/claude) | `claude` | [`ANTHROPIC_API_KEY`](/gh-aw/reference/auth/#anthropic_api_key) (standard) or [`engine.auth` Anthropic WIF](/gh-aw/reference/auth/#anthropic-workload-identity-federation-wif) (keyless) |
| [OpenAI Codex](https://openai.com/blog/openai-codex) | `codex` | [OPENAI_API_KEY](/gh-aw/reference/auth/#openai_api_key) |
| [Google Gemini CLI](https://github.com/google-gemini/gemini-cli) | `gemini` | [GEMINI_API_KEY](/gh-aw/reference/auth/#gemini_api_key) |
| [Crush](https://github.com/charmbracelet/crush) (experimental) | `crush` | [COPILOT_GITHUB_TOKEN](/gh-aw/reference/auth/#copilot_github_token) |
Expand Down
Loading