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

> Set up Claude Code GitHub Actions: install with /install-github-app, write the @claude workflow, run PR reviews and cron jobs, and cap cost and permissions.

22 October 2026 · Technical · How-to · 7 min read · https://bridge-terminal.com/atlas/blog/claude-code-github-actions-setup-at-claude/

## The short version

- Claude Code GitHub Actions lets anyone with write access mention @claude in an issue or pull request and get an answer or a pushed commit.
- Run /install-github-app from Claude Code for the quick path, or install the app, add a secret and copy one workflow file by hand.
- Giving the action a prompt switches it from waiting for @claude to running on any event, such as a pull request opening or a daily cron.
- Keep permissions narrow, store credentials only as GitHub secrets, and cap each run with --max-turns and workflow timeouts.
- Commits pushed with the default GITHUB_TOKEN do not trigger your CI, so leave that token out of the action's inputs.

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](https://bridge-terminal.com/atlas/blog/claude-code-headless-ci-permissions/).

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

```text
/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](https://github.com/apps/claude) 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:

```yaml
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:

```text
@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:

```yaml
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](https://bridge-terminal.com/atlas/blog/ai-code-review-claude-code-setup/). 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](https://bridge-terminal.com/atlas/blog/claude-code-skills-reusable-commands/) 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:

```yaml
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](https://bridge-terminal.com/atlas/blog/claude-md-best-practices-project-instructions/).
- 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](https://bridge-terminal.com/atlas/blog/claude-code-costs-token-usage-limits/).

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](https://bridge-terminal.com/atlas/) does this on its own board rather than in GitHub workflows. Turning GitHub issues and pull request comments into board tasks is on Atlas's list to build in, so it works without any setup on your side; until then, the `@claude` workflow above is how you act on them from GitHub.

## Questions people ask

### How do I set up Claude Code GitHub Actions?

Open claude in your repository and run /install-github-app, then merge the pull request it prepares. Alternatively install the Claude GitHub App, add ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN as a repository secret, and copy examples/claude.yml into .github/workflows/. Either way you need admin access to the repository.

### Can I use my Claude Pro or Max subscription instead of an API key?

Yes. Run claude setup-token locally, store the result as the CLAUDE_CODE_OAUTH_TOKEN secret and pass it as claude_code_oauth_token. Runs then use your subscription instead of API billing, but the token is tied to the person who generated it, so the docs recommend an API key for secrets shared across an organisation.

### Who can trigger @claude in a repository?

By default the commenting user needs write access, and bot actors are rejected unless listed in allowed_bots. You can allow specific users without write access with allowed_non_write_users and your own github_token.

### Why doesn't my CI run on the commits Claude pushes?

GitHub does not trigger workflows for commits made with the default GITHUB_TOKEN. Remove that token from the action's inputs so it acts as the Claude GitHub App, or pass a custom app token.

### How do I stop a Claude workflow from costing too much?

Set --max-turns in claude_args, add workflow timeouts and concurrency limits, write specific requests and keep CLAUDE.md short. Each run also consumes GitHub Actions minutes.

## About Atlas: Review and checks without writing workflow files

A GitHub workflow gives you review and checks only after you build and tune it. Atlas reviews every build as it finishes, returns it releasable or files fix tasks to its builder, and its landing train runs the project's own checks once on up to six merged branches. It does this on its own board, not through GitHub Actions. Turning GitHub issues and pull request comments into board tasks is on Atlas's list to build in, so it works without any setup on your side; until then, the @claude workflow is how you act on them from GitHub. — https://bridge-terminal.com/atlas/

## Sources

- [Claude Code GitHub Actions (Claude Code docs)](https://code.claude.com/docs/en/github-actions)
- [anthropics/claude-code-action (GitHub)](https://github.com/anthropics/claude-code-action)

_Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._