What you will be able to do
- Wire Claude into a GitHub or GitLab workflow and tell interactive mode apart from automation mode
- Configure Code Review triggers and severity rules, and predict what each trigger costs
- Run a code review locally or in CI with the /code-review command and its flags
- Plan a small, behaviour-preserving refactor and put together the tools for a larger one
1.Version control and CI: where Claude joins the pipeline
Claude fits into the software lifecycle through the same places your team already works: the repository, its pull or merge requests, and the CI runner. On GitHub, setup has three parts: install the Claude GitHub App, add an authentication secret (ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN), and add a workflow file. Running /install-github-app from Claude Code does all three and opens the workflow pull request for you. The app asks for read and write access to Contents, Issues and Pull requests, so it can change files, answer issues, and create PRs and push changes. The Claude Code GitHub Action is built on the Agent SDK.
| Mode | When it applies | Where results appear |
|---|---|---|
| Interactive mode | The workflow provides no prompt input; Claude waits for the trigger phrase (@claude by default) | As a comment on the triggering issue or PR |
| Automation mode | The workflow provides a prompt input; Claude runs without waiting for a mention | In the workflow run log by default, unless the prompt directs Claude to post and it has a tool that can |
Two guards stop the pipeline from running unattended in unintended ways. On issue and pull request events, the user who triggers the run needs write access to the repository. And on every event, a bot actor is rejected unless it is listed in allowed_bots, which stops bots from triggering Claude in a loop.
GitLab follows the same pattern: one job in .gitlab-ci.yml plus a masked ANTHROPIC_API_KEY CI/CD variable. The job runs in your own GitLab runners, under your branch protection and approvals, and every change Claude makes arrives as a merge request, so reviewers see the diff before anything lands. Locally, Claude Code can run parallel sessions in git worktrees, which keeps concurrent edits from colliding.
Removing the integration is its own lifecycle step. Deleting the workflow files stops the Action. Deleting the repository secret does not revoke the key it held; to retire an API key entirely, you also delete it in the Claude Console.
2.Managed Code Review: triggers, severity and REVIEW.md
Code Review runs an automatic review on pull requests without you writing a workflow. You choose a trigger for each repository, and that choice sets how often reviews run, and so what they cost.
| Trigger | When a review runs | Cost effect |
|---|---|---|
| Once after PR creation | When a PR is opened or marked ready for review | Runs once per PR |
| After every push | On every push to the PR branch; auto-resolves threads when flagged issues are fixed | Multiplies cost by the number of pushes |
| Manual | Only when someone comments @claude review or @claude review always | Cost accrues only from reviews someone requests |
The manual command has a few requirements. It must be a top-level PR comment, not an inline comment on a diff line. It has to start the comment. You need write, maintain or admin permission. And the PR must be open. @claude review runs a single review, while @claude review always also subscribes the PR to reviews on later pushes. Clicking Re-run on the check run does not start a review.
Findings come with a severity: 🔴 Important is a bug to fix before merging, 🟡 Nit is minor and not blocking, and 🟣 Pre-existing is a bug already in the codebase that the PR did not introduce. You set the policy in two files. CLAUDE.md holds shared project instructions, and Code Review flags newly introduced violations of it as nits. REVIEW.md holds review-only instructions: what to flag, at what severity, and how to report it. The documented example saves Important for findings that break behaviour, leak data or block a rollback, including migrations that aren't backward compatible, and caps style, naming and refactoring suggestions at Nit.
## Do not report
- Anything CI already enforces: lint, formatting, type errors
- Generated files under `src/gen/` and any `*.lock` file
- Test-only code that intentionally violates production rulesSources4
3.Running /code-review locally and in a workflow
You can also run a review yourself with the /code-review command. In a terminal session it runs as a forked subagent, so you can keep working while it runs. --fix applies the findings to your working tree. --comment posts them as inline comments on a GitHub pull request, or as a single note on a GitLab merge request. In non-interactive runs (the -p flag or the Agent SDK), Claude Code waits for the review and returns the findings in its response. The exception is ultra, which starts a cloud review and returns without waiting.
The same command runs inside CI. In the documented GitHub Actions review workflow, a pull_request event triggers the action, the code-review plugin is installed, and /code-review is passed as the prompt. Passing a prompt puts the workflow in automation mode.
- 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"'It does not. With --comment, Claude posts an inline comment for each issue it finds, or a single summary comment when it finds none. Without it, Claude posts nothing and the findings only appear in the workflow run log. The claude_args line gives Claude exactly the tool it needs to post those inline comments.
A platform team is deciding how to run an automated code-fixing agent as part of their CI/CD pipeline, where the agent must run unattended, scale across many concurrent pipeline jobs, and integrate with existing deployment infrastructure. Which option is the best fit according to Anthropic's guidance on choosing between the CLI and the SDK?
Correct answer: A — Use the Agent SDK, since it is recommended for production automation and CI/CD pipelines while the CLI is better suited to interactive, one-off development sessions
- A. Correct. Anthropic's comparison explicitly lists CI/CD pipelines and production automation as SDK use cases, while the CLI is recommended for interactive development and one-off tasks.
- B. Incorrect. The guidance places CI/CD pipelines under SDK use cases, not the CLI, which is intended for interactive and one-off use.
- C. Incorrect. The Client SDK requires the team to implement the tool execution loop themselves; it is not described as the recommended CI/CD pattern when the Agent SDK already provides that loop.
- D. Incorrect. The two are differentiated by intended use case, not treated as interchangeable at random for automated pipelines.
4.Refactoring, small and large
The documented refactoring recipe is a small, test-guarded loop. Claude finds the legacy code, suggests how to modernise it, applies the change while keeping behaviour the same, and then runs the tests. The prompts in the docs follow that sequence: "find deprecated API usage in our codebase", "suggest how to refactor utils.js to use modern JavaScript features", "refactor utils.js to use ES2024 features while maintaining the same behavior", then "run tests for the refactored code". Two tips turn this into a discipline: ask for backward compatibility when you need it, and refactor in small, testable increments.
The sources give no dedicated recipe for large-scale refactoring. What they do give is a set of building blocks that scale the same loop up. The deprecated-API search already covers the whole codebase. Plan mode lets you review changes before they touch disk. Subagents can take on research so your main context stays clean. Parallel sessions in worktrees keep concurrent edits from colliding. Code review is the last check. The REVIEW.md example marks refactoring suggestions as Nit at most, but ranks as Important a migration that isn't backward compatible, and that is exactly the risk a large refactor carries.
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.The After every push trigger costs about the same as reviewing once per PR, because only the changed lines are reviewed again.Why is that wrong?
After every push runs a full review on each push, so the cost multiplies by the number of pushes. Once after PR creation runs only once per PR.
Covered in Managed Code Review: triggers, severity and REVIEW.md
2.Commenting @claude review on a PR in a Manual repository makes Claude review every later push too.Why is that wrong?
@claude review runs one review only. Subscribing the PR to reviews on later pushes takes @claude review always.
Covered in Managed Code Review: triggers, severity and REVIEW.md
3.Deleting the ANTHROPIC_API_KEY repository secret revokes the key when you remove the GitHub integration.Why is that wrong?
Deleting the secret removes only the stored copy, and the key it held keeps working. To retire the key, you also delete it in the Claude Console.
Covered in Version control and CI: where Claude joins the pipeline
Practise it for real
Set up a repository review policy and run it on a local diff before a pull request exists
1.Create a REVIEW.md at the repository root that contains the documented "## Do not report" block.
Why: REVIEW.md holds review-only instructions for the agents that find, verify and report findings.
You should see: A committed REVIEW.md that tells reviewers to skip lint, formatting and type errors that CI already enforces.
2.Make a small refactor on a branch, run your tests, then run /code-review in a Claude Code terminal session.
Why: In a terminal session the review runs as a forked subagent against your local diff.
You should see: Findings tagged 🔴 Important, 🟡 Nit or 🟣 Pre-existing, with no lint or formatting complaints.
3.Run /code-review --fix.
Why: --fix applies the findings to your working tree after the review, so you can inspect them with git diff.
You should see: Uncommitted changes in your working tree that address the findings.
4.Push the branch, open a pull request, and comment @claude review as a top-level comment on it.
Why: In a repository with the Manual trigger, this runs one review without subscribing the PR to later pushes.
You should see: A Claude Code Review check run whose Details list every finding with its file, line and summary.
Stuck? Get a nudge
If nothing happens after the comment, check that it is a top-level PR comment rather than an inline one, that the command starts the comment, and that you have write permission on the repository.
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/github-actionsOfficial docs
“Automation mode: when the workflow provides a prompt input, Claude runs without waiting for a mention”
↩︎ Version control and CI: where Claude joins the pipeline“rejects a bot actor unless you list it in allowed_bots, which keeps bots from triggering Claude in a loop”
↩︎ Version control and CI: where Claude joins the pipeline“Without it, Claude posts nothing, and you read the findings in the workflow run log.”
↩︎ Running /code-review locally and in a workflow“If you delete a secret, the credential it held stays valid.”
↩︎ Exam trap 3 - 2.https://code.claude.com/docs/en/gitlab-ci-cdOfficial docs
“Every change flows through an MR so reviewers see the diff and approvals still apply.”
↩︎ Version control and CI: where Claude joins the pipeline - 3.https://code.claude.com/docs/en/common-workflowsOfficial docs
“Run parallel sessions with worktrees”
↩︎ Version control and CI: where Claude joins the pipeline“refactor utils.js to use ES2024 features while maintaining the same behavior”
↩︎ Refactoring, small and large“Do refactoring in small, testable increments”
↩︎ Refactoring, small and large“Plan before editing to review changes before they touch disk”
↩︎ Refactoring, small and large - 4.https://code.claude.com/docs/en/code-reviewOfficial docs
“REVIEW.md: review-only instructions, given to the agents that find and verify findings”
↩︎ Managed Code Review: triggers, severity and REVIEW.md“Code Review reads it as project context and flags newly introduced violations as nits.”
↩︎ Managed Code Review: triggers, severity and REVIEW.md“--fix: applies the findings to your working tree after the review”
↩︎ Running /code-review locally and in a workflow“Reserve Important for findings that would break behavior, leak data,”
↩︎ Refactoring, small and large“After every push: runs on each push, multiplying cost by the number of pushes”
↩︎ Exam trap 1“Starts a single review without subscribing the PR to future pushes”
↩︎ Exam trap 2