Claude Code GitHub Workflows

When to Use This Skill

Expert knowledge for designing GitHub Actions workflows that integrate Claude Code for automated code assistance, PR reviews, and issue triage.

Core Expertise

Workflow Design Patterns

• Automated pull request reviews with inline comments
• Issue triage and automated responses
• CI failure auto-fix workflows
• Custom trigger configurations and event handling

Trigger Configurations

• Issue comment triggers (@claude mentions)
• Pull request events (opened, synchronize, ready_for_review)
• Workflow run triggers (CI failure handling)
• Path-filtered reviews for specific directories

Display name convention

Every workflow's name: follows <Domain>: <Action> [<target>] (quoted, since YAML treats : as a key separator). Use the Claude: domain for Claude Code-driven workflows; use Auto-fix: for workflow_run-triggered remediation. See .claude/rules/workflow-naming.md for the canonical rule and active domains. The example snippets below dogfood the convention.

When a workflow's on.workflow_run.workflows lists another workflow's display name, the listed string must match the target workflow's name: exactly — update both sides in the same change.

Essential Workflow Template

name: "Claude: @mentions"

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

jobs:
  claude:
    if: |
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'issues' && contains(github.event.issue.body, '@claude'))
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - name: Checkout repository
        uses: actions/checkout@v5
        with:
          fetch-depth: 1

      - name: Run Claude Code
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Automation Patterns

Comprehensive PR Review

name: "Claude: PR review"

on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      id-token: write
    steps:
      - uses: actions/checkout@v5
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          track_progress: true
          prompt: |
            Review this PR focusing on:
            1. Code Quality
            2. Security
            3. Performance
            4. Testing
            5. Documentation

CI Failure Auto-Fix

name: "Auto-fix: CI failures"

on:
  workflow_run:
    # The string here must match the target workflow's `name:` exactly.
    workflows: ["Test: Suite"]
    types: [completed]

jobs:
  auto-fix:
    if: github.event.workflow_run.conclusion == 'failure'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      actions: read
    steps:
      - uses: actions/checkout@v5
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            The CI workflow failed. Please:
            1. Analyze the failure logs
            2. Identify the root cause
            3. Implement a fix
            4. Create a PR with the fix

Issue Triage and Labeling

name: "Claude: Issue triage"

on:
  issues:
    types: [opened]

jobs:
  triage:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Analyze this issue and:
            1. Add appropriate labels (bug, feature, documentation, etc.)
            2. Suggest a priority level
            3. Recommend assignment if obvious
            4. Ask clarifying questions if needed

Path-Filtered PR Review

name: "Claude: Review backend changes"

on:
  pull_request:
    paths:
      - 'backend/**'
      - 'api/**'

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v5
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Review backend changes focusing on:
            - API design and RESTful principles
            - Database query optimization
            - Error handling and logging
            - Security vulnerabilities

Custom Trigger Phrase

name: "Claude: Custom trigger"

on:
  issue_comment:
    types: [created]

jobs:
  claude:
    if: contains(github.event.comment.body, '/claude-review')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
    steps:
      - uses: actions/checkout@v5
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          trigger_phrase: "/claude-review"

External Contributor Handling

Security: pull_request_target runs in the base repo context with access to secrets and a write-capable token, even for fork PRs. The job below checks out untrusted head code (head.sha) for review only — do not add build/test steps that execute that code, and treat the PR title/body/comments as untrusted input in the prompt. See github-actions-auth-security and .claude/rules/github-actions-security.md.

name: "Claude: Review external contributions"

on:
  pull_request_target:
    types: [opened]

jobs:
  review:
    if: github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.pull_request.head.sha }}

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Welcome first-time contributor! Review this PR for:
            - Code quality and style compliance
            - Test coverage
            - Documentation updates
            - Security concerns

            Provide helpful, constructive feedback.

claude-code-action v1 Gotchas

Hard-won facts that produce silently-broken workflows (each cost real debugging in production; see laurigates/.github#17–#19):

Outputs are fixed — counts need --json-schema

The action exposes only execution_file, branch_name, github_token, structured_output, and session_id. Referencing anything else (steps.scan.outputs.total) evaluates to empty with no error — and prompting Claude to print TOTAL: <n> in a comment does not create a step output. Any metric a workflow needs out of a Claude step goes through structured output:

- id: scan
  uses: anthropics/claude-code-action@v1
  with:
    claude_args: >-
      --json-schema '{"type":"object","properties":{"total_issues":{"type":"integer"}},"required":["total_issues"]}'
    prompt: |
      ...analysis instructions...
      Report the count in the structured output field total_issues.

# Read it back — the || '{}' guard is REQUIRED: job outputs evaluate even
# when the step was skipped, and fromJSON('') errors.
outputs:
  issues: ${{ fromJSON(steps.scan.outputs.structured_output || '{}').total_issues }}

The same guarded expression works in if: gates (fromJSON(... || '{}').critical > 0) — an unguarded comparison against a missing output silently never fires.

The same law covers comment markers: anything CI greps for in an agent's output must be written by a workflow step, not requested from the model — see REFERENCE.md § A marker the model has to emit.

Bots are blocked by default

allowed_bots defaults to empty — no bot may trigger the action, so bot-authored PRs (Renovate, release-please, Dependabot) fail with "Workflow initiated by non-human actor". Pass allowed_bots: "renovate[bot]" (or a comma-separated list) on workflows where bot PRs are the point, e.g. dependency audits triggered by lockfile changes. Re-running a failed run does not help: the replay keeps the original bot sender.

Deprecated inputs (removed in a future version)

direct_prompt, override_prompt, custom_instructions, max_turns, model, fallback_model, allowed_tools, disallowed_tools, mcp_config, claude_env, mode are all deprecated. Use prompt plus claude_args (--model, --max-turns, --allowedTools, --disallowedTools, --mcp-config, --system-prompt) and settings (env). A deprecated input may be silently ignored — a workflow using direct_prompt can run with no prompt at all.

Budget levers

claude_args supports --max-turns (turn count) and --max-budget-usd (run-level spend cap); there is no token-count budget. Both fail the run mid-flight when exhausted — they bound waste but don't prevent doomed runs on oversized diffs; pre-gate on diff size for that. Turn-budget exhaustion is recognizable by error_max_turns in the execution_file and by a rotating set of failing AI jobs across re-runs of the same commit.

--model and --effort are the cost levers, not --max-turns. --model takes an alias (opus, sonnet, fable, best) or a full id; aliases move with each model generation, so record the alias you chose next to the effort. --effort low|medium|high|xhigh|max overrides the harness default (high); effort names do not map across model generations, so re-check the level when the alias's target changes. haiku supports no --effort at all, so opus --effort low is the cheap tier, not haiku. Every template above should carry both, e.g.

claude_args: |
  --model opus
  --effort medium

Performance Optimization

Checkout Optimization

# Fast checkout for large repos
- uses: actions/checkout@v5
  with:
    fetch-depth: 1          # Shallow clone
    sparse-checkout: |      # Only needed paths
      .github
      src
      tests

Conversation Limits

# Control execution time and cost
claude_args: |
  --max-turns 10  # Limit back-and-forth exchanges

Conditional Execution

# Skip unnecessary runs
jobs:
  claude:
    if: |
      contains(github.event.comment.body, '@claude') &&
      !contains(github.event.comment.body, 'ignore')

Repository Configuration

CLAUDE.md Example

Create CLAUDE.md in repository root to define coding standards:

# Repository Guidelines for Claude Code

## Code Standards
- Use TypeScript strict mode
- Follow Airbnb style guide
- Maintain 90%+ test coverage
- Document all public APIs

## Development Workflow
- Run tests before committing: `npm test`
- Format with Prettier: `npm run format`
- Lint with ESLint: `npm run lint`

## Commit Messages
Follow Conventional Commits:
- feat: New features
- fix: Bug fixes
- docs: Documentation changes
- refactor: Code refactoring

## Testing Requirements
- Unit tests for all functions
- Integration tests for APIs
- E2E tests for critical flows

## Security
- Never commit secrets
- Validate all user inputs
- Use parameterized queries
- Follow OWASP guidelines

Quick Setup

1. Install Claude GitHub App: https://github.com/apps/claude
2. Add API Key: Repository Settings → Secrets → ANTHROPIC_API_KEY
3. Create Workflow: .github/workflows/claude.yml (use template above)
4. Test: Create issue and comment @claude Hello!
5. (Optional) Add CLAUDE.md in repo root for project standards

Troubleshooting

Workflow Not Triggering

• Check trigger conditions in if: clause
• Verify permissions (contents, pull-requests, issues)
• Check GitHub App installation

Permission Denied

• Ensure proper permissions in workflow
• Check branch protection rules
• Verify repository access

For advanced configuration including MCP servers, tool permissions, and authentication methods, see the github-actions-mcp-config and github-actions-auth-security skills. For the secure-use baseline these templates follow (least-privilege permissions, script-injection indirection, pull_request_target hazards), see .claude/rules/github-actions-security.md.