Add CLAUDE_CODE_OAUTH_TOKEN support to Claude engine

[lucasilverentand]

Summary

Adds support for CLAUDE_CODE_OAUTH_TOKEN as an authentication option for the Claude engine, alongside the existing ANTHROPIC_API_KEY.

Changes

• Core Engine (pkg/workflow/claude_engine.go): Updated to use GenerateMultiSecretValidationStep with both tokens, with CLAUDE_CODE_OAUTH_TOKEN taking precedence
• Tests: Updated all Claude engine and secret validation tests to verify both token types
• Documentation: Updated engine docs, CLI docs, and setup templates with examples for both tokens
• CLI Support (pkg/cli/trial_command.go): Updated --use-local-secrets to check CLAUDE_CODE_OAUTH_TOKEN first

Pattern

Follows the existing pattern from Codex engine (CODEX_API_KEY || OPENAI_API_KEY) for consistency:

ANTHROPIC_API_KEY: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN || secrets.ANTHROPIC_API_KEY }}

Test plan

• All Claude engine tests pass (33+ tests)
• All secret validation tests pass
• Multi-secret validation works correctly
• Backward compatible with existing ANTHROPIC_API_KEY usage

🤖 Generated with Claude Code

[Copilot]

Pull Request Overview

This PR adds support for CLAUDE_CODE_OAUTH_TOKEN as an alternative authentication method for the Claude Code engine, with ANTHROPIC_API_KEY as a fallback. The changes enable users to authenticate using either token, with CLAUDE_CODE_OAUTH_TOKEN taking precedence when both are set.

Key Changes:

• Added multi-secret validation support for Claude engine to accept both CLAUDE_CODE_OAUTH_TOKEN and ANTHROPIC_API_KEY
• Updated execution steps to use GitHub Actions fallback syntax (||) for secret precedence
• Updated CLI trial command to check for CLAUDE_CODE_OAUTH_TOKEN before falling back to ANTHROPIC_KEY
• Updated documentation and setup templates to reflect both authentication options

Reviewed Changes

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

Show a summary per file

File	Description
pkg/workflow/claude_engine.go	Switched from single to multi-secret validation and updated environment variable to use fallback syntax
pkg/workflow/claude_engine_test.go	Updated tests to verify both secrets are validated and fallback syntax is used
pkg/workflow/secret_validation_test.go	Updated test assertions to check for both CLAUDE_CODE_OAUTH_TOKEN and ANTHROPIC_API_KEY
pkg/cli/trial_command.go	Added logic to check CLAUDE_CODE_OAUTH_TOKEN before ANTHROPIC_KEY fallback
docs/src/content/docs/reference/engines.md	Updated documentation to describe both authentication options
docs/src/content/docs/tools/cli.md	Added CLAUDE_CODE_OAUTH_TOKEN to the list of environment variables
pkg/cli/templates/setup-agentic-workflows.md	Updated setup instructions to show both authentication options
.github/agents/setup-agentic-workflows.md	Updated agent template with both authentication options

Comments suppressed due to low confidence (2)

pkg/workflow/secret_validation_test.go:152

• This test should also verify the error messages and fallback logic similar to the Codex test at line 198. The test should check for the 'Neither ... nor ...' error message and the 'using as fallback' success message to ensure the generated step correctly implements the multi-secret validation behavior.

	if !strings.Contains(firstStep, "Validate CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY secret") {
		t.Error("First installation step should validate CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY secret")
	}
	if !strings.Contains(firstStep, "CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}") {
		t.Error("Secret validation step should reference secrets.CLAUDE_CODE_OAUTH_TOKEN")
	}
	if !strings.Contains(firstStep, "ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}") {
		t.Error("Secret validation step should reference secrets.ANTHROPIC_API_KEY")
	}

pkg/workflow/claude_engine_test.go:51

• Similar to the Codex engine test (lines 198-200), this test should verify the bash validation logic that checks if both secrets are empty: if [ -z \"$CLAUDE_CODE_OAUTH_TOKEN\" ] && [ -z \"$ANTHROPIC_API_KEY\" ]. This ensures the validation step will properly fail when neither secret is configured.

	if !strings.Contains(secretValidationStep, "CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}") {
		t.Errorf("Expected 'CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}' in secret validation step, got: %s", secretValidationStep)
	}
	if !strings.Contains(secretValidationStep, "ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}") {
		t.Errorf("Expected 'ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}' in secret validation step, got: %s", secretValidationStep)
	}

---

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

[pelikhan]

@lucasilverentand are you able to test this locally?

[lucasilverentand]

@lucasilverentand are you able to test this locally?

The tests complete locally but I'll verify it locally. I've already caught something I (+claude) did wrong. we should not set it as the same variable rather they should be handled as either CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY as Claude Code handles them differently internally. After this change I will do another round of local validations.

Excuse my premature PR, I'll fix it right away.

[pelikhan]

No worries. I was wondering whether we needed to mint a token using OpenID

[lucasilverentand]

Regarding the OpenID/token minting question: No, we don't need to mint the token. The CLAUDE_CODE_OAUTH_TOKEN is meant to be obtained by users externally (likely from Claude Code's authentication system) and configured as a GitHub secret, similar to how ANTHROPIC_API_KEY works.

The workflow simply:

1. Validates that at least one secret (CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY) is configured
2. Passes both environment variables to the Claude CLI
3. The Claude CLI itself handles the authentication logic and determines which token to use

This is consistent with how other engines work (e.g., Codex with CODEX_API_KEY/OPENAI_API_KEY) - they all expect pre-configured secrets rather than minting tokens.

[lucasilverentand]

@pelikhan As you can see it runs in https://github.com/lucasilverentand/gh-aw-trial/actions/runs/19045577600. What would the next steps be to get this merged?

Let me know if I can do anything! 😄

[pelikhan]

It's merged. I will mint a release shortly.

[lucasilverentand]

Absolutely amazing, thank you for the high momentum here!