What This Template Is For
A CI/CD pipeline is the assembly line between a code commit and a production deployment. When it works well, engineers merge code and it reaches users within minutes, with automated tests catching problems before they ship. When it is poorly defined, deployments are manual, test coverage is inconsistent, and "it works on my machine" is a weekly conversation.
This template documents the full pipeline specification: what happens at each stage, what quality gates must pass, how artifacts are managed, and how code progresses from development to production. It is not a tutorial on setting up Jenkins or GitHub Actions. It is the specification that tells your team exactly what the pipeline should do, regardless of which tool runs it.
Use this template when setting up a pipeline for a new service, migrating from a manual deployment process, or standardizing pipelines across multiple teams. For the broader context of how deployment processes fit into technical product management, see the Technical PM Handbook. If your team is evaluating build-vs-buy for CI/CD tooling, the PM Tool Picker can help compare options.
How to Use This Template
- Map your current deployment process from commit to production. Document every manual step, even if it seems obvious.
- Define the pipeline stages in order: source, build, test, artifact, deploy. Each stage should have clear inputs, outputs, and pass/fail criteria.
- Set quality gates between stages. A quality gate is a set of conditions that must be met before code advances to the next stage.
- Document environment promotion rules: how code moves from dev to staging to production, and who approves each transition.
- Define rollback procedures for each environment.
- Review with the engineering team to identify gaps, then implement stage by stage.
The Template
Pipeline Overview
| Field | Details |
|---|---|
| Service/Application | [Name] |
| Repository | [URL] |
| CI/CD Tool | [GitHub Actions / GitLab CI / Jenkins / CircleCI / etc.] |
| Owner | [Team or individual] |
| Date | [Date] |
| Pipeline Trigger | [Push to main / PR merge / Tag / Manual] |
Source Control Configuration
| Setting | Value |
|---|---|
| Default Branch | [main / master] |
| Branch Protection | [Required approvals, status checks] |
| Merge Strategy | [Squash / Merge commit / Rebase] |
| Branch Naming | [Convention: feature/, bugfix/, hotfix/] |
Branch rules.
- ☐ All changes go through pull requests (no direct pushes to default branch)
- ☐ Minimum [N] approving reviews required
- ☐ All CI checks must pass before merge
- ☐ Branch must be up to date with default branch before merge
- ☐ Force pushes disabled on protected branches
Pipeline Stages
Stage 1: Build
| Setting | Value |
|---|---|
| Trigger | [On PR open / On push to default branch] |
| Runtime | [Node 20 / Python 3.12 / Go 1.22 / etc.] |
| Steps | Install dependencies, compile, lint |
| Timeout | [e.g., 10 minutes] |
| Caching | [node_modules, .next/cache, pip cache] |
Stage 2: Test
| Setting | Value |
|---|---|
| Trigger | [After build succeeds] |
| Test Types | [Unit, Integration, E2E] |
| Coverage Threshold | [e.g., 80% lines, 70% branches] |
| Timeout | [e.g., 15 minutes] |
| Parallelization | [Yes/No, number of shards] |
Stage 3: Security Scan
| Setting | Value |
|---|---|
| Trigger | [After tests pass] |
| Scans | [Dependency audit, SAST, secret detection] |
| Blocking Severity | [Critical and High block merge / Medium as warning] |
| Tool | [Snyk / Dependabot / Trivy / etc.] |
Stage 4: Build Artifact
| Setting | Value |
|---|---|
| Trigger | [After all checks pass on default branch] |
| Artifact Type | [Docker image / Static bundle / Serverless package] |
| Registry | [ECR / GCR / Docker Hub / S3] |
| Tagging | [Git SHA, semver, latest] |
| Retention | [e.g., 30 days for non-production, indefinite for production] |
Stage 5: Deploy
| Setting | Value |
|---|---|
| Strategy | [Rolling / Blue-green / Canary / Recreate] |
| Environments | [Dev → Staging → Production] |
| Approval Required | [None for dev, manual for production / auto for all] |
| Health Check | [Endpoint, expected response, timeout] |
| Rollback Trigger | [Health check failure / error rate spike / manual] |
Quality Gates
| Gate | Stage | Criteria | Blocking? |
|---|---|---|---|
| Lint | Build | Zero errors (warnings allowed) | Yes |
| Type check | Build | Zero type errors | Yes |
| Unit tests | Test | 100% pass rate | Yes |
| Coverage | Test | > [threshold]% line coverage | Yes |
| Integration tests | Test | 100% pass rate | Yes |
| Security scan | Security | No critical/high vulnerabilities | Yes |
| Build size | Artifact | Bundle < [size] MB | No (warning) |
| Smoke tests | Deploy | Critical paths pass in target environment | Yes |
Environment Configuration
| Environment | URL | Deployment Trigger | Approval | Data |
|---|---|---|---|---|
| Development | [URL] | Push to feature branch | None | Synthetic / seeded |
| Staging | [URL] | Merge to default branch | None | Production mirror (anonymized) |
| Production | [URL] | [Manual approval / Auto after staging] | [Approver] | Live |
Rollback Procedures
- ☐ Automated rollback on health check failure (deploy stage)
- ☐ Manual rollback via [tool/command: e.g.,
kubectl rollout undo] - ☐ Database migration rollback strategy documented
- ☐ Feature flag kill switch for new functionality
- ☐ Previous artifact retained for instant rollback ([retention period])
Secrets and Configuration
| Secret/Config | Storage | Access | Rotation |
|---|---|---|---|
| API keys | [Vault / AWS Secrets Manager / GitHub Secrets] | [Pipeline only / Runtime] | [Quarterly / Annual] |
| Database credentials | [Vault / SSM Parameter Store] | [Runtime only] | [Quarterly] |
| Signing keys | [KMS / Vault] | [Pipeline only] | [Annual] |
| Feature flags | [LaunchDarkly / environment variables] | [Runtime] | N/A |
Filled Example: Next.js SaaS Application
Pipeline Overview
| Field | Details |
|---|---|
| Service | Acme Dashboard (Next.js 14) |
| Repository | github.com/acme/dashboard |
| CI/CD Tool | GitHub Actions |
| Owner | Platform Team |
| Pipeline Trigger | Push to main (deploy), PR open (checks) |
Pipeline Stages
| Stage | Steps | Duration | Quality Gate |
|---|---|---|---|
| Build | npm ci, npm run lint, npm run type-check, npm run build | ~3 min | Zero lint errors, zero type errors |
| Test | npm run test (Vitest), npm run test:e2e (Playwright) | ~5 min | 100% pass, >85% coverage |
| Security | npm audit --audit-level=high, Snyk container scan | ~2 min | No critical/high CVEs |
| Artifact | Build Docker image, push to ECR with git SHA tag | ~2 min | Image builds, health check passes |
| Deploy (staging) | Deploy to ECS staging, run smoke tests | ~4 min | All smoke tests pass |
| Deploy (production) | Deploy to ECS production (rolling, 25% at a time) | ~8 min | Error rate < 0.5%, P99 < 2s |
Total pipeline duration: ~24 minutes (commit to production)
Environment Configuration
| Environment | URL | Trigger | Approval |
|---|---|---|---|
| Preview | pr-{number}.preview.acme.com | PR open | None |
| Staging | staging.acme.com | Merge to main | None |
| Production | app.acme.com | Staging smoke tests pass | Auto (manual override available) |
Rollback
| Trigger | Action | Duration |
|---|---|---|
| Health check fails (3 consecutive) | Automatic ECS rollback to previous task definition | ~2 min |
| Error rate > 2% for 5 min post-deploy | Automated rollback via CloudWatch alarm + Lambda | ~3 min |
| Manual (engineer decision) | aws ecs update-service --force-new-deployment with previous image tag | ~5 min |
Key Takeaways
- Define quality gates between every pipeline stage with specific pass/fail criteria
- Target under 15 minutes from push to production deployment readiness
- Automate rollback with health checks and error rate monitoring
- Cache dependencies and parallelize tests to keep pipeline duration low
- Separate database migrations from application deployments for safer rollbacks
About This Template
Created by: Tim Adair
Last Updated: 3/4/2026
Version: 1.0.0
License: Free for personal and commercial use