Module 6: Project — Complete CI/CD Pipeline with Claude Code
End-to-End Pipeline Design
End-to-End Pipeline Design
Overview
This capsule is where you design the complete pipeline before implementing it. Without a clear design, capsules 03-06 become blind implementation with costly rework. Here you take the components you learned in modules 1-5 and decide how they fit: execution order, dependencies, gates, parallelization, expected costs, and trade-offs.
The output of this capsule isn't code — it's a design document that describes the pipeline in terms of stages, data flows, critical decisions, and estimates. It's what lets you enter the implementation capsules knowing what to build and why.
By the end, you'll have: the pipeline architecture diagrammed, decisions documented with a reason, time and cost estimates per run, and an incremental validation plan.
Why Design Before Implementing
WITHOUT PRIOR DESIGN:
Session 1: You start with M1 (basic workflow)
Session 2: You add M2 (code review)
Session 3: "Now deployment... but where does it fit?"
Session 4: Refactor so deployment works
Session 5: "The security scan is missing... do I put it before or after?"
Session 6: Another refactor
→ Each decision is made without context of the whole
→ Costly refactors to reorganize
→ Inconsistent final pipeline
WITH PRIOR DESIGN:
Session 0: Complete design on paper/markdown
Session 1: You implement stage 1 knowing where it fits
Session 2: You implement stage 2 with no surprises
Session N: A coherent pipeline, minimal refactoring
→ Contextualized decisions
→ Linear implementation
→ A coherent result from the start
An investment of 1-2 hours in design saves 6-10 hours of rework. And it produces a better pipeline.
The Key Design Decisions
1. STAGE ORDER
What runs first, what after?
Trade-off: parallelism (fast) vs dependencies (correct)
2. PARALLELIZATION
Which stages can run in parallel?
Trade-off: speed vs runner cost
3. GATES (human and automatic)
Where do we require human approval?
Trade-off: security vs speed
4. FAILURE BEHAVIOR
Which stages block if they fail? Which only inform?
Trade-off: strict (blocking) vs permissive (informative)
5. COST PER RUN
How much does each deploy cost?
Trade-off: features vs budget
6. TOTAL TIME
How long does PR-to-prod take on the happy path?
Trade-off: coverage vs speed
7. OBSERVABILITY
Which metrics does the pipeline export?
Trade-off: completeness vs complexity
Each decision has an explicit trade-off. Documenting them avoids "why did we do this" 6 months later.
The Complete Architecture
┌──────────────────────────────────────────────────────────┐
│ PHASE 1: PR REVIEW │
│ (parallel, before the merge) │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Code Review │ │ Security │ │ Tests + │ │
│ │ (Claude) │ │ Scan │ │ Linting │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ │ │ │ │
│ └────────────────┴────────────────┘ │
│ │ │
│ ▼ │
│ Did the gates pass? │
│ │ │
└──────────────────────────┼────────────────────────────────┘
│
┌────────────┴────────────┐
▼ NO ▼ YES
Block the merge ┌──────────────┐
│ Merge to main│
└──────┬────────┘
│
┌─────────────────────────────────────────┼─────────────────┐
│ PHASE 2: PRE-DEPLOYMENT │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Generate │ │
│ │ Changelog │ ← M4 │
│ └──────┬───────────┘ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Readiness │ │
│ │ Validation │ ← M4 │
│ └──────┬───────────┘ │
└───────────────────────────────────────┼────────────────────┘
│
┌───────────────────────────────────────┼────────────────────┐
│ PHASE 3: DEPLOYMENT ▼ │
│ ┌──────────────────┐ │
│ │ Deploy Staging │ ← M4 │
│ │ + Smoke Tests │ │
│ └──────┬───────────┘ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Validate Staging │ │
│ │ with Claude │ ← M4 │
│ └──────┬───────────┘ │
│ ▼ │
│ ╔══════════════════╗ │
│ ║ APPROVAL GATE ║ ← M4 │
│ ║ (human) ║ │
│ ╚══════┬═══════════╝ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Deploy Production│ │
│ │ + Smoke Tests │ ← M4 │
│ └──────┬───────────┘ │
└───────────────────────────────────────┼────────────────────┘
│
┌───────────────────────────────────────┼────────────────────┐
│ PHASE 4: POST-DEPLOY ▼ │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Monitor + │ ← M5 │ Notify Team │ │
│ │ Auto-Rollback │ │ │ │
│ └──────┬───────────┘ └──────────────────┘ │
│ ▼ (if rollback) │
│ ┌──────────────────┐ │
│ │ Diagnose + │ ← M5 │
│ │ Postmortem │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Key characteristics of the design:
- Phase 1 is parallel (3 simultaneous jobs)
- Phase 2 is sequential (changelog → readiness)
- Phase 3 has the only human gate (between staging and production)
- Phase 4 monitors continuously, triggers rollback if needed
Detailing Each Stage
Phase 1: PR Review
# Conceptual — implementation in capsule 03
stages_phase_1:
- name: code-review
runs_on: pull_request
duration: ~3 min
cost: ~$0.02
failure_behavior: warn (doesn't block)
output: PR comment with findings
- name: security-scan
runs_on: pull_request
duration: ~2 min
cost: ~$0.03
failure_behavior: block on critical (capsule 02 M5)
output: PR comment + check status
- name: tests-and-linting
runs_on: pull_request
duration: ~5 min
cost: ~$0.04 (runner)
failure_behavior: block (always)
output: check status
parallelization: the 3 run in parallel
total_phase_1_duration: ~5 min (max of the 3)
total_phase_1_cost: ~$0.09Phase 2: Pre-Deployment
stages_phase_2:
- name: generate-changelog
trigger: push to main
duration: ~1 min
cost: ~$0.05
failure_behavior: warn (doesn't block the deploy)
- name: readiness-validation
duration: ~2 min
cost: ~$0.04
failure_behavior: block (deploy doesn't proceed)
parallelization: sequential
total_phase_2_duration: ~3 min
total_phase_2_cost: ~$0.09Phase 3: Deployment
stages_phase_3:
- name: deploy-staging
duration: ~4 min
cost: ~$0.04 (runner) + infra cost
failure_behavior: block (doesn't advance to prod)
- name: smoke-tests-staging
duration: ~2 min
cost: ~$0.02
failure_behavior: block
- name: validate-staging-claude
duration: ~1 min
cost: ~$0.02
failure_behavior: warn
output: comment to the PR with analysis
- name: approval-gate-production
duration: variable (human)
cost: $0
failure_behavior: timeout after 24h
- name: deploy-production
duration: ~4 min
cost: ~$0.04 + infra cost
failure_behavior: trigger automatic rollback
- name: smoke-tests-production
duration: ~2 min
cost: ~$0.02
parallelization: sequential
total_phase_3_duration: ~13 min not counting the approval wait
total_phase_3_cost: ~$0.14Phase 4: Post-Deploy
stages_phase_4:
- name: monitor-post-deploy
duration: ~10 min (monitoring window)
cost: ~$0.01 (mostly runner)
failure_behavior: trigger rollback if metrics degrade
- name: rollback (conditional)
triggered_by: monitor failure
duration: ~3 min
cost: ~$0.03
- name: diagnose (conditional)
triggered_by: rollback
duration: ~2 min
cost: ~$0.06 (Claude analysis)
- name: notify-team
duration: ~1 min
cost: ~$0.02
total_phase_4_duration: ~10-15 min (typical) or ~5 min on the happy pathOverall Summary
HAPPY PATH (no rollback, no extensive human investigation):
- Phase 1: 5 min
- Phase 2: 3 min
- Phase 3: 13 min (without approval wait)
- Approval wait: variable (typically 10-30 min)
- Phase 4 (monitoring): 10 min
TOTAL: ~30-50 min (most of it is the approval wait)
COST PER RUN:
- API costs: ~$0.20 per complete run
- Runner costs: ~$0.10
- TOTAL: ~$0.30 per deploy
ASSUMING 50 deploys/month:
~$15/month in CI/CD
Critical Decisions to Make Before Implementing
1. Model: Haiku, Sonnet, or Opus
DECISION: Which model to use in each stage?
Code review (Phase 1): Haiku → economical, enough for review
Security scan: Sonnet → more quality to detect real vulns
Changelog generation: Sonnet → categorization reasoning
Readiness validation: Sonnet → deep analysis
Validate staging: Sonnet → reasoning about metrics + changelog
Diagnosis post-roll: Sonnet → root cause analysis
NEVER Opus in normal CI — overkill and expensive.
2. Trigger: PR vs Push vs Tag
PHASE 1 (review): pull_request: [opened, synchronize]
PHASE 2-3 (deploy): push: [main]
PHASE 4 (monitoring): chained from deploy
Edge case: urgent hotfix
- Allow direct push to main (skip PR review)
- But keep Phase 2-4 mandatory
- Configure branch protection to limit who can skip the PR
3. Concurrency: When to Cancel Runs
# For PR reviews (Phase 1):
concurrency:
group: pr-${{ github.event.pull_request.number }}
cancel-in-progress: true # ← cancel old runs of the same PR
# For deploys (Phase 2-3-4):
concurrency:
group: deploy-production
cancel-in-progress: false # ← NEVER cancel deploys4. Minimal Permissions
# Phase 1 (review):
permissions:
contents: read
pull-requests: write # to post comments
# Phase 2-3 (deploy):
permissions:
contents: write # to push tags if applicable
deployments: write # to register deployments
packages: write # if it publishes artifacts
# Phase 4 (post-deploy):
permissions:
contents: read
issues: write # to create the postmortem issue
pull-requests: write # for commentsPrinciple: the minimal permissions necessary. Each stage only with what it requires.
5. Secrets Management
SHARED SECRETS (all stages):
- ANTHROPIC_API_KEY (with a usage limit configured)
- GITHUB_TOKEN (auto-generated)
PHASE 3 SECRETS (deploy only):
- PROD_DATABASE_URL (in the "production" environment)
- PROD_API_TOKENS (in the "production" environment)
- STAGING_DATABASE_URL (in the "staging" environment)
PHASE 4 SECRETS:
- METRICS_API_TOKEN (Datadog/Prometheus)
- SLACK_WEBHOOK
- PAGERDUTY_TOKEN (optional)
ROTATION:
- ANTHROPIC_API_KEY: rotate quarterly
- DATABASE_URLs: rotate when you rotate DB credentials
- GITHUB_TOKEN: auto-rotated by GitHub
6. Branch Protection Rules
BRANCH: main
Rules:
- Require pull request before merging
- Require approvals: 1
- Require status checks to pass:
☑ tests-and-linting (Phase 1)
☑ security-scan (Phase 1)
☑ code-review (Phase 1) — optional
- Require branches to be up to date
- Restrict who can push: only merge from a PR (no direct push)
BRANCH: hotfix/*
Rules:
- Allow direct push (for emergencies)
- But require a PR to merge to main
Incremental Validation: Implementation Plan
You won't implement the whole pipeline at once. Iteration plan:
ITERATION 1: Phase 1 working
- Basic code review (M2)
- Tests + linting
- Verify end-to-end on a test PR
- Estimated time: 2 hrs
- Value: automatic feedback on PRs
ITERATION 2: Phase 2 + Phase 3 (without rollback)
- Automatic changelog
- Readiness validation
- Automatic deploy to staging
- Approval gate + deploy to production
- Estimated time: 3 hrs
- Value: deploy with discipline
ITERATION 3: Phase 4 (rollback + monitoring)
- Monitor post-deploy
- Auto-rollback with triggers
- Post-rollback diagnostic
- Estimated time: 3 hrs
- Value: resilience
ITERATION 4: Optimization + observability
- Pipeline metrics
- Cost tracking
- Complete documentation
- Estimated time: 2 hrs
- Value: production-ready pipeline
Total: ~10 hours of focused work distributed across 4 iterations that each deliver visible value.
The Design Document
Before implementing, write a PIPELINE_DESIGN.md:
# Pipeline Design
## Goal
An end-to-end CI/CD pipeline that demonstrates the capabilities of integrated Claude Code.
## Architecture
[Pipeline diagram — use the one above]
## Stages
### Phase 1: PR Review
- code-review (parallel)
- security-scan (parallel)
- tests-and-linting (parallel)
### Phase 2: Pre-Deployment
- generate-changelog
- readiness-validation
### Phase 3: Deployment
- deploy-staging
- smoke-tests-staging
- validate-staging-claude
- approval-gate-production (HUMAN GATE)
- deploy-production
- smoke-tests-production
### Phase 4: Post-Deploy
- monitor-post-deploy
- rollback (conditional)
- diagnose (conditional)
- notify-team
## Critical Decisions
### Model
- Haiku for code review
- Sonnet for security/changelog/diagnosis
### Estimated cost
- Per run: ~$0.30
- Monthly (50 deploys): ~$15
### Estimated time (happy path)
- Phase 1: 5 min
- Phase 2: 3 min
- Phase 3: 13 min + approval wait
- Phase 4: 10 min monitoring
### Branch Protection
- main: PR required, status checks required
- Hotfix path: documented but requires communication to the team
## Implementation Plan
Iteration 1: Phase 1 (~2 hrs)
Iteration 2: Phase 2-3 (~3 hrs)
Iteration 3: Phase 4 (~3 hrs)
Iteration 4: Optimization (~2 hrs)
Total: ~10 hrs
## Risks and Mitigations
### Risk: Costs grow more than expected
Mitigation: spending limit in the Anthropic console + GitHub Billing
### Risk: The approval gate becomes a bottleneck
Mitigation: notification + explicit delegation in the docs
### Risk: Rollback with false positives
Mitigation: start with conservative thresholds, calibrate with real data
## Success Criteria
- The pipeline runs end-to-end with no manual intervention on the happy path
- PR-to-staging: <15 min
- PR-to-production (includes approval): <1 hour typical
- Automatic rollback in <5 min when triggered
- The team can operate without documentation beyond the runbookThis document is the project's first deliverable. Without it, the following capsules are execution without direction.
Common Pitfalls in the Design
1. Over-parallelizing
Symptom: "I'll put all the stages in parallel for maximum speed."
Why it fails: Stages have dependencies (you can't deploy to production without successful staging). Over-parallelizing = incoherent pipeline.
How to fix it: Identify the real dependencies before parallelizing. Only parallelize between independent stages.
2. Under-parallelizing
Symptom: "I'll make everything sequential for simplicity."
Why it fails: A pipeline 2-3x slower than necessary. Code review + security + tests can run in parallel.
How to fix it: Identify independent stages and parallelize them. Speed matters for the team's flow.
3. Approval gate in the wrong place
Symptom: Approval required before staging — the team complains because "why do they need to approve staging".
Why it fails: Staging is a test environment. The human gate goes before production.
How to fix it: Only human gates at high-risk transitions (staging → prod, hotfix deploy without tests, etc.).
4. Not documenting trade-offs
Symptom: 6 months later, someone asks "why is this sequential?" and nobody knows.
Why it fails: Decisions stay in heads, not in docs.
How to fix it: Every non-obvious decision → document it in PIPELINE_DESIGN.md with a reason. Especially trade-offs (not "just because").
5. Perfect design vs incremental implementation
Symptom: You spend 2 weeks designing the ideal pipeline, you never start implementing.
Why it fails: Without feedback from reality, the design has incorrect assumptions.
How to fix it: A "good enough" design in 1-2 hours. Implement Iteration 1. Learn. Adjust the design. Iterate.
Diagnosis
Question 1: Does your design explicitly identify which stages are parallel vs sequential?
If not, you'll make ad-hoc decisions at each stage. An explicit diagram = better.
Question 2: Did you document the estimated cost per run and per month?
Without this, the bill surprises you. A simple calculation resolves 80%.
Question 3: Do you know the total expected time of the pipeline on the happy path?
If you said "I'm not sure", most people who get to the deploy don't know how long to wait. That affects the team's flow.
Question 4: Is your approval gate where it makes sense (before prod) or where it "feels safe" (all stages)?
Too many gates = a frustrating pipeline. Few gates in specific places = the right balance.
Question 5: Do you have an iteration plan or are you going to implement everything at once?
Implementing everything at once = rework. Iterations with visible value each = you learn and adjust.
Exercises
Exercise 1: Design document (Medium)
Write PIPELINE_DESIGN.md for your project following the template above. Specifically:
- A diagram of the 4 phases
- Critical decisions with a reason
- Estimated costs
- Iteration plan
Exercise 2: Identify parallelization (Easy)
Take your diagram and explicitly mark:
- 🟢 Stages that can run in parallel
- 🔴 Stages that require sequential execution
- 🟡 Stages that depend on the outputs of others
Exercise 3: Calculate cost and time (Medium)
For your designed pipeline:
- Estimate the tokens per stage that Claude uses
- Calculate the API cost per run
- Calculate the runner cost (time × $0.008)
- Estimate the total time on the happy path
- Multiply by the expected deploys/month
If the estimate is >$50/month, identify what to optimize.
Summary
- Design before implementing saves 6-10 hrs of rework
- 4 pipeline phases: PR Review (parallel), Pre-Deploy, Deployment (with approval), Post-Deploy
- Only human gates at critical transitions (not at every stage)
- Decisions documented with a reason avoid the future "why did we do this"
- The appropriate model per stage: Haiku for review, Sonnet for deep analysis
- Incremental iteration > perfect design + monolithic implementation
- Estimated costs and times avoid surprises
Next capsule: 03 — Implementation: Stages 1-3 (PR Review). You take the design and start implementing Phase 1: code review + security scan + tests, all running in parallel on every PR.
Additional Resources
- Continuous Delivery — Jez Humble — The classic reference
- The DORA State of DevOps Report — Metrics that matter in CI/CD
- GitHub Actions: jobs in parallel — Parallelization syntax
- Site Reliability Engineering: Release Engineering — How Google designs deploys
- Mermaid — For pipeline diagrams in docs
- DORA Four Key Metrics — For measuring the pipeline