GitHub Actions

Automate code review, issue handling, and pull request workflows using Claude Code in GitHub Actions.

Claude Code integrates with GitHub Actions through the anthropics/claude-code-action action. Once set up, you can mention @claude in pull request or issue comments to trigger Claude to analyze context and act on the request.

Quick setup

The easiest way to add the workflow to a repository is with the built-in installer:

claude install-github-app

This interactive command walks you through:

1. Authenticate with GitHub

   The installer checks that you are authenticated with the GitHub CLI (gh). If not, it prompts you to log in.

2. Choose a repository

   Select the repository to set up, or use the current repository if you are already inside one.

3. Provide your Anthropic API key

   Enter your ANTHROPIC_API_KEY. The installer stores it as a GitHub Actions secret in the selected repository using gh secret set.

4. Select workflows

   Choose which workflows to install: the Claude PR assistant workflow, the Claude Code Review workflow, or both.

5. Open the pull request

   The installer creates a new branch, commits the workflow file(s), and opens a browser tab with a pre-filled pull request for you to review and merge.

The workflows do not take effect until the pull request is merged into the default branch.

Available workflows

Claude PR assistant

Triggers when @claude is mentioned in a pull request comment, pull request review, issue comment, or issue body/title.

Workflow file: .github/workflows/claude.yml

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') || contains(github.event.issue.title, '@claude')))
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
      actions: read
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Run Claude Code
        id: claude
        uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Claude Code Review

Runs automatically on every pull request (opened, synchronized, or reopened) and posts a code review using the code-review plugin.

Workflow file: .github/workflows/claude-code-review.yml

name: Claude Code Review

on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]

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

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Run Claude Code Review
        id: claude-review
        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 ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'

Required secrets

Secret	Description
ANTHROPIC_API_KEY	Your Anthropic API key. Set this as a GitHub Actions repository secret.
CLAUDE_CODE_OAUTH_TOKEN	Alternative to ANTHROPIC_API_KEY when using OAuth authentication.

The installer sets the secret automatically. To set it manually:

gh secret set ANTHROPIC_API_KEY --body "sk-ant-..." --repo owner/repo

Required permissions

The workflow jobs request the following GitHub Actions permissions. Grant only what your use case needs:

Permission	Level	Purpose
contents	read	Read repository files and history
pull-requests	read	Read PR diffs and comments
issues	read	Read issue body and comments
id-token	write	OIDC token (used for authentication)
actions	read	Read CI results on PRs

Only users with write access to a repository can trigger the workflow by mentioning @claude. Mentions from other users are ignored.

Customizing the workflow

Custom prompt

Add a fixed prompt to the Run Claude Code step to instruct Claude regardless of what the comment says:

- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: 'Update the pull request description to include a summary of changes.'

Restricting allowed tools

Use claude_args to limit which tools Claude can use:

- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    claude_args: '--allowed-tools Bash(gh pr:*)'

You can also expand allowed tools for build/test tasks:

claude_args: '--allowed-tools Bash(npm install),Bash(npm run build),Bash(npm run lint),Bash(npm run test)'

Restricting by PR author

To run the code review only for specific contributors, add an if condition to the job:

jobs:
  claude-review:
    if: |
      github.event.pull_request.user.login == 'external-contributor' ||
      github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'

Restricting to specific file paths

To run the code review only when certain files change:

on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]
    paths:
      - "src/**/*.ts"
      - "src/**/*.tsx"

Security considerations

• The ANTHROPIC_API_KEY is stored as an encrypted GitHub Actions secret and is never exposed in logs.
• All Claude runs appear in the GitHub Actions run history for audit purposes.
• Claude’s default tools are limited to reading and writing files and interacting with the repository (comments, branches, commits).
• The allowed_tools / claude_args option in the workflow file controls which additional tools Claude may use.

Manual setup

If you prefer not to use the installer, you can set up the workflow manually. See the claude-code-action repository for full documentation and advanced configuration options.