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

#claudecode #githubactions #ci #automation

Originally published at https://aicoding-guide.com.

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.

Key point
What you will learn

Setting up with /install-github-app, and which authentication secret to use

The workflow that responds to @claude mentions

The automated review workflow, who can trigger runs, and how to cap cost

Setting up

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.
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.
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/.

Glossary
The GitHub App and GITHUB_TOKEN: by default the action authenticates as the Claude GitHub App. If you pass github_token: ${{ secrets.GITHUB_TOKEN }} instead, GitHub won't trigger workflows on the commits Claude makes — the documented fix for "CI not running on Claude's commits" is to remove that line.

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"'

Without --comment, nothing is posted
In automation mode, "By default, results appear in the workflow run log rather than a comment." --comment is what makes Claude post on the pull request. Keep the claude_args line too: even though the skill's own allowed-tools frontmatter names the same tool, the action starts the inline-comment MCP server only when --allowedTools in claude_args names it.

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

Glossary
Who can trigger a run is checked by the action itself: two checks run before Claude starts, and the run fails if either rejects it. Write access — on issue and pull request events the triggering user must have write access to the repository; to allow specific users without it, set allowed_non_write_users and pass your own github_token. Human actor — a bot actor is rejected unless listed in allowed_bots, which keeps bots from triggering Claude in a loop. That check also applies to scheduled runs, which GitHub attributes to a repository user.

Secrets and pull requests from forks
On public repositories, GitHub withholds secrets from runs triggered by fork pull requests, so a review workflow runs only on pull requests from branches in the same repository. Before reaching for pull_request_target to change that, understand that it runs the fork's code with your secrets available.

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

DEV Community