Headless and CI/CD
Run Claude Code in non-interactive workflows with clear inputs, outputs, and guardrails.
Headless Claude Code works best when the task is narrow and the expected output is machine-readable or easy to review.
Good Headless Tasks
- Generate a changelog summary from a known diff.
- Run a focused code review and return findings.
- Update a repetitive documentation section.
- Classify test failures with logs as input.
- Produce a patch in a temporary branch for human review.
Avoid headless execution for broad architectural work unless a human will review each step.
Invocation Contract
Define input, output, and permissions:
claude -p "Review this diff for locale routing regressions. Return JSON findings only."For scripts, prefer stable flags and structured output. Record the model, version, and command in CI logs so failures can be reproduced.
CI Guardrails
- Run in a clean checkout.
- Use least-privilege credentials.
- Block production writes unless explicitly approved.
- Store generated patches as artifacts.
- Require human review before merge.
- Fail closed when configuration cannot be loaded.
Output Review
Headless output should answer:
- What files or commits were inspected?
- What exact issue was found?
- What evidence supports it?
- What command or test confirms the result?
If the output cannot support those questions, narrow the prompt or add structured reporting.