# Claude Code on your pull requests

The Claude Code action runs the agent inside a GitHub workflow, either waiting for an @claude mention or running a prompt on any event. Setup is short; the access and secret choices are where it goes wrong.

## Two ways to run it

`anthropics/claude-code-action@v1` runs Claude Code inside a workflow. How it behaves depends on one input.

With no `prompt`, it is interactive. It reacts when someone writes `@claude` in a pull request or issue, and does what that comment asks.

With a `prompt`, it runs in automation mode on whatever event you attach it to: a pull request opening, a label, a cron schedule. Nobody asks. The workflow file is the request.

```flow
An event fires: PR, issue, comment, cron
The workflow starts the action
The action runs Claude with the repo checked out
Claude reads, edits and comments through GitHub
The result lands as a comment or a commit
```

It is the same agent you run locally, working through the GitHub runner instead of your machine.

## Setting it up

The quick route is `/install-github-app` inside Claude Code. It works on github.com only, needs `gh` to be logged in, and needs admin rights on the repository.

Then the workflow needs a credential. Two secrets work: `ANTHROPIC_API_KEY`, or `CLAUDE_CODE_OAUTH_TOKEN`, which you create with `claude setup-token`. The choice matters for teams. An API key suits a secret shared across an organization. An OAuth token belongs to one person's subscription, so a whole team running on it is running on one person's account.

If you would rather hold no long-lived secret at all, workload identity federation is supported. It uses inputs such as `anthropic_federation_rule_id` and needs the `id-token: write` permission. Cloud providers are switched with `use_bedrock`, `use_vertex` or `use_foundry`, all through OIDC.

**Question:** Your whole team will trigger the action. Which credential fits better, and why?

- A personal OAuth token, because it is free
- An API key, because an OAuth token belongs to one person's subscription
- No credential, the action works without one
- The GITHUB_TOKEN of the repository

**Answer:** An API key, because an OAuth token belongs to one person's subscription. For an organization-wide shared secret the docs point to an API key. An OAuth token is tied to one person's subscription.


## Passing options through

`claude_args` takes any CLI flag, which is where the limits from the headless lesson come back. For example `--max-turns 5` stops a run that wanders, and `--model` picks the model. Treat this field as the place you bound the job.

CLAUDE.md is read on every run, so a long one is paid for on every pull request. Keep it short.

> **Name the inline-comment server**
The server that posts inline review comments only starts if `--allowedTools` in `claude_args` names it. This is true even when the skill's own frontmatter names it too. If inline comments never appear, check this first.


## Who can trigger it

The user who triggers the action needs write access to the repository. Bot actors are rejected unless you list them in `allowed_bots`.

Scheduled runs have a subtle rule: they are attributed to whoever last edited the cron line. If that person was a bot, the run is rejected unless the bot is allowed. Also, GitHub disables schedules in public repositories after 60 days without activity, so a quiet repo's nightly job can stop without any error from Claude.

> **A detail that stops your CI**
If you pass `github_token: secrets.GITHUB_TOKEN`, CI does not run on Claude's commits. GitHub ignores events created by that token. If you want your checks to run on what Claude pushes, do not use it.


## What to put in the prompt

Because automation mode has no human to correct it, the prompt carries the whole task and its boundary. A review prompt that works says what to look at, what to ignore and where to stop, for example: review the diff for missing error handling, comment only on lines that changed, do not edit files. An open-ended prompt on a cron schedule is the same problem as an unbounded script loop.

> **The names changed once**
The old `@beta` action was replaced by `@v1`. `direct_prompt` became `prompt`, and `custom_instructions` became `--append-system-prompt` inside `claude_args`.


> **Start with comments only**
Install the app on a test repository, open a pull request, and comment `@claude explain what this change does`. Once that works, add a workflow with a `prompt` that reviews every new PR, and read the first few results before you trust it.


**Question:** Claude pushed a commit but your CI checks did not run. What is the likely cause?

- The workflow used github_token: secrets.GITHUB_TOKEN
- The prompt was too long
- The action was set to interactive mode
- The API key expired

**Answer:** The workflow used github_token: secrets.GITHUB_TOKEN. GitHub ignores events created by the GITHUB_TOKEN, so commits pushed with it do not trigger other workflows.