codyswanngt/claude-code-action

Claude Code Action Workflow Guide

Reference guide for creating anthropics/claude-code-action@v1 GitHub workflows.

Authentication

Choose one authentication method:

| Method | Input | Use Case | |--------|-------|----------| | OAuth Token | claude_code_oauth_token | Recommended for most setups (requires Claude Pro or Max) | | API Key | anthropic_api_key | Direct Anthropic API key from console.anthropic.com | | AWS Bedrock | aws_access_key_id + aws_secret_access_key | AWS-hosted Claude | | GCP Vertex | gcp_project_id + gcp_region + gcp_workload_identity_provider | Google Cloud Claude |

Getting CLAUDE_CODE_OAUTH_TOKEN

Requires a Claude Pro or Max subscription.

1. Run locally:

   claude setup-token
   

2. Copy the output token
3. Add it as a GitHub repository secret:

   gh secret set CLAUDE_CODE_OAUTH_TOKEN
   

   Paste the token when prompted.

On macOS, Claude Code stores credentials in the encrypted Keychain (not a plain file). The setup-token command is the official way to extract a token for CI use.

Repository Configuration

| Name | Type | Required For | How to Set | |------|------|-------------|------------| | CLAUDE_CODE_OAUTH_TOKEN | Secret | All Claude workflows | gh secret set CLAUDE_CODE_OAUTH_TOKEN | | ENABLE_CLAUDE_NIGHTLY | Variable | Nightly workflows (opt-in) | gh variable set ENABLE_CLAUDE_NIGHTLY --body "true" |

Workflow Patterns

Interactive (PR/Issue mentions)

Triggered when users mention @claude in comments, reviews, or issues.

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
  issues:
    types: [opened, assigned]
  pull_request_review:
    types: [submitted]

CI Auto-Fix (Automation)

Triggered when a CI workflow fails. Automatically fixes the code.

on:
  workflow_run:
    workflows: ["CI Quality Checks"]
    types: [completed]

Guard against infinite loops:

if: |
  github.event.workflow_run.conclusion == 'failure' &&
  !startsWith(github.event.workflow_run.head_branch, 'claude-auto-fix-') &&
  github.event.workflow_run.head_branch != 'main' &&
  github.event.workflow_run.head_branch != 'staging' &&
  github.event.workflow_run.head_branch != 'dev'

Nightly/Scheduled

Runs on a cron schedule for maintenance tasks (test improvement, coverage).

on:
  schedule:
    - cron: '0 3 * * 1-5'  # 3 AM UTC weekdays
  workflow_dispatch:

Use opt-in guard:

if: vars.ENABLE_CLAUDE_NIGHTLY == 'true'

Standard Permissions Block

permissions:
  contents: write
  pull-requests: write
  issues: write
  actions: read
  id-token: write

Tool Allowlisting

Standard allowedTools for Lisa projects:

Edit,MultiEdit,Write,Read,Glob,Grep,Bash(git:*),Bash(npm:*),Bash(npx:*),Bash(bun:*),Bash(yarn:*),Bash(pnpm:*),Bash(gh:*)

This covers:

• File operations: Edit, MultiEdit, Write, Read, Glob, Grep
• Git: Bash(git:*) -- commit, push, branch, etc.
• Package managers: npm, npx, bun, yarn, pnpm
• GitHub CLI: Bash(gh:*) -- create PRs, issues, etc.

Key Inputs

| Input | Required | Description | |-------|----------|-------------| | prompt | No | Task instructions for Claude | | claude_code_oauth_token | Yes* | OAuth token for authentication | | claude_args | No | CLI args: --allowedTools, --max-turns, --system-prompt, --mcp-config | | branch_prefix | No | Prefix for auto-created branches (e.g., claude/nightly-) | | additional_permissions | No | Extra GitHub permissions (e.g., actions: read) | | max_turns | No | Max agentic turns (via claude_args --max-turns) | | track_progress | No | Enable progress tracking comments | | allowed_bots | No | Comma-separated bot names allowed to trigger | | allowed_non_write_users | No | Users without write access who can trigger |

MCP Configuration

Pass MCP server config via claude_args:

claude_args: |
  --mcp-config .mcp.json

Pass secrets to MCP servers via environment variables in the workflow.

Patterns

Duplicate PR Prevention

Before running nightly workflows, check for existing open PRs:

- name: Check for existing PR
  id: check-pr
  uses: actions/github-script@v7
  with:
    script: |
      const pulls = await github.rest.pulls.list({
        owner: context.repo.owner,
        repo: context.repo.repo,
        state: 'open',
        per_page: 100,
      });
      const existing = pulls.data.find(pr =>
        pr.head.ref.startsWith('claude/nightly-') &&
        pr.title.toLowerCase().includes('your-keyword')
      );
      core.setOutput('has_existing_pr', existing ? 'true' : 'false');

- name: Run Claude
  if: steps.check-pr.outputs.has_existing_pr != 'true'
  uses: anthropics/claude-code-action@v1

Cost Control

Use --max-turns to limit API usage:

claude_args: |
  --max-turns 25

Recommended limits:

• Interactive (PR/issue): No limit (user-driven)
• CI auto-fix: 25 turns
• Nightly workflows: 40 turns

Security

• Never hardcode secrets in workflow files
• Use ${{ secrets.* }} for all sensitive values
• Sanitize dynamic content in prompts to prevent injection
• Use allowed_bots to control which bots can trigger Claude