CI/CD Integration

Overview

An agent workflow is only as valuable as how often it runs. If it requires a developer to remember to trigger it, it will be forgotten. The real power emerges when agent workflows run automatically -- triggered by git pushes, pull requests, and scheduled events, just like your tests and linters. This lesson covers how to embed AI agents into CI/CD pipelines, with a focus on GitHub Actions, headless execution, and the configuration that makes it reliable.

Why CI/CD Changes the Game

Running agents locally is useful. Running agents in CI is transformative. Here is the difference:

• Local -- one developer remembers to run the review script before submitting a PR
• CI -- every PR is automatically reviewed, every migration is validated, every documentation gap is flagged

CI vs local comparison: a CI/CD pipeline shows a deterministic sequence — PR opened triggers Build and Test, then Agent Review, then Security Gate, then Deploy Preview. The local-only approach shows a developer remembering to run a script manually, with the risk of forgetting next time.

CI integration turns agent workflows from optional developer habits into consistent, automated review steps. Every PR gets an agent review. Every change gets a security scan. The agent provides advisory feedback that complements -- but does not replace -- your deterministic checks and human review.

The Headless Challenge

Agents in CI face a constraint that local usage does not: there is no human at the keyboard. This means:

• No interactive prompts -- the agent cannot ask "should I modify this file?" There is nobody to answer.
• No permission approvals -- file writes, command execution, and network access must be pre-authorized.
• No course correction -- if the agent goes off-track, there is no human to redirect it.

Headless mode solves this by running the agent with pre-configured permissions and a well-defined task. The agent executes its prompt, produces output, and exits. The key ingredients are:

1. A clear, scoped prompt passed via -p flag
2. A .claude/settings.json with the right permission allowlist
3. A CLAUDE.md file that provides all the context the agent needs

Headless execution sequence: GitHub Actions triggers a runner on a PR event. The runner checks out code, installs the CLI, and invokes the agent with a review prompt. The agent reads CLAUDE.md, settings.json, and the diff from the repository, analyzes the code, and returns review markdown. The runner posts the review as a comment on the PR.

Security Model for CI Agents

Before wiring agents into CI, you need a security model. A CI pipeline that runs agents on pull requests is processing untrusted input -- and without guardrails, an attacker can exploit the agent to exfiltrate secrets, modify code, or bypass review.

Here are the non-negotiable guardrails:

1. PR content is untrusted input. PR titles, descriptions, diffs, commit messages, and changed file contents are all attacker-controlled in a fork PR scenario. Never interpolate raw diff content directly into a prompt string -- write it to a temporary file and pass the file path instead. This prevents prompt injection through crafted diffs.

2. Fork isolation. Fork PRs should run without repository secrets or write-capable tokens. Use the pull_request event (not pull_request_target) so that fork PRs cannot access secrets. If you need pull_request_target for other reasons, never check out or execute code from the fork's HEAD.

3. Least-privilege tools for the reviewing agent. A code reviewer needs read-only tools. It should not have access to deployment credentials, write tokens, or the ability to post arbitrary comments with embedded commands. Use tools: Read, Glob, Grep in agent frontmatter.

4. Advisory output only. Agent review output is untrusted advisory text. Deterministic checks -- tests, linting, type checking, policy scanners -- make merge decisions. The agent provides a second pair of eyes, not a quality gate. A human reviewer makes the final merge decision.

5. Pin third-party Actions. In production-grade workflows, pin GitHub Actions to immutable commit SHAs rather than mutable tags like @v4. A compromised tag can inject malicious code into your workflow.

Fork PR security flowchart: a pull request is checked — if it is a fork PR, it runs without secrets or write tokens. Both fork and non-fork PRs go through an agent review with read-only tools. The agent produces advisory output, which feeds into both a human reviewer (who makes the merge decision) and deterministic checks (tests, lint, types) that form a pass/fail quality gate.

GitHub Actions Setup

Here is a GitHub Actions workflow that runs an agent-powered code review on every pull request, incorporating the security guardrails above:

Key decisions in this workflow:

• pull_request event (not pull_request_target) -- fork PRs cannot access secrets
• Diff written to a file instead of interpolated into the prompt -- prevents prompt injection through crafted diffs
• --max-turns 3 limits agent iterations to prevent runaway sessions
• fetch-depth: 0 gives the agent full git history for accurate diffs
• timeout-minutes: 10 prevents runaway agent sessions from blocking CI
• --output-format json produces structured output that downstream steps can parse
• The API key is stored as a GitHub secret, never hardcoded
• The review comment is labeled "Advisory" -- it is input for human reviewers, not a merge gate

Permission Configuration for CI

In headless mode, the agent needs pre-authorized permissions. Without them, it will hit permission prompts and stall. Configure .claude/settings.json with the minimum permissions the agent needs:

The principle of least privilege applies here. Allow the agent to read files, run git commands, and execute your test suite. Deny destructive operations, network access, and anything that modifies remote state.

Treat CI agent permissions like you treat IAM roles: grant only what is necessary, deny everything else explicitly.

The Role of CLAUDE.md in CI

When an agent runs in CI, it cannot ask a developer "what framework does this project use?" or "what is the test command?" It relies entirely on CLAUDE.md for that context. A CI-optimized CLAUDE.md should include:

• Project overview -- what the codebase does, what language and framework it uses
• Architecture -- where key directories are and what they contain
• Conventions -- coding patterns, naming conventions, error handling approaches
• Test commands -- exactly how to run tests, lint, and build
• Constraints -- files or directories that must not be modified
• Review guidelines -- what constitutes a real issue versus a style preference

Without this file, the CI agent is flying blind. With it, the agent has the same context a senior team member would bring to a review.

Multi-Step CI Workflows

Simple review is just the beginning. You can chain multiple agent steps in a single CI workflow:

This is the fan-out pattern from the previous lesson, implemented as CI steps. Each review dimension runs independently, then a synthesis step merges the results.

Architecture of an Agent-Integrated Pipeline

Here is how agents fit into a complete CI/CD architecture:

Agent-integrated pipeline architecture: a pull request feeds into two parallel tracks. The CI pipeline runs deterministic checks (Build, Test Suite, Linter) that form a pass/fail quality gate. Separately, the agent review runs parallel correctness, security, and coverage analyses. The quality gate determines pass/fail, while agent review provides advisory input to a human reviewer. Both the gate result and the human reviewer feed into the final merge decision.

The agent review step runs alongside traditional deterministic checks -- build, test, lint. The deterministic checks form the actual quality gate (pass/fail). The agent review provides advisory input to a human reviewer, who makes the final merge decision. Agent output should never be the sole merge gate -- it is a second pair of eyes, not a replacement for tests and human judgment.

Cost and Performance Considerations

Running agents in CI costs real money and wall-clock time. Manage both:

• Scope the prompt -- do not ask the agent to "review everything." Focus on the diff, not the entire repo.
• Set timeouts -- a timeout-minutes value prevents runaway sessions from consuming resources.
• Cache dependencies -- install the agent CLI once and cache it across runs.
• Trigger selectively -- run the full agent pipeline on PRs to main, not on every push to every branch.
• Use token budgets -- the --max-turns flag limits how many iterations the agent can perform.

Start with a single agent step in CI. Measure the cost and duration. Add more steps only when the value justifies the expense.

Troubleshooting CI Agent Failures

When an agent step fails in CI, the most common causes are:

• Missing API key -- verify the secret is set and the environment variable name matches
• Permission denied -- the agent tried to run a command not in the allowlist; update .claude/settings.json
• Timeout -- the prompt was too broad or the agent entered an iteration loop; narrow the scope
• Empty diff -- the workflow triggered on a PR with no code changes; add a guard condition
• Context overflow -- the diff was too large for the context window; split the review by file or directory

Summary

Integrating agents into CI/CD pipelines transforms them from developer tools into team infrastructure. The key requirements are headless mode with pre-configured permissions, a comprehensive CLAUDE.md for context, and scoped prompts that give the agent a clear, bounded task. GitHub Actions provides a natural integration point -- trigger on PR events, run the agent CLI, and post results back to the PR. Start with a single review step, measure cost and latency, and expand to multi-step pipelines as you build confidence. In the next lesson, we will dive deep into the most impactful CI use case: automated code review that catches bugs linters miss.