> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/jackdog668/claude-code/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
claude install-github-app
```

This interactive command walks you through:

<Steps>
  <Step title="Authenticate with GitHub">
    The installer checks that you are authenticated with the GitHub CLI (`gh`). If not, it prompts you to log in.
  </Step>

  <Step title="Choose a repository">
    Select the repository to set up, or use the current repository if you are already inside one.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Select workflows">
    Choose which workflows to install: the Claude PR assistant workflow, the Claude Code Review workflow, or both.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

## 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`

```yaml theme={null}
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`

```yaml theme={null}
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:

```bash theme={null}
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               |

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

## Customizing the workflow

### Custom prompt

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

```yaml theme={null}
- 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:

```yaml theme={null}
- 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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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](https://github.com/anthropics/claude-code-action) for full documentation and advanced configuration options.