claude-code-review.yml
Run a read-only Claude review of a pull request (the code-review plugin). By default, callers run it only on dispatched runs (for @claude review via claude.yml), which posts a consolidated summary. If the caller also enables a pull_request trigger, it can run automatically on PR updates. A direct /review path is available too, but only if the caller also enables issue_comment. claude.yml dispatches it via workflow_dispatch; keep the stub named claude-code-review.yml (or set claude.yml’s review-workflow-file to match) so the dispatch resolves.
Inputs
| Input | Type | Default | Description |
|---|---|---|---|
pr-number |
string | '' |
PR number to review (set by claude.yml’s workflow_dispatch; empty on pull_request runs). |
prompt-addendum |
string | '' |
Repo-specific review guidance appended to the plugin prompt. |
checkout-submodules |
boolean | false |
Check out submodules so the reviewer can read their contents. Private submodules require the SUBMODULES_TOKEN secret. |
allowed-bots |
string | 'github-actions[bot]' |
Comma-separated bot actors the reviewer accepts, so a dispatched review is not rejected as non-human. |
track-progress |
boolean | false |
Enable tag mode: live tracking comment + inline-comment tool on pull_request events. Default false (agent/summary-only mode) is safe. Only set true after anthropics/claude-code-action#1415 ships a read_only input - until then, tag mode exposes git write tools and the reviewer may push commits to the branch. |
show-full-output |
boolean | false |
Show the full JSON output from Claude Code. Turn it on to diagnose a review that fails inside the model call. |
apt-packages |
string | '' |
Space-separated system packages to apt-get install before the review runs (e.g. maxima for a computer algebra system). Empty to skip. |
pip-packages |
string | '' |
Space-separated pip packages to install with pip3 --break-system-packages before the review runs (e.g. sympy). Empty to skip. |
lab-manual |
boolean | true |
Hold the PR to the SERG lab manual (coding style/practices, repository conventions) during review, in addition to correctness. Default true; set false for repos where the R/tidyverse/Quarto-focused manual doesn’t apply (e.g. a GitHub Actions, shell, or docs repo), so the reviewer isn’t handed guidance irrelevant to the diff. |
check-latex-macros |
boolean | false |
Check PR diffs for LaTeX math simplifiable via an existing macro from the d-morrison/macros submodule, and for nontrivial expressions repeated 3+ times that are candidates for a new one. Off by default. The macro checks read definitions only from a locally checked-out submodule (the repo’s pinned version is authoritative), so this only finds real macro definitions when the repo vendors the d-morrison/macros submodule and checkout-submodules: true is also set. |
report-cost |
boolean | true |
Post a follow-up PR comment with the review’s dollar cost (total_cost_usd, summed across the initial attempt and any stub-review retry). See README.md’s feature-parity table for the upstream source citation. Set false to suppress it. |
model |
string | '' |
Model for the reviewer to run on, passed through as the Claude Code CLI’s --model flag (e.g. claude-opus-4-8). Empty (default) falls through to claude-code-action’s own default. Unlike claude.yml, this workflow has no generic claude-args passthrough, so this is the only way to influence the model. |
use-ai-config |
boolean | true |
Install the Morrison-Lab/ai-config plugin (ai-config@Morrison-Lab) alongside the built-in code-review@claude-code-plugins, so the reviewer applies the lab’s shared review conventions rather than only the calling repo’s own CLAUDE.md. Set false to opt out. |
plugin-marketplaces |
string | '' |
Extra newline-separated plugin marketplace Git URLs, added on top of the two this workflow already uses (anthropics/claude-code.git for the code-review plugin, and Morrison-Lab/ai-config.git unless use-ai-config is false). Pair with plugins below; empty adds none. |
plugins |
string | '' |
Extra newline-separated plugin refs to install (<plugin>@<marketplace-name>), added on top of the built-in code-review@claude-code-plugins and ai-config@Morrison-Lab. Each marketplace name must match the name that marketplace declares in its own .claude-plugin/marketplace.json, not the URL given in plugin-marketplaces. |
Secrets
| Secret | Required | Description |
|---|---|---|
CLAUDE_CODE_OAUTH_TOKEN |
no | OAuth token for Claude Code (Claude Max plan). |
ANTHROPIC_API_KEY |
no | Direct Anthropic API key (or GitHub App via /install-github-app), used instead of CLAUDE_CODE_OAUTH_TOKEN. |
SUBMODULES_TOKEN |
no | Read access to private submodules. |
Permissions
Grant contents: read, pull-requests: write, issues: write, and id-token: write, and add either the CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY secret.
Example
# Copy to .github/workflows/claude-code-review.yml in your repo.
# NOTE: requires either CLAUDE_CODE_OAUTH_TOKEN (Claude Max plan) or
# ANTHROPIC_API_KEY (direct API / GitHub App via /install-github-app). Pass
# secrets explicitly (below) rather than via `secrets: inherit`: GitHub only
# inherits secrets into a reusable workflow owned by the same org/user, so a
# cross-owner caller (e.g. a UCD-SERG-org repo calling this d-morrison
# user-owned workflow) inherits an empty token and the run fails env-validation.
# Default: mention-triggered only. claude.yml re-dispatches this workflow on an
# `@claude review` mention (and after an @claude run pushes commits) via
# workflow_dispatch. Keep the file named claude-code-review.yml (or set
# claude.yml's review-workflow-file to match) so the dispatch resolves.
# Optional: uncomment pull_request for automatic review, and uncomment
# issue_comment to allow trusted collaborators to trigger `/review` directly.
name: Claude Code Review
on:
# Optional: enable automatic review on PR activity.
# pull_request:
# types: [opened, synchronize, ready_for_review, reopened]
# Optional: direct on-demand `/review` path (independent of @claude).
# issue_comment:
# types: [created]
workflow_dispatch:
inputs:
pr_number:
description: "Pull request number to review"
required: true
type: string
jobs:
review:
permissions:
contents: read
pull-requests: write
issues: write
id-token: write
uses: Morrison-Lab/gha/.github/workflows/claude-code-review.yml@v2
secrets:
CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} # Max-plan OAuth; empty when using API key
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} # direct API key; empty when using OAuth
SUBMODULES_TOKEN: ${{ secrets.SUBMODULES_TOKEN }} # optional; empty when unset
with:
# Wires the workflow_dispatch input through so claude.yml can re-dispatch
# a review on Claude's commits; empty (and ignored) on pull_request runs.
pr-number: ${{ inputs.pr_number }}
# with:
# checkout-submodules: true # SUBMODULES_TOKEN secret only for private submodules
# allowed-bots: 'github-actions[bot],claude' # accept more bot actors (default: github-actions[bot])
# track-progress: true # tag mode: live tracking comment + inline comments (unsafe until anthropics/claude-code-action#1415 ships)
# lab-manual: false # skip the R/tidyverse SERG lab manual (default true; set false for non-R/Quarto repos)
# apt-packages: maxima # system packages for the reviewer's Bash tool, e.g. a CAS
# pip-packages: sympy # pip packages, e.g. a computer-algebra system for math-heavy repos
# check-latex-macros: true # flag LaTeX simplifiable via d-morrison/macros; also needs checkout-submodules: true
# report-cost: false # suppress the dollar-cost comment (default true)
# model: claude-opus-4-8 # override the reviewer's model (default: claude-code-action's own default)
# use-ai-config: false # skip the Morrison-Lab/ai-config plugin (installed by default)
# plugin-marketplaces: https://github.com/<owner>/<repo>.git # further plugin sources
# plugins: <plugin>@<marketplace-name>
# prompt-addendum: |
# Repo-specific review guidance (e.g. Quarto/R conventions to enforce).See examples/claude-code-review.yml for the full caller stub.