Claude Code GitHub Actions: Set Up @claude on Your Repo

Claude Code GitHub Actions runs Claude Code inside your repository's workflows, so a teammate can write @claude fix the TypeError in the dashboard on an issue and have Claude work on it and push the change. You can set it up with /install-github-app, or by hand with one secret and one YAML file. This guide covers both paths, the workflows worth having, and the limits that keep cost and risk down.

Everything below comes from Anthropic's documentation for the claude-code-action. If you want the general headless pattern outside GitHub, see Claude Code Headless in CI.

What does the Claude Code GitHub Action do?

It is a GitHub Action (anthropics/claude-code-action) that starts Claude Code on a GitHub-hosted runner. It works in two modes, chosen by your workflow configuration:

• Interactive mode: the workflow has no prompt input. Claude waits for the trigger phrase, @claude by default, in an issue or pull request comment, a pull request review, or the title or body of a new issue. Progress and results appear as a comment on that issue or PR.
• Automation mode: the workflow has a prompt input. Claude runs without waiting for a mention, on whatever event you chose. By default results go to the workflow run log, not a comment.

Use interactive mode for "help me with this" requests and automation mode for things you want on every pull request or every morning.

How do I install it?

You need admin access to the repository either way.

Quick setup with /install-github-app

Install and sign in to the GitHub CLI (gh auth login), open claude in the repository, and run:

/install-github-app

Follow the prompts. Claude Code installs the Claude GitHub App, then stores a credential as a repository secret. It reuses an existing API key if it has one; otherwise you choose between a long-lived token from your Claude subscription and a pasted API key. The secret is named ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN. It then pushes a branch with the workflow files you picked and opens GitHub with a pull request ready to create. Merge that pull request and @claude works.

Two limits: the command works only with github.com repositories (GitLab and Bitbucket remotes get a notice and exit), and pressing Esc stops setup after the current step finishes.

Manual setup

1. Install the Claude GitHub App on the repository. The action relies on three of its permissions: Contents, Issues and Pull requests, all read and write.
2. Add a repository secret. Use ANTHROPIC_API_KEY (a key from the Claude Console) or CLAUDE_CODE_OAUTH_TOKEN (generated locally with claude setup-token, available on Pro, Max, Team and Enterprise).
3. Copy examples/claude.yml from the action's repository into .github/workflows/. If you use the OAuth token, change the anthropic_api_key line to claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}.

Then test it by tagging @claude in an issue.

One thing to know before you approve: GitHub does not let you accept a subset of an app's permissions. The official app requests a wider set than this action uses (including Actions, Checks, Workflows and Discussions). If your organisation wants only Contents, Issues and Pull requests, the docs say to create a custom GitHub App. That covers only this action; Code Review and web auto-fix still need the official app.

What does a working @claude workflow look like?

This is the documented interactive workflow:

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 }}

The non-boilerplate parts:

• id-token: write is required for the action's default GitHub App authentication.
• actions: read lets Claude read CI results on pull requests.
• actions/checkout gives Claude a local copy of the code.
• The if line stops runners from starting on comments that do not mention @claude.

Then write requests like these in a comment:

@claude implement this feature based on the issue description
@claude how should I implement user authentication for this endpoint?
@claude fix the TypeError in the user dashboard component

Specific requests need fewer turns, which matters for cost (more below).

Who can trigger it?

Before Claude starts, the action checks the actor. On issue and pull request events the user must have write access; you can list exceptions in allowed_non_write_users, which needs your own github_token. Bot actors are rejected unless listed in allowed_bots, which keeps bots from triggering Claude in a loop. The bot check also applies to scheduled runs, which GitHub attributes to a repository user, usually whoever last changed the cron line.

How do I run a code review on every pull request?

Give the action a prompt. The docs show a workflow that installs the code-review plugin and runs its skill whenever a pull request is opened, updated, reopened or marked ready:

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

Two details trip people up. Without --comment, Claude posts nothing and the findings sit in the run log. And keep the claude_args line even though the skill names the same tool, because the inline-comment server only starts when --allowedTools names it. Claude skips draft and closed pull requests, ones it judges trivial or automated, and ones that already carry a comment from Claude. On public repositories, GitHub withholds secrets from fork pull requests, so this runs only for branches in the same repository.

For what a review like this does and does not catch, read AI Code Review with Claude Code. If you do not want to maintain a workflow file at all, the docs point to the separate Code Review product.

The prompt can also be a skill from your own .claude/skills/ directory. Run actions/checkout first so the files are on the runner, then pass /skill-name. See Claude Code Skills for writing one.

Can it run on a schedule?

Yes. With a prompt and a cron trigger, the action runs in automation mode. A plain-text prompt gets no shell or GitHub API access until you grant tools with --allowedTools in claude_args or a permissions.allow rule in the settings input. This daily report, which runs at 09:00 UTC, uses two GitHub MCP tools, so it needs no checkout:

name: Daily Report
on:
  schedule:
    - cron: "0 9 * * *"
jobs:
  report:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: read
      id-token: write
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: "Generate a summary of yesterday's commits and open issues"
          claude_args: |
            --model claude-opus-5-5
            --allowedTools "mcp__github__list_commits,mcp__github__list_issues"

GitHub runs scheduled workflows only from the default branch, and in public repositories disables the schedule after 60 days without repository activity.

How do I control cost?

Each run uses GitHub Actions minutes and, with an API key, API tokens. With an OAuth token, runs use your Claude subscription instead of API billing. The docs list these levers:

• Write specific @claude requests, and use issue templates to give context up front.
• Keep CLAUDE.md concise, since Claude reads it on every run. Put review criteria and code style there; see CLAUDE.md Best Practices.
• Set --max-turns in claude_args, for example claude_args: "--max-turns 5 --model claude-sonnet-5".
• Set workflow-level timeouts and use GitHub's concurrency controls to limit parallel runs.

More general token tactics are in Claude Code Costs.

One caution on the OAuth option: the token is tied to the subscription of whoever ran claude setup-token. For a secret shared across an organisation, the docs recommend an API key. To avoid a long-lived secret entirely, the action supports workload identity federation through the anthropic_federation_rule_id and anthropic_organization_id inputs, with id-token: write. Amazon Bedrock, Google Cloud's Agent Platform and Microsoft Foundry are supported through use_bedrock, use_vertex and use_foundry.

Why is my CI not running on Claude's commits?

The usual cause: GitHub does not trigger workflows on commits made with the default GITHUB_TOKEN. If you pass github_token: ${{ secrets.GITHUB_TOKEN }} to the action, remove it so it authenticates as the Claude GitHub App, or pass a custom app token. Also check that your CI triggers include the events Claude's pushes produce, such as push or pull_request.

If Claude does not respond at all, check that the app is installed, workflows are enabled, the secret exists, the comment contains @claude as a whole word (not /claude or @claude-bot), and the commenter has write access.

A safe starting configuration

1. Start with the review workflow only, with read permissions, and watch a week of comments.
2. Add the @claude workflow once you trust the review output, and keep branch protection so a human merges.
3. Never commit keys; use GitHub Secrets only.
4. Cap every job with --max-turns and a timeout.
5. Upgrade old @beta workflows to @v1: replace direct_prompt with prompt, drop mode, and move max_turns and model into claude_args.

Conclusion

The setup is small: one app, one secret, one or two workflow files. The limits matter more than the setup: narrow permissions, a turn cap, a concise CLAUDE.md, and a human who still merges.

If you want review and checks across a whole project without writing workflow files, Atlas does this on its own board rather than in GitHub workflows.