Run Claude Code in GitHub Actions with claude-code-action

Comment "@claude fix this bug" on an issue and have Claude Code implement the fix and open a pull request. Have a review appear automatically when a PR opens. Both come from the official claude-code-action, configured with workflow files in your repository.

This article covers setup, the two basic configurations — mention response and automated review — and how to limit permissions and cost.

Setting up

1. Run /install-github-app from Claude Code inside the repository. It installs the Claude GitHub App, sets up the authentication secret, and pushes a branch with the workflow files, opening a pull request for you to create. You need admin access to the repository, and the GitHub CLI installed and authenticated with gh auth login.
2. Register the authentication secret. Use ANTHROPIC_API_KEY for a Claude API key from the Claude Console, or CLAUDE_CODE_OAUTH_TOKEN for a subscription token generated with claude setup-token. In the workflow, pass them to anthropic_api_key and claude_code_oauth_token respectively.
3. Create and merge the pull request. @claude then works in the repository.

/install-github-app only works with github.com repositories; on a gitlab.com or bitbucket.org remote it prints a notice and exits. For manual setup, install the Claude GitHub App yourself, add the secret, and copy examples/claude.yml into .github/workflows/.

Configuration 1: respond to @claude mentions

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

id-token: write is required for the action's default GitHub App authentication, and actions: read lets Claude read CI results on PRs. With no prompt input, the action runs in interactive mode and waits for the trigger phrase — @claude by default, changeable with trigger_phrase.

Requests that work well:

• On an issue: "@claude reproduce this and open a PR with a fix"
• On a review comment: "@claude add error handling to this function"
• On a PR: "@claude add tests for what this change affects"

Configuration 2: review automatically when a PR opens

Supplying a prompt input puts the action in automation mode, which runs without waiting for a mention. The configuration the documentation now shows calls the code-review plugin's skill rather than a free-text prompt:

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

jobs:
  review:
    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:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

With a free-text prompt you have to grant the tools yourself: "For a plain-text prompt, Claude has no shell or GitHub API access until you grant the tools the prompt needs" — through --allowedTools in claude_args, or a permissions.allow rule in the settings input.

Claude skips draft and closed pull requests, ones it judges not to need review, and ones that already carry a comment from Claude.

Limiting permissions and cost

Goal	How
Keep outsiders from triggering runs	Already checked by the action (see below). Narrow further with an if: on github.event.comment.author_association
Minimize write access	Give the review workflow contents: read
Restrict the tools	Pass --allowedTools in claude_args
Cap the work per run	Pass --max-turns, and set a workflow-level timeout
Enforce your project's rules	Put them in the repository's CLAUDE.md, which the action reads

How this relates to CLAUDE.md

Claude inside the action reads the repository's CLAUDE.md the same as it does locally — the documentation lists "Define project standards in CLAUDE.md" as a best practice, and notes that Claude reads it on every run, so keeping it concise also keeps cost down. Review criteria and prohibitions belong there rather than in the workflow's prompt, so you maintain one copy (How to write CLAUDE.md).

For a lighter setup that calls claude -p directly instead of using the official action, see Run Claude Code headless in CI.

Summary

• /install-github-app installs the app and workflows; register ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN as the secret
• No prompt means interactive mode and the @claude trigger; a prompt means automation mode
• In automation mode results go to the run log unless you pass --comment and name the inline-comment tool in claude_args
• Write access and a human-actor check already gate who can trigger runs; allowed_bots and allowed_non_write_users adjust them
• Keep review criteria in CLAUDE.md, and cap cost with --max-turns, a smaller model, and workflow timeouts