Claude Code + GitHub Actions: Complete Setup and Use Cases

In the terminal, Claude Code is an interactive assistant. The conversation happens in real time — question, answer, edit, commit. But code doesn't just live on your machine. It lives on GitHub.

What if Claude Code could run there too? Automatically reviewing PRs, responding when someone mentions @claude in an issue, or even attempting to fix CI failures on its own?

That's exactly what claude-code-action does. Anthropic's official GitHub Action puts Claude Code inside GitHub Actions — the same model, the same capabilities, running in response to repository events.

What is claude-code-action

The claude-code-action is the official GitHub Action maintained by Anthropic. It lets Claude Code execute inside GitHub Actions runners, with access to the repository code and the ability to interact through comments.

In practice, it works like this: an event happens on GitHub (PR opened, comment created, issue filed), the workflow triggers, and Claude Code analyzes the context and responds.

The model is the same one that runs in the terminal. The repository's CLAUDE.md is respected. The difference is the execution context — instead of an interactive conversation, Claude receives the task, executes, and responds.

To understand the hierarchy:

• Workflow (.yml file) defines when and how Claude runs
• Action (claude-code-action) is what executes
• Plugin (optional) defines a specific behavior — like structured code review

Step-by-step setup

The setup involves three steps: installing the GitHub App, configuring authentication, and creating workflow files.

Prerequisites

• A GitHub repository
• An active Claude Code subscription or an Anthropic API key

Step 1 — Install the Claude GitHub App

Go to github.com/apps/claude and install the app on your repository (or across the entire organization).

The app requires these permissions:

• Contents — Read & Write
• Issues — Read & Write
• Pull Requests — Read & Write

Without the app installed, Claude cannot post comments or interact with PRs and issues.

Step 2 — Configure authentication

There are two authentication methods. The choice depends on how you want to pay for usage.

Option A: API Key (pay-per-token)

Generate a key from the Anthropic Console and add it as a repository secret:

# Settings → Secrets and variables → Actions → New repository secret
# Name: ANTHROPIC_API_KEY
# Value: sk-ant-...

Option B: OAuth Token (uses subscription quota)

If you have a Claude Pro or Max subscription, you can use your existing quota instead of paying per token. Generate the token in your terminal:

claude setup-token

Copy the generated token and add it as a secret:

# Settings → Secrets and variables → Actions → New repository secret
# Name: CLAUDE_CODE_OAUTH_TOKEN
# Value: (token generated by the command above)

Step 3 — Create the workflow files

Create the .github/workflows/ directory in the repository root (if it doesn't exist) and add the files below.

Workflow 1: Interactive assistant (@claude mentions)

This workflow makes Claude respond whenever someone mentions @claude in PR comments, issues, or code reviews.

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

jobs:
  claude:
    if: |
      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
      (github.event_name == 'issues' && contains(github.event.issue.body, '@claude'))
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}

Now, in any PR or issue, just write something like @claude explain what this function does and Claude responds directly on GitHub.

Workflow 2: Automatic PR code review

This workflow triggers automatically when a PR is opened or updated. It uses the official code review plugin for structured analysis.

name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]

jobs:
  claude-review:
    if: github.actor != 'dependabot[bot]'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
          plugins: 'code-review@claude-code-plugins'
          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'

Notice the if: github.actor != 'dependabot[bot]' condition — this prevents Claude from spending tokens reviewing automated Dependabot PRs.

Billing: API Key vs OAuth Token

The authentication method determines how usage is billed. This table summarizes the differences:

Aspect	API Key	OAuth Token
Billing	Per token consumed	Subscription quota
Cost	Variable, can get expensive at volume	Predictable monthly
Best for	Teams, high volume	Solo devs, Pro/Max subscribers
Setup	Anthropic Console → API Keys	claude setup-token in terminal

One important detail: if both ANTHROPIC_API_KEY and OAuth are configured in the same repository, the API key takes priority. This means per-token billing even if OAuth is set up. To use the subscription quota, remove the API key from secrets.

Advanced use cases

The two workflows above cover the most common scenarios. But there's room to go further.

Automatic issue triage

Claude can classify new issues, suggest labels, and post an initial comment with analysis.

name: Issue Triage
on:
  issues:
    types: [opened]

jobs:
  triage:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          prompt: |
            Analyze this new issue. Classify it as bug, feature, question, or docs.
            Suggest appropriate labels. If it's a bug, try to identify
            which files might be involved based on the description.

Security-focused review

For repositories with authentication routes or sensitive APIs, a security-focused review can catch vulnerabilities early.

- uses: anthropics/claude-code-action@v1
  with:
    claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
    prompt: |
      Review this PR with a security-first mindset aligned with OWASP Top 10.
      Focus on: input validation, authentication flows, SQL injection,
      XSS vectors, secrets exposure, and insecure dependencies.
      Flag any finding as [CRITICAL], [HIGH], [MEDIUM], or [LOW].

Scheduled maintenance

A weekly scheduled workflow that checks for outdated dependencies and forgotten TODOs in the codebase.

name: Weekly Maintenance
on:
  schedule:
    - cron: '0 9 * * 1'  # Monday at 9am UTC

jobs:
  maintenance:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          prompt: |
            Run a weekly maintenance check:
            1. List any TODO/FIXME/HACK comments with file locations
            2. Check for potential security issues in dependencies
            3. Identify dead code or unused exports
            Create a GitHub issue summarizing the findings.

CI failure auto-fix

When CI fails, Claude can analyze the error and create a branch with the fix.

name: CI Auto-Fix
on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

jobs:
  auto-fix:
    if: github.event.workflow_run.conclusion == 'failure'
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          prompt: |
            The CI workflow failed. Analyze the failure logs,
            identify the root cause, and attempt to fix it.
            Push the fix to a new branch named fix/ci-<short-description>.

Configuration reference

The table below lists the main claude-code-action parameters:

Parameter	Description
claude_code_oauth_token	OAuth token (subscription billing)
anthropic_api_key	API key (pay-per-token billing)
prompt	Custom instructions for the task
claude_args	CLI arguments (--model, --max-turns, --allowedTools)
trigger_phrase	Custom trigger phrase (default: @claude)
allowed_bots	Bot usernames allowed to trigger the workflow
track_progress	Show progress checkboxes in the comment
use_commit_signing	Sign commits via GitHub API
plugin_marketplaces	Plugin repository URLs
plugins	Plugins to load (e.g., code-review@claude-code-plugins)

For the full list of parameters, check the official configuration docs.

CLI vs Action vs Web

Claude Code runs in three different contexts. Each serves a distinct purpose.

	CLI (Terminal)	Action (GitHub)	Web (claude.ai/code)
Execution	Your machine	GitHub runners	Anthropic VMs
Trigger	Manual command	GitHub events	Browser or phone
Interactivity	Full conversation	Fire-and-forget	Interactive, steerable
Context	Memories, CLAUDE.md, conversation	Repo + CLAUDE.md only	Repo + CLAUDE.md + session
Compute cost	None	GitHub Actions minutes	Included in subscription
Model cost	Subscription	API tokens or OAuth	Subscription
Best for	Daily development	Automated CI/CD	Remote tasks, mobile

The most common combination: CLI for day-to-day work, Action for repository automation. The Web version is useful for delegating longer tasks and monitoring from a phone.

Tips and gotchas

Dependabot PRs. Always exclude them with if: github.actor != 'dependabot[bot]'. Without this, every version bump burns tokens unnecessarily.

Model override. For tasks that need deeper reasoning, force a specific model:

claude_args: '--model claude-opus-4-6'

Timeout. Set a limit on the job to prevent stuck executions:

jobs:
  claude:
    timeout-minutes: 15

Concurrency. Prevent parallel runs on the same issue or PR:

concurrency:
  group: claude-${{ github.event.issue.number || github.event.pull_request.number }}
  cancel-in-progress: true

Limitations to keep in mind:

• Claude cannot modify workflow files (.github/workflows/) — a GitHub security restriction
• Claude does not create PRs directly — it pushes to a branch and provides a link
• Only users with write access to the repository can trigger @claude

References

• Claude Code GitHub Actions - Official Docs
• anthropics/claude-code-action — Official repository
• Setup Guide
• Security Documentation
• Solutions & Workflow Examples
• Configuration Reference