GitHub Actions

Claude Code integrates with GitHub Actions through the official anthropics/claude-code-action@v1 action. There are two distinct modes: comment-triggered (Claude responds when someone writes @claude in a PR or issue) and automation (Claude runs on workflow events like push or schedule with a prompt you provide).

Both modes use the same action — the difference is whether you provide a prompt in the workflow file or rely on comment triggers.

---

Prerequisites

Before creating any workflow:

1. API key secret — Go to your repo → Settings → Secrets and variables → Actions → New repository secret. Name it ANTHROPIC_API_KEY.

2. Install the Claude GitHub App — Required for comment-triggered mode. Either run /install-github-app inside Claude Code terminal (fastest), or install manually from github.com/apps/claude. The app needs Contents, Issues, and Pull requests read/write.

3. Workflow file location — All files go in .github/workflows/ in your repo root.

You do not need to install the Claude CLI on the runner manually — the action handles that.

---

How the Action Works

graph TD A[PR opened or comment posted] --> B{Trigger type?} B -->|@claude comment| C[Claude GitHub App fires] B -->|workflow event| D[GitHub Actions runner starts] C --> D D --> E[anthropics/claude-code-action@v1] E --> F[Claude reads PR context + CLAUDE.md] F --> G[Claude executes task] G --> H{Output} H -->|comment trigger| I[Posts reply in PR/issue thread] H -->|automation| J[Commits changes or writes artifact] style A fill:#1e293b,color:#7dd3fc,stroke:#334155 style B fill:#1e293b,color:#a78bfa,stroke:#334155 style C fill:#1e293b,color:#7dd3fc,stroke:#334155 style D fill:#1e293b,color:#7dd3fc,stroke:#334155 style E fill:#1e293b,color:#f59e0b,stroke:#334155 style F fill:#1e293b,color:#7dd3fc,stroke:#334155 style G fill:#1e293b,color:#7dd3fc,stroke:#334155 style H fill:#1e293b,color:#a78bfa,stroke:#334155 style I fill:#1e293b,color:#86efac,stroke:#334155 style J fill:#1e293b,color:#86efac,stroke:#334155

Claude automatically reads your CLAUDE.md file during every run. Put your project conventions, code style rules, and review criteria there — Claude will follow them without needing to repeat them in every prompt.

---

Template 1: PR Code Review

Triggers on every PR open or push to an open PR. Claude reviews the diff and posts its findings as a PR comment.

.github/workflows/claude-pr-review.yml

name: Claude PR Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Review this pull request for:
            - Bugs and logic errors
            - Security vulnerabilities
            - Performance issues
            - Missing error handling
            Post your findings as a PR review comment. Be specific about line numbers where relevant.
          claude_args: "--max-turns 5"

What each part does:

• fetch-depth: 0 — fetches full git history so Claude can see the complete diff, not just the latest commit
• permissions: pull-requests: write — required for Claude to post the review comment back to the PR
• prompt — your instructions; Claude also has access to the PR diff, title, and description automatically
• claude_args: "--max-turns 5" — caps the conversation at 5 turns to control cost on large PRs

---

Template 2: Release Notes Generator

Triggers when you push a version tag (v1.0.0, v2.3.1, etc.). Claude reads the commits since the last tag and writes a RELEASE_NOTES.md file.

.github/workflows/claude-release-notes.yml

name: Generate Release Notes

on:
  push:
    tags:
      - 'v*'

jobs:
  release-notes:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Read the git log from the previous tag to HEAD and write release notes.
            Group changes into: Features, Bug Fixes, Breaking Changes, Internal.
            Write to RELEASE_NOTES.md. Use markdown. Keep each item to one sentence.
          claude_args: "--allowedTools Bash,Read,Write --max-turns 5"

      - name: Upload release notes artifact
        uses: actions/upload-artifact@v4
        with:
          name: release-notes
          path: RELEASE_NOTES.md

Note: permissions: contents: write is required here because Claude writes a file to the workspace. Without it, the Write tool will fail.

---

Template 3: Comment-Triggered Assistant

The @claude trigger requires the GitHub App installed. Once installed, anyone with write access can trigger Claude by commenting @claude in any PR or issue.

.github/workflows/claude-assistant.yml

name: Claude Assistant

on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    # Only run when comment contains @claude
    if: |
      contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
    steps:
      - uses: actions/checkout@v4

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          # No prompt here — Claude reads the comment that triggered the run

Example comments that work after this is set up:

@claude implement this feature based on the issue description
@claude fix the TypeError in the dashboard component
@claude add unit tests for the auth module
@claude explain why this approach might cause performance issues

---

Template 4: Scheduled Codebase Audit

Runs every Monday at 9 AM UTC. Claude scans the codebase and writes a weekly audit report.

.github/workflows/claude-weekly-audit.yml

name: Weekly Codebase Audit

on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 09:00 UTC

jobs:
  audit:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            Audit this codebase for:
            1. Security anti-patterns (hardcoded secrets, SQL injection risks, missing input validation)
            2. Outdated dependency patterns in package.json
            3. Files with TODO/FIXME comments that have been open more than 30 days (check git blame)
            Write your findings to audit-report.md. Score each finding: Critical / High / Medium / Low.
          claude_args: "--max-turns 10 --allowedTools Bash,Read,Write"

      - name: Upload audit report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: weekly-audit-${{ github.run_number }}
          path: audit-report.md
          retention-days: 90

---

Action Parameters Reference

Parameter	Required	Description
anthropic_api_key	Yes (direct API)	Your ANTHROPIC_API_KEY secret
prompt	No*	Instructions for Claude. Omit for comment-triggered mode
claude_args	No	Any Claude CLI flags: --max-turns, --model, --allowedTools, etc.
github_token	No	GitHub token for API access. Defaults to GITHUB_TOKEN
trigger_phrase	No	Custom trigger phrase. Default: @claude
use_bedrock	No	Set "true" to use AWS Bedrock instead of direct API
use_vertex	No	Set "true" to use Google Vertex AI instead of direct API

*When prompt is omitted and the trigger is a comment event, Claude reads the comment body automatically.

Passing CLI arguments

The claude_args field accepts any Claude Code CLI flag:

claude_args: |
  --max-turns 10
  --model claude-sonnet-4-6
  --allowedTools Bash,Read,Edit,Write
  --append-system-prompt "Always respond in the language of the PR author"

---

Permissions Reference

Task	Minimum permissions
Read-only code review (no comments)	contents: read
Post PR review comments	contents: read + pull-requests: write
Respond to issue comments	issues: write
Write files to workspace	contents: write
All comment triggers	contents: write + pull-requests: write + issues: write

Set only the permissions your workflow actually needs. Over-permissioning is a common CI security mistake.

---

Cost Management

GitHub Actions costs come from two sources: runner minutes and Anthropic API tokens.

Control runner time:

jobs:
  review:
    runs-on: ubuntu-latest
    timeout-minutes: 10  # Kill the job if it runs longer than 10 minutes

Control API token usage:

claude_args: "--max-turns 3"  # Fewer turns = fewer tokens

Limit concurrent runs (prevents pile-up on busy repos):

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

Use --permission-mode plan for analysis-only tasks. Plan mode means Claude describes what it would do but does not execute any file writes or bash commands — useful for audits where you want findings without side effects.

claude_args: "--permission-mode plan --max-turns 5"

---

Tips

CLAUDE.md is your best lever. Claude reads it on every run. Define your review standards, code style, and what to skip (e.g., “ignore generated files in dist/”) once there, not in every workflow prompt.

fetch-depth: 0 matters. The default actions/checkout@v4 fetches only the latest commit (fetch-depth: 1). For diff-based tasks, Claude needs the full history to compute the diff correctly.

Test with workflow_dispatch first. Add workflow_dispatch: to your on: block during development so you can trigger the workflow manually without pushing commits.

on:
  workflow_dispatch:  # Add this for manual testing
  pull_request:
    types: [opened, synchronize]

---

Related

• GitLab CI/CD — Equivalent setup for GitLab pipelines
• Headless Mode — Understanding claude -p directly
• Common Workflows — Prompt patterns that work well in CI context