CI/CD Integration
Claude Code runs anywhere a shell does — including GitHub Actions, GitLab CI/CD, and any script that can call a binary. This section covers how to automate Claude in pipelines: reviewing pull requests on every push, generating release notes from tags, and piping build artifacts through Claude for instant analysis.
The key mental model is simple: claude -p "prompt" is a Unix program. It reads stdin, writes stdout, and exits with a status code. Everything else is plumbing.
When to Use CI vs Local
Not every task belongs in a pipeline. The rule of thumb:
| Trigger | Where to run Claude |
|---|---|
| Every PR opened | CI — automated, consistent, no human required |
| Every merge to main | CI — release notes, changelog updates |
| Nightly codebase audit | CI — scheduled cron job |
| Exploring an unfamiliar codebase | Local — interactive, needs back-and-forth |
| Debugging a complex bug | Local — you need to ask follow-up questions |
| Writing a new feature | Local — iterative, context-heavy |
| Quick file analysis from a build artifact | Either — `cat error.log |
The dividing line is interactivity. CI runs are one-shot: you give Claude a prompt, it produces output, the job exits. Local runs are iterative: you refine the prompt, read the response, ask follow-ups.
If you find yourself wanting to reply to what Claude said in CI, run it locally instead.
Decision Table: Which Integration to Use
| GitHub Actions | GitLab CI/CD | Headless (claude -p) | |
|---|---|---|---|
| Best for | GitHub repos, PR automation | GitLab repos, MR automation | Any script, any CI system |
| Setup complexity | Low — official Action | Medium — manual .gitlab-ci.yml | Minimal — just install the CLI |
| Trigger on PR/MR comments | Yes — @claude mentions | Yes — @claude mentions | No — pipeline events only |
| Output destination | PR comments, artifacts | MR comments, artifacts | stdout, files |
| Enterprise providers | AWS Bedrock, Vertex AI | AWS Bedrock, Vertex AI | Inherited from env |
| Cost visibility | GitHub + Anthropic billing | GitLab + Anthropic billing | Anthropic billing only |
Use the GitHub/GitLab Action when you want Claude to respond to comments in PRs and MRs. Use headless mode directly when you want Claude as a step in a broader pipeline that just needs text output — linting, summarizing, extracting structured data.
How CI Automation Works
The trigger flow is the same regardless of platform:
The only required ingredient is ANTHROPIC_API_KEY available as an environment variable. Everything else — install method, trigger type, output destination — is up to you.
Prerequisites (All Platforms)
Before any CI integration works, you need one thing:
ANTHROPIC_API_KEY — your Anthropic API key stored as a CI secret, never hardcoded.
- GitHub: Settings → Secrets and variables → Actions → New repository secret
- GitLab: Settings → CI/CD → Variables → Add variable (mask it)
- Local scripts:
export ANTHROPIC_API_KEY=...in your shell or.env
Without this, every claude -p call will fail with an authentication error.
Pages in This Section
| Page | What you’ll learn |
|---|---|
| GitHub Actions | Using anthropics/claude-code-action@v1, @claude mentions in PRs, PR review and release notes templates |
| GitLab CI/CD | .gitlab-ci.yml jobs, GitLab variable syntax, MR automation |
| Headless Mode | claude -p in depth — pipes, output formats, package.json scripts, --bare for fast CI runs |
Start with Headless Mode if you want to understand the underlying primitive. Start with GitHub Actions or GitLab CI/CD if you want a working integration in 10 minutes.
Related
- Creator Workflows — Boris’s
/loopand/schedulepatterns for local automation - Common Workflows — Everyday prompt patterns that translate directly to CI prompts