How to Set Up GitHub Actions CI/CD on Claude Code

You can run Claude Code inside GitHub Actions using Anthropic's official claude-code-action, which lets you trigger AI-assisted code review, automated fixes, and test generation on every pull request or push. It's built for developers who want to stay in flow without switching tabs to ask Claude questions manually. Requires an Anthropic API key (or Claude Pro/Max plan). CI usage is billed separately from your interactive Claude Code sessions.

• Official action: anthropics/claude-code-action@v1
• Works with PR events, push events, and manual workflow_dispatch triggers
• Supports custom prompts, file context, and tool permissions per workflow step

What is the claude-code-action and how does it work in CI?

The claude-code-action is Anthropic's official GitHub Action that runs Claude Code in a non-interactive, headless mode inside your CI pipeline. You define a prompt, pass it context (diffs, files, test output), and Claude responds with comments, suggestions, or even direct commits back to your branch.

Under the hood it authenticates via your ANTHROPIC_API_KEY secret, spins up a Claude Code session, executes the prompt against your repo, and then writes its output back: either as a PR comment, a step output variable, or a committed file change depending on how you configure it.

How to set up the basic GitHub Actions workflow for Claude Code

Create a file at .github/workflows/claude-review.yml in your repository:

name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  claude-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Run Claude Code review
        uses: anthropics/claude-code-action@v1
        with:
          prompt: |
            Review the changes in this pull request.
            Focus on correctness, performance, and potential bugs.
            Post a concise summary as a PR comment.
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

This triggers on every new or updated PR and posts Claude's review as a comment. The fetch-depth: 0 is important: it gives Claude the full git history so it can understand what changed.

How to store your API key securely

In your GitHub repository, go to Settings > Secrets and variables > Actions, then create a new secret named ANTHROPIC_API_KEY. Paste your key from console.anthropic.com. The action reads it via ${{ secrets.ANTHROPIC_API_KEY }} at runtime.

How to automate PR fixes and code changes (not just comments)

If you want Claude to write code directly (not just comment), you need to expand permissions and configure the action to commit changes back. Here's a workflow that auto-fixes lint errors on push:

name: Claude Auto-Fix

on:
  push:
    branches: [main, dev]

jobs:
  auto-fix:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: anthropics/claude-code-action@v1
        with:
          prompt: |
            Run the linter. If there are any fixable lint errors,
            fix them and commit the changes with message "fix: auto-fix lint errors".
            Do not change logic, only formatting and lint issues.
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          allowed_tools: "Bash,Edit,Write"

The allowed_tools parameter controls what Claude can do. Bash lets it run shell commands (linters, test runners), Edit lets it modify files, and Write lets it create new ones. Only grant what the job actually needs.

How to run tests and generate reports with Claude in CI

A common pattern is to run your test suite, capture the output, and pass it to Claude to generate a human-readable summary or suggest fixes for failing tests:

name: Claude Test Summary

on: [push]

jobs:
  test-and-summarize:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run tests
        id: tests
        run: npm test 2>&1 | tee test-output.txt || true

      - uses: anthropics/claude-code-action@v1
        with:
          prompt: |
            Read the file test-output.txt.
            Summarize which tests failed and why.
            For each failure, suggest a concrete fix.
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          allowed_tools: "Read,Bash"

The || true prevents the test step from canceling the workflow on failure, ensuring Claude still gets to analyze the output.

What are the key configuration options for claude-code-action?

Parameter	Required	Description
prompt	Yes	The instruction Claude receives. Supports multiline YAML strings.
anthropic_api_key	Yes	Your Anthropic API key, stored as a GitHub secret.
allowed_tools	No	Comma-separated list: Bash, Read, Edit, Write, Glob, Grep.
model	No	Defaults to latest Claude Sonnet. Override with any Claude model ID.
max_turns	No	Caps the agentic loop at N turns to control cost.
timeout_minutes	No	GitHub Actions job timeout. Default varies by runner.

How CI/CD usage affects your Claude usage limits

This is the part that trips up developers: GitHub Actions runs use API tokens, not your interactive Claude Code session quota. But if you're running Claude Code locally and have pipelines firing in the background, your API spend can spike unexpectedly.

According to Anthropic's support documentation, Claude Code on Pro or Max plans has usage windows that reset on a rolling basis. Hitting that limit mid-sprint (especially during a code review cycle) means a 5-hour wait before you can continue. That's exactly the kind of context switch that kills momentum.

If you're actively running CI pipelines alongside local Claude Code sessions, keeping an eye on your remaining quota matters. Usagebar sits in your macOS menu bar and shows your live usage at a glance, with alerts at 50%, 75%, and 90% so you can decide whether to queue up more CI jobs or save headroom for interactive work. You can also check your current usage with the /usage command directly in Claude Code, or at claude.ai/settings/usage.

Understanding when your Claude Code usage resets is especially useful when you're planning to run heavy CI jobs: schedule them right after a reset window to maximize available quota.

Best practices for Claude Code in GitHub Actions

• Scope prompts tightly. Vague prompts lead to long agentic loops and higher token cost. Tell Claude exactly what to look at and what output to produce.
• Use max_turns. Set a cap to prevent runaway jobs from consuming unexpected quota or CI minutes.
• Limit allowed_tools. A review job doesn't need Write. Principle of least privilege applies to AI agents too.
• Cache dependencies before Claude runs. Put npm install or equivalent in a prior step so Claude's Bash calls don't re-download packages on every turn.
• Use workflow_dispatch for expensive jobs. Don't trigger heavy Claude analysis on every commit to main. Manually trigger or limit to specific branches.
• Separate review and fix workflows. A read-only review workflow (no Edit/Write) is safer to run broadly. Reserve write-capable workflows for specific, trusted triggers.

For teams building more complex automations, the full CI/CD pipeline guide for Claude Code covers multi-step pipelines and parallelization strategies. You might also want to look at how Claude Code handles git commits for the interactive side of the same workflow.

Monitor your usage so CI jobs don't lock you out

The worst-case scenario: you kick off a batch of CI jobs to review a large PR, they drain your remaining quota, and then you're locked out for hours right when you need to respond to review feedback. Knowing your usage headroom before triggering expensive pipelines prevents exactly this.

Get Usagebar for an instant download, persistent menu bar indicator with smart threshold alerts. It uses macOS Keychain to store credentials securely and shows exactly when your usage window resets so you can plan CI runs around your actual quota. Pricing is pay-what-you-want, with a free option for students.

Key takeaways

1. Use anthropics/claude-code-action@v1 to run Claude Code in any GitHub Actions workflow.
2. Store your API key as a GitHub Actions secret, never hardcoded.
3. Control scope with allowed_tools and max_turns to manage cost and safety.
4. CI usage draws from API quota, separate from interactive sessions, but both count toward your plan limits if you're on Pro or Max.
5. Use /usage in Claude Code, or Usagebar, to monitor headroom before running expensive pipelines.
6. Schedule heavy CI jobs after a usage reset window to maximize available capacity.

Sources

• https://github.com/anthropics/claude-code-action
• https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan
• https://support.claude.com/en/articles/9797557-usage-limit-best-practices
• https://claude.ai/settings/usage