Headless Mode
Claude Code runs in headless (non-interactive) mode using the --print flag or the -p shorthand. In this mode, it receives a prompt, processes it, and outputs the result — no interactive terminal required. This is the foundation for CI/CD integration.
In headless mode, Claude Code cannot ask for human approval. All tools must be pre-approved via --allowedTools or the permission system must be configured to allow necessary operations.
CI/CD Patterns
Common CI/CD patterns include: automated code review on pull requests (Claude reviews the diff and posts comments), PR description generation (Claude summarizes changes), test generation (Claude writes tests for changed files), and automated fixes (Claude fixes linting errors or type issues).
These patterns typically use GitHub Actions, GitLab CI, or similar CI systems to trigger Claude Code when a PR is opened or updated.
Security Considerations
CI/CD environments require careful security configuration. Use restricted API keys with appropriate usage limits. Pre-approve only the tools needed for the specific task. Run Claude Code with minimal file system access. Never store API keys in code — use CI/CD secrets management.
For PR review, Claude Code typically needs read-only access to the repository. For automated fixes, it needs write access to specific files. Scope permissions to the minimum required.
Key Concept
Headless Mode Requires Pre-Configured Permissions
In CI/CD, there is no human to approve actions. Every tool Claude Code needs must be pre-approved before execution. This means your CI/CD configuration must explicitly list allowed tools, and you should deny everything else by default. The --allowedTools flag and project settings are your primary controls.
Exam Traps
Using --dangerously-skip-permissions without safeguards
This flag disables all permission checks. In CI/CD, use --allowedTools instead to grant specific, scoped permissions.
Not setting token/cost limits
A runaway CI job can consume significant API credits. Always set max token limits and cost caps for CI/CD usage.
Storing API keys in code or CI config files
Use CI/CD platform secrets management. Never commit API keys to the repository or include them in plain text in CI configuration files.
Check Your Understanding
You want to add automated code review to your GitHub Actions pipeline. Claude Code should review PRs and post comments but never modify files. Which configuration is correct?
Build Exercise
Set Up CI/CD Code Review
What you'll learn
- Configure Claude Code for headless execution
- Set up GitHub Actions with Claude Code
- Scope permissions for CI/CD
- Handle API key management securely
Write a Claude Code command that runs in headless mode, reads a diff, and outputs a code review. Test it locally with a sample diff.
WHY: Validating the headless command locally before CI setup saves debugging time.
YOU SHOULD SEE: Claude Code processes the diff and outputs review comments without interactive prompts.
Create a GitHub Actions workflow file that triggers on pull requests and runs the Claude Code review command.
WHY: GitHub Actions is the most common CI/CD platform for automated code review.
YOU SHOULD SEE: A .github/workflows/review.yml file that triggers on pull_request events.
Configure the workflow to post review results as PR comments using the GitHub API.
WHY: Review results are most useful as PR comments where developers can see them in context.
YOU SHOULD SEE: Claude's review appears as a comment on the pull request.
Add cost controls: set a maximum token limit and add a cost tracking step that logs API usage.
WHY: Cost controls prevent runaway CI jobs from consuming API credits.
YOU SHOULD SEE: Token usage is logged and the job respects the maximum limit.
Sources
- Claude Code CI/CD Integration— Anthropic Documentation
- Claude Code GitHub Actions— Anthropic Documentation