# CI/CD Pipeline

# CI/CD Pipeline

> **Project:** {{PROJECT_NAME}}
> **Version:** {{VERSION}}
> **Date:** {{DATE}}
> **Author:** {{AUTHOR}}
> **Status:** Draft | In Review | Approved
> **Reviewers:** {{REVIEWERS}}

## Document History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 0.1     | {{DATE}} | {{AUTHOR}} | Initial draft |

---

## 1. Overview

<!-- GUIDANCE: Describe the CI/CD strategy at a high level. What platforms are used and why? -->

**CI/CD Platform:** {{PLATFORM}} <!-- GitHub Actions / GitLab CI / CircleCI / Jenkins / Bitbucket Pipelines -->
**Container Registry:** {{REGISTRY}} <!-- ECR / Docker Hub / GHCR / GCR -->
**Deployment Target:** {{DEPLOY_TARGET}} <!-- ECS / K8s / App Service / Heroku / VPS -->
**Strategy:** {{STRATEGY}} <!-- Rolling / Blue-Green / Canary -->

---

## 2. Pipeline Overview

<!-- GUIDANCE: Replace this diagram with your actual pipeline. Show all stages, gates, and branches. -->

```mermaid
flowchart LR
    subgraph Source
        PR[Pull Request]
        MERGE[Merge to main]
    end

    subgraph CI["CI — runs on every PR"]
        LINT[Lint & Format]
        TEST_UNIT[Unit Tests]
        TEST_INT[Integration Tests]
        SAST[SAST Scan]
        SCA[Dependency Scan]
        BUILD[Build Artifact]
    end

    subgraph CD_DEV["CD — Dev Auto-Deploy"]
        DEPLOY_DEV[Deploy to Dev]
        SMOKE_DEV[Smoke Tests]
    end

    subgraph CD_STAGING["CD — Staging (auto on main)"]
        DEPLOY_STG[Deploy to Staging]
        TEST_E2E[E2E Tests]
        PERF[Performance Tests]
    end

    subgraph CD_PROD["CD — Production (manual gate)"]
        APPROVAL[Manual Approval]
        DEPLOY_PROD[Deploy to Production]
        SMOKE_PROD[Smoke Tests]
        MONITOR[Verify Monitoring]
    end

    PR --> LINT
    LINT --> TEST_UNIT
    TEST_UNIT --> TEST_INT
    TEST_INT --> SAST
    SAST --> SCA
    SCA --> BUILD
    MERGE --> CD_DEV
    BUILD --> DEPLOY_DEV
    DEPLOY_DEV --> SMOKE_DEV
    SMOKE_DEV --> DEPLOY_STG
    DEPLOY_STG --> TEST_E2E
    TEST_E2E --> PERF
    PERF --> APPROVAL
    APPROVAL --> DEPLOY_PROD
    DEPLOY_PROD --> SMOKE_PROD
    SMOKE_PROD --> MONITOR
```

---

## 3. Source Control Configuration

### 3.1 Branching Strategy

<!-- GUIDANCE: Choose one strategy and document branch naming conventions and lifecycle. -->

**Strategy:** {{BRANCH_STRATEGY}} <!-- GitFlow / Trunk-Based / GitHub Flow -->

| Branch | Purpose | Naming Convention | Lifetime |
|--------|---------|-------------------|----------|
| `main` | Production-ready code | fixed | Permanent |
| `develop` | Integration branch | fixed | Permanent |
| `feature/*` | New features | `feature/{{TICKET}}-description` | Until merged |
| `fix/*` | Bug fixes | `fix/{{TICKET}}-description` | Until merged |
| `hotfix/*` | Production hotfixes | `hotfix/{{TICKET}}-description` | Until merged |
| `release/*` | Release preparation | `release/v{{VERSION}}` | Until merged |

### 3.2 Branch Protection Rules

<!-- GUIDANCE: Document required status checks, reviewer requirements, and merge restrictions. -->

**Protected Branches:** `main`, `develop`

| Rule | `main` | `develop` |
|------|--------|-----------|
| Require PR | Yes | Yes |
| Required approvals | {{APPROVALS}} | 1 |
| Dismiss stale reviews | Yes | Yes |
| Require status checks | Yes | Yes |
| Required checks | lint, unit-tests, integration-tests, sast | lint, unit-tests |
| Require up-to-date | Yes | No |
| Allow force push | No | No |
| Allow deletions | No | No |

### 3.3 Code Review Requirements

<!-- GUIDANCE: Document who must review, turnaround SLA, and what reviewers look for. -->

- Minimum **{{APPROVALS}}** approval(s) required before merge
- At least one approval from a **code owner** (see `CODEOWNERS`)
- All review comments must be **resolved** before merge
- Review turnaround SLA: **{{REVIEW_SLA}}** business hours
- Auto-assign reviewers via: {{ASSIGN_MECHANISM}} <!-- CODEOWNERS / GitHub auto-assign action -->

---

## 4. Build Stage

### 4.1 Build Tool & Configuration

<!-- GUIDANCE: Document the build commands, target artifacts, and build matrix. -->

| Parameter | Value |
|-----------|-------|
| Build Tool | {{BUILD_TOOL}} <!-- npm/yarn/pnpm/gradle/maven --> |
| Build Command | `{{BUILD_CMD}}` |
| Artifact Type | {{ARTIFACT}} <!-- Docker image / JAR / ZIP / binary --> |
| Artifact Naming | `{{REGISTRY}}/{{IMAGE_NAME}}:{{TAG_STRATEGY}}` |
| Tag Strategy | `git-sha` for PRs, `semver` for releases |

### 4.2 Dependency Caching

<!-- GUIDANCE: Document cache keys and what is cached to speed up builds. -->

| Cache | Key | Restore Keys |
|-------|-----|--------------|
| Node modules | `node-modules-{{OS}}-{{LOCKFILE_HASH}}` | `node-modules-{{OS}}-` |
| Docker layers | `buildx-{{DOCKERFILE_HASH}}` | `buildx-` |
| Test results | `test-results-{{COMMIT_SHA}}` | N/A |

### 4.3 Artifact Generation

<!-- GUIDANCE: Document what artifacts are produced, where they are stored, and retention policy. -->

| Artifact | Storage | Retention | Signed |
|----------|---------|-----------|--------|
| Docker image | {{REGISTRY}} | 90 days (non-prod), Forever (prod tags) | {{SIGNING}} |
| Test reports | CI artifact storage | 30 days | No |
| SBOM | {{SBOM_STORAGE}} | 1 year | Yes |
| Coverage report | {{COVERAGE_STORAGE}} | 30 days | No |

---

## 5. Test Stages

<!-- GUIDANCE: Document quality gates — what must pass for the pipeline to continue. -->

### 5.1 Unit Tests

| Parameter | Value |
|-----------|-------|
| Framework | {{UNIT_FRAMEWORK}} |
| Command | `{{UNIT_CMD}}` |
| Coverage Tool | {{COVERAGE_TOOL}} |
| Coverage Gate | ≥ {{COVERAGE_GATE}}% lines, ≥ {{BRANCH_GATE}}% branches |
| Failure Action | Block PR merge |

### 5.2 Integration Tests

| Parameter | Value |
|-----------|-------|
| Framework | {{INT_FRAMEWORK}} |
| Command | `{{INT_CMD}}` |
| Dependencies | {{INT_DEPS}} <!-- Docker services for DB, Redis, etc. --> |
| Failure Action | Block PR merge |

### 5.3 E2E Tests

| Parameter | Value |
|-----------|-------|
| Framework | {{E2E_FRAMEWORK}} <!-- Playwright / Cypress / Selenium --> |
| Command | `{{E2E_CMD}}` |
| Environment | Staging |
| Parallelization | {{E2E_SHARDS}} shards |
| Failure Action | Block staging promotion |

### 5.4 Security Scanning

| Scan Type | Tool | Command | Gate |
|-----------|------|---------|------|
| SAST | {{SAST_TOOL}} <!-- Semgrep / CodeQL / Bandit --> | `{{SAST_CMD}}` | Block on HIGH/CRITICAL |
| SCA (dependencies) | {{SCA_TOOL}} <!-- Snyk / Dependabot / OWASP Dependency-Check --> | `{{SCA_CMD}}` | Block on CRITICAL |
| Container scan | {{CONTAINER_SCAN}} <!-- Trivy / Snyk Container --> | `{{CONTAINER_SCAN_CMD}}` | Block on CRITICAL |
| Secret scanning | {{SECRET_SCAN}} <!-- GitLeaks / TruffleHog --> | `{{SECRET_SCAN_CMD}}` | Block on any finding |

### 5.5 Linting & Formatting

| Tool | Purpose | Command | Auto-fix |
|------|---------|---------|----------|
| {{LINTER}} | Code linting | `{{LINT_CMD}}` | PR comment |
| {{FORMATTER}} | Code formatting | `{{FMT_CMD}}` | Auto-commit or fail |
| {{TYPE_CHECK}} | Type checking | `{{TYPE_CMD}}` | No |

---

## 6. Deploy Stages

### 6.1 Deployment Strategy

<!-- GUIDANCE: Document the deployment strategy in detail, including traffic shifting and rollback triggers. -->

**Strategy:** {{DEPLOY_STRATEGY}} <!-- Rolling / Blue-Green / Canary -->

**Rolling Deployment:**
- Batch size: {{BATCH_SIZE}}% of instances
- Pause between batches: {{PAUSE}}min
- Health check wait: {{HEALTH_WAIT}}s
- Rollback trigger: health check failure

**Canary Deployment (if used):**
- Initial canary weight: {{CANARY_INITIAL}}%
- Increment: {{CANARY_INCREMENT}}% every {{CANARY_INTERVAL}}min
- Promotion criteria: error rate < {{ERROR_THRESHOLD}}%, p99 < {{LATENCY_THRESHOLD}}ms
- Rollback trigger: automatic on threshold breach

### 6.2 Environment Promotion

<!-- GUIDANCE: Document the promotion path and any gates between environments. -->

```
PR Branch → Dev (auto) → Staging (auto on main merge) → Production (manual approval)
```

| Promotion | Trigger | Gate | Approver |
|-----------|---------|------|----------|
| → Dev | Merge to `develop` / PR | All CI checks pass | Automatic |
| → Staging | Merge to `main` | All CI + Dev smoke tests | Automatic |
| → Production | Tag `v*.*.*` | All tests + manual approval | {{PROD_APPROVER}} |

### 6.3 Approval Gates

<!-- GUIDANCE: Document who can approve production deployments and the approval process. -->

**Production Approval Required:** Yes
**Approvers:** {{PROD_APPROVERS}} (at least {{APPROVAL_COUNT}} required)
**Approval Window:** {{APPROVAL_WINDOW}}h (pipeline cancels after timeout)
**Emergency Override:** {{EMERGENCY_OVERRIDE}} <!-- process for urgent hotfixes -->

### 6.4 Feature Flags Integration

<!-- GUIDANCE: Document how feature flags are used to decouple deployment from release. -->

**Feature Flag Tool:** {{FF_TOOL}} <!-- LaunchDarkly / Unleash / custom -->
**Flag Validation:** Feature flags validated in staging before production deploy
**Kill Switch:** All new features behind flags for first {{FF_PERIOD}} days

---

## 7. Post-Deploy

### 7.1 Smoke Tests

<!-- GUIDANCE: Document the smoke test suite — what it verifies and how quickly it runs. -->

| Check | Expected | Timeout |
|-------|----------|---------|
| Health endpoint `GET /health` | HTTP 200 | 10s |
| Auth endpoint reachable | HTTP 401 | 10s |
| Database connection | Healthy | 15s |
| Cache connection | Healthy | 10s |
| Critical user journey | Success | 60s |

**Smoke test timeout:** {{SMOKE_TIMEOUT}}min total
**On failure:** Auto-rollback triggered

### 7.2 Monitoring Verification

<!-- GUIDANCE: Document what monitoring metrics are verified post-deploy to confirm health. -->

| Metric | Threshold | Check Duration |
|--------|-----------|----------------|
| Error rate | < {{ERROR_RATE}}% | 5 min |
| P99 latency | < {{P99}}ms | 5 min |
| CPU utilization | < {{CPU}}% | 5 min |
| Memory utilization | < {{MEM}}% | 5 min |

### 7.3 Rollback Triggers

<!-- GUIDANCE: Document automatic and manual rollback triggers. -->

**Automatic rollback triggers:**
- Smoke test failure
- Error rate > {{AUTO_ROLLBACK_ERROR}}% for {{AUTO_ROLLBACK_DURATION}}min post-deploy
- Health check failure on {{HEALTH_FAIL_THRESHOLD}}% of instances

**Manual rollback:** See [rollback-plan.md](../RELEASE/rollback-plan.md)

---

## 8. Pipeline Configuration Reference

<!-- GUIDANCE: Link to or embed the actual pipeline config file for easy reference. -->

**Config File Location:** {{CONFIG_PATH}} <!-- .github/workflows/ci.yml / .gitlab-ci.yml -->

Key environment variables injected by CI:

| Variable | Source | Purpose |
|----------|--------|---------|
| `REGISTRY_TOKEN` | {{SECRET_STORE}} | Container registry auth |
| `DEPLOY_KEY` | {{SECRET_STORE}} | Deployment credentials |
| `SENTRY_DSN` | {{SECRET_STORE}} | Error tracking |
| `SLACK_WEBHOOK` | {{SECRET_STORE}} | Notifications |

---

## 9. Secret Injection Strategy

<!-- GUIDANCE: Document how secrets reach the pipeline without being hardcoded. -->

**Strategy:** {{SECRET_STRATEGY}} <!-- GitHub Secrets / Vault dynamic secrets / OIDC + IAM -->

| Secret Type | Storage | Injection Method | Rotation |
|-------------|---------|-----------------|----------|
| Registry credentials | {{STORAGE}} | {{METHOD}} | {{ROTATION}} |
| Cloud credentials | {{STORAGE}} | OIDC / Workload Identity | Per-job |
| App secrets | {{STORAGE}} | {{METHOD}} | {{ROTATION}} |

**OIDC Preferred:** Cloud credentials injected via OIDC — no long-lived keys stored in CI

---

## 10. Pipeline Metrics

<!-- GUIDANCE: Track these metrics monthly to identify bottlenecks and measure DORA metrics. -->

| Metric | Target | Current |
|--------|--------|---------|
| Build duration (P50) | < {{BUILD_TARGET}}min | TBD |
| Test duration (P50) | < {{TEST_TARGET}}min | TBD |
| Total pipeline duration | < {{TOTAL_TARGET}}min | TBD |
| Deploy frequency | {{DEPLOY_FREQ}} | TBD |
| Lead time for changes | < {{LEAD_TIME}} | TBD |
| Change failure rate | < {{FAILURE_RATE}}% | TBD |
| MTTR | < {{MTTR}} | TBD |

---

## Related Documents

- [Deployment Architecture](./deployment-architecture.md)
- [Environment Configuration](./environment-configuration.md)
- [Deployment Checklist](../RELEASE/deployment-checklist.md)
- [Rollback Plan](../RELEASE/rollback-plan.md)
- [Test Strategy](../TESTING/test-strategy.md)

---

## Approval
| Role | Name | Date | Signature |
|------|------|------|-----------|
| Author | | | |
| Reviewer | | | |
| Approver | | | |