skip to content

CI & Pull Request Review

The GitHub Action answers @claude mentions or runs a set prompt, GitLab jobs open merge requests, and managed Code Review posts severity-tagged findings. Asked because CI gives an agent write access.

part ofClaude Coderead it →
on this pageshow

explore

questions

6

How does anthropics/claude-code-action@v1 choose between @claude interactive mode and automation mode, and what changes between the two?

level: middleimportance: must knowfreq 26%

answer

  1. one input decides the mode
  2. no prompt means wait for a mention
  3. trigger_phrase, default @claude
  4. comment versus workflow run log
  5. tools granted through claude_args

basics

~20 s

The action's prompt input decides: without it, Claude waits for the trigger phrase, @claude by default, and replies in a comment; with it, Claude runs on the workflow's event and reports in the workflow run log by default.

solid answer

~50 s

In `anthropics/claude-code-action@v1` there is no mode switch: the `prompt` input decides. **Interactive mode** (no `prompt`) waits for `@claude`, or whatever `trigger_phrase` sets, in an issue or PR comment, a PR review, or the body or title of a newly opened issue, and posts progress and results as a comment it keeps updating. **Automation mode** (`prompt` set, as plain text or a `/skill-name`) runs on any event the workflow listens to, including a `schedule`, and by default reports in the workflow run log; it posts to the PR only when the prompt says so and Claude has a tool that can post. A plain-text prompt has no shell or GitHub API access until you grant it, with `--allowedTools` in `claude_args` or a `permissions.allow` rule in the `settings` input. `claude_args` takes any Claude Code CLI flag, such as `--max-turns` or `--model`.

code

yaml · 7 lines
yaml
- uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    prompt: "Summarize yesterday's commits and open issues"
    claude_args: |
      --max-turns 10
      --allowedTools "mcp__github__list_commits,mcp__github__list_issues"

go deeper

for a junior

Remember that the prompt input decides the mode: no prompt means Claude waits for @claude, a prompt means it runs on the event.

for a middle

Explain where each mode reports, how claude_args forwards CLI flags such as --max-turns and --allowedTools, and why a plain-text prompt needs tools granted.

for a senior

Diagnose silent failures: an inline-comment server never started, findings left in the run log, a skill missing because checkout ran after the action.

for a principal

Decide which jobs deserve automation mode on every pull request against on-demand mentions, given per-run token cost and the write access each run holds.

## One input decides The Claude Code GitHub Action, `anthropics/claude-code-action@v1`, runs Claude Code as a step in a GitHub Actions workflow. It has two ways of working, and you never name them: the action **detects the mode** from its configuration. The deciding input is `prompt`. | | Interactive mode | Automation mode | | - | - | - | | Selected by | no `prompt` input | a `prompt` input (plain text or a skill) | | Starts when | the trigger phrase appears | the workflow's event fires | | Default output | a comment on the issue or PR | the workflow run log | | Typical use | `@claude fix the failing test` | review every PR, a nightly report | Both modes run the same **checks on who triggered the run** before Claude starts; automation mode does not skip them. ## Interactive mode With no `prompt`, Claude waits for the **trigger phrase**, `@claude` unless the `trigger_phrase` input changes it. It looks for the phrase in an issue or pull request comment, a pull request review, or the body or title of a newly opened issue, and it must appear as a complete word: `/claude` or `@claude-bot` does not count. The workflow's own `if: contains(github.event.comment.body, '@claude')` only saves runner minutes on unrelated comments; the action checks the phrase again itself. Claude answers in a comment on the same issue or PR and updates it as it works, which is why the example workflow grants `pull-requests: write` and `issues: write`. ## Automation mode With `prompt` set, Claude runs as soon as the event fires, on a pull request opening, a push or a `schedule`, with nobody mentioning it. Three things trip people up: - **Output goes to the run log by default.** Claude posts to the issue or PR only when the prompt directs it to and it has a tool that can post. - **A plain-text prompt starts with no shell or GitHub API access.** Grant the tools it needs with `--allowedTools` in `claude_args` or with a `permissions.allow` rule in the `settings` input. A **skill** prompt (`/skill-name` from `.claude/skills/`, or `/plugin-name:skill-name` from a plugin installed with `plugin_marketplaces` and `plugins`) can use the tools its `allowed-tools` frontmatter grants. - **A repository skill needs a checkout.** Run `actions/checkout` before the action so the skill files exist on the runner. ## claude_args and settings `claude_args` passes **any Claude Code CLI argument** to the run; the `settings` input takes Claude Code settings as a JSON string or a file path. Common arguments: 1. `--max-turns` to cap how many turns a run may take, a per-run cost control that pairs with a workflow-level timeout; 2. `--model` to pick a model instead of Claude Code's default; 3. `--allowedTools` (alias `--allowed-tools`), a comma-separated list of tools that run without a prompt; 4. `--mcp-config` to load MCP servers from a file; 5. `--debug` for verbose output. A trap in the shipped review workflow: the `code-review` plugin's skill already names the inline-comment tool in its `allowed-tools`, yet the workflow keeps `claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'`, because the action **starts the MCP server that posts inline comments only when `--allowedTools` in `claude_args` names it**. Drop that line and the review posts nothing inline. The skill's `--comment` argument is the other half: without it, findings stay in the run log. ## Bounding each run Every run costs GitHub Actions minutes on the runner plus model usage: API tokens with `anthropic_api_key`, or the subscription's usage with `claude_code_oauth_token`. The documented levers are: - `--max-turns` in `claude_args`, so a confused run stops instead of iterating; - a workflow-level timeout for runaway jobs, and GitHub's concurrency controls to limit parallel runs; - specific `@claude` requests and issue templates, so Claude needs fewer turns; - a concise `CLAUDE.md`, because Claude reads it on every run. ## Upgrading from @beta The mode detection replaced explicit configuration in the beta. To move a workflow from `anthropics/claude-code-action@beta`: 1. change `@beta` to `@v1` in the `uses` line; 2. remove the `mode` input; 3. rename `direct_prompt` to `prompt`; 4. move CLI options such as `max_turns` and `model` into `claude_args`; `custom_instructions` has no same-name flag and becomes `--append-system-prompt`. When you read an unfamiliar v1 workflow, then, look for `prompt` first: its presence alone tells you whether Claude waits for a mention or acts on every matching event.

  • A review workflow runs the code-review skill with --comment, but no inline comments ever appear on the pull request. What is missing?
    Most likely the `claude_args` line `--allowedTools "mcp__github_inline_comment__create_inline_comment"`. The action starts the MCP server that posts inline comments only when `--allowedTools` in `claude_args` names it, even though the skill's own `allowed-tools` frontmatter lists the same tool. Without the server, Claude has no tool to post with.
  • A scheduled automation run reports it cannot run git commands or read issues. Why, and what do you change?
    A plain-text prompt in automation mode starts with no shell or GitHub API access. Grant exactly what the job needs: `--allowedTools` in `claude_args`, such as two GitHub MCP list tools, or a `permissions.allow` rule in the `settings` input. Alternatively invoke a skill, whose `allowed-tools` frontmatter grants its tools.
  • What changes when you migrate a workflow from anthropics/claude-code-action@beta to @v1?
    Switch `@beta` to `@v1`, delete the `mode` input because v1 detects the mode, rename `direct_prompt` to `prompt`, and move CLI options such as `max_turns` and `model` into `claude_args`. `custom_instructions` has no same-name flag and becomes `--append-system-prompt`.

  • In v1 you set a mode input to pick interactive or automation
  • Automation mode always posts its result as a PR comment
  • A plain-text automation prompt can run any shell command by default
  • Automation mode skips the checks on who triggered the run
  • claude_args accepts only --model and --max-turns
open as a page

What does the Claude Code GitHub Action do, and what does /install-github-app set up in a repository?

level: juniorimportance: should knowfreq 30%

basics

~20 s

anthropics/claude-code-action@v1 runs Claude Code inside a repository's GitHub Actions workflows, answering @claude mentions or running a set prompt. /install-github-app installs the Claude GitHub App, saves an auth secret and opens a pull request adding the workflow.

open as a page

Claude Code Review left an Important finding on a pull request, yet the PR merged under branch protection. Why, and how would you gate merges on its findings?

level: seniorimportance: should knowfreq 9%

basics

~20 s

Code Review never approves or blocks a pull request: its Claude Code Review check run always ends neutral, so branch protection cannot fail on it. To gate merges, your own CI parses the check run's severity counts and fails on Important.

open as a page

Who can trigger a run of anthropics/claude-code-action@v1, and how do you widen that set safely for outside contributors or bots?

level: seniorimportance: should knowfreq 14%

basics

~20 s

Before Claude starts, the action checks the triggering actor: on issue and PR events the user needs write access, and bot actors are rejected unless listed in allowed_bots. allowed_non_write_users, with your own github_token, admits named users without write access.

open as a page

How do you run Claude Code in a GitLab CI/CD job, and why doesn't an @claude comment start that job by itself?

level: middleimportance: nice to knowfreq 7%

basics

~20 s

In GitLab you add a job to .gitlab-ci.yml that installs Claude Code and runs claude -p with pre-approved tools, using a masked ANTHROPIC_API_KEY variable. A comment starts nothing until your webhook listener calls the pipeline trigger API.

open as a page

In Claude Code Review, how do REVIEW.md and CLAUDE.md differ in shaping what a pull request review flags?

level: middleimportance: nice to knowfreq 6%

basics

~20 s

CLAUDE.md is project context for every Claude Code task, and Code Review flags new violations of it as nits. REVIEW.md, at the repository root, is review-only instruction for the reviewing agents: severity definitions, nit caps, skip rules, mandatory checks.

open as a page