Claude Code GitHub Actions

Configure automation using anthropics/claude-code-action with event routing, subagents, hooks, and MCP integration.

Quick Start

name: Claude Code
on:
  issue_comment: { types: [created] }
  pull_request: { types: [opened, synchronize] }
  issues: { types: [opened, labeled] }

permissions:
  contents: write
  pull-requests: write
  issues: write

jobs:
  claude:
    if: github.actor != 'github-actions[bot]'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Core Concepts

Key Patterns

Event Routing

jobs:
  pr-comment:
    if: github.event_name == 'issue_comment' && github.event.issue.pull_request
  issue-comment:
    if: github.event_name == 'issue_comment' && !github.event.issue.pull_request
  label-triggered:
    if: contains(github.event.issue.labels.*.name, 'claude-implement')

Subagents

prompt: |
  Delegate to 3 parallel subagents:
  1. Security Agent: OWASP Top 10, auth checks
  2. Performance Agent: N+1 queries, memory leaks
  3. Style Agent: Naming, documentation, tests

Hooks

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "npx prettier --write $(jq -r '.tool_input.file_path')" }]
    }],
    "Stop": [{
      "hooks": [{ "type": "command", "command": "npm run lint && npm test" }]
    }]
  }
}

Performance

concurrency:
  group: claude-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

on:
  pull_request:
    paths: ['src/**', '!**/*.md']

Tuning Reference

Critical Gotchas

1. --allowedTools vs --disallowedTools

- allowedTools only skips prompts—does NOT restrict tools - Use disallowedTools to actually block: --disallowedTools Bash,Run,Edit

1. MCP + Subagents

- MCP tools do NOT work in background subagents - Always run MCP operations in foreground

1. Fork Safety

- pullrequest event = safe (read-only token, no secrets) - pullrequesttarget = dangerous if you checkout fork code - Never: checkout ref: ${{ github.event.pullrequest.head.sha }} with secrets

1. Hook Exit Codes

- 0 = continue - 2 = block, feed stderr to Claude - Other = log error, don't block

1. Subagent Limits

- ~10 concurrent subagents max - Additional tasks queue

Examples

See [examples/](examples/) for 14 production-ready use cases:

Patterns

• [Event Routing](patterns/event-routing.md) - Conditions, label routing, author associations
• [Subagents](patterns/subagents.md) - Creation, parallel execution, built-in types
• [Hooks](patterns/hooks.md) - All events, exit codes, JSON parsing, examples
• [Permissions](patterns/permissions.md) - Tool control layers, known issues
• [Security](patterns/security.md) - Fork handling, external contributors, safe patterns
• [Reusable Workflows](patterns/reusable-workflows.md) - workflow_call, composite actions
• [Performance](patterns/performance.md) - Concurrency, caching, path filtering
• [Skills](patterns/skill-usage.md) - Domain expertise, skill structure, hooks

Official Docs

Synced from anthropics/claude-code-action:

• [Configuration](official-docs/configuration.md) - MCP servers, settings, custom tools
• [Security](official-docs/security.md) - API key protection, commit signing
• [Usage](official-docs/usage.md) - Inputs, outputs, migration guide