CI/CD Pipeline Design Template (SLSA, NIST SP 800-204D)

CI/CD Pipeline Design: [Product or pipeline name]

Design document for a continuous integration and continuous delivery (CI/CD) pipeline: design drivers, architecture and runners, stages and quality gates, environments and promotion, identity and secrets, supply chain integrity (dependencies, SBOM, provenance and signing), deployment strategies and rollback, threat review, observability and delivery metrics, ownership of the pipeline itself, decisions, risks and a traceability matrix. Based on NIST SP 800-204D Strategies for the Integration of Software Supply Chain Security in DevSecOps CI/CD Pipelines (final, February 2024), NIST SP 800-218 Secure Software Development Framework (SSDF) Version 1.1 (February 2022), the SLSA specification v1.2 Build and Source tracks, the OWASP Top 10 CI/CD Security Risks (CICD-SEC-1 to CICD-SEC-10) and the joint CISA, FBI and ASD's ACSC guidance Safe Software Deployment (October 2024). Delivery metrics follow the five DORA software delivery metrics. Replace every [bracketed] value and every row marked Example. Worked examples use Corvid Commerce, a fictional SaaS company that runs an online checkout platform.

Document control

Approvals

Revision history

Contents

1. Purpose, scope and context
2. Design drivers and requirements
3. Pipeline architecture
4. Stages and quality gates
5. Environments and promotion
6. Identity, secrets and permissions
7. Supply chain integrity
8. Deployment strategies and rollback
9. Pipeline threat review
10. Observability, audit and delivery metrics
11. Ownership and change management of the pipeline
12. Decisions, risks and open issues
13. Acceptance criteria and traceability
14. Glossary and references

1. Purpose, scope and context

1.1 Purpose

This document describes how source changes for [Product name] become tested, signed and deployed artefacts. It is the reference for the platform team that operates the pipeline, for service teams that use it, and for auditors who need evidence that builds are reproducible, reviewed and tamper-evident.

1.2 Scope

1.3 Context

Example: Corvid Commerce deploys about 60 production changes per week across 41 services. Today each team maintains its own pipeline file; seven different deploy scripts exist, two teams deploy from laptops, and long-lived cloud keys are stored as repository secrets. An external customer audit asked for build provenance and an SBOM for each release. This design replaces the per-team pipelines with a shared, versioned pipeline definition that teams call with parameters.

2. Design drivers and requirements

2.1 Design drivers

1. Fast feedback: a developer learns whether a change is good within minutes, so that small batches and trunk-based development stay practical.
2. Integrity: every production artefact can be traced to a reviewed commit, a known build platform and a signed provenance statement.
3. Safe release: changes reach production through staged exposure with automated health checks and a tested rollback path.
4. Least privilege: no job holds more access than its step needs, and no long-lived production credential exists in the pipeline.
5. Self-service: service teams adopt the pipeline by configuration, not by copying scripts.

2.2 Requirements

3. Pipeline architecture

3.1 Component view

The diagram shows the main components and the direction of trust. The trust level column in 3.2 marks where untrusted code runs.

3.2 Components and trust boundaries

3.3 Pipeline as code

4. Stages and quality gates

4.1 Stage list

Example: The pull request path has a p90 budget of 10 minutes: validate (1) and build and unit test (4) run first, then static analysis (3) and dependency scan (2) run in parallel, which gives 1 + 4 + 3 = 8 minutes plus 2 minutes of queueing allowance. The merge-to-production path has a p90 budget of 119 minutes of machine time (4 + 2 + 3 + 5 + 10 + 30 + 60 + 5 minutes of queueing allowance), not counting the wait for the tier 1 promotion approval.

4.2 Gate definitions

4.3 Gate rules

1. A blocking gate fails closed: when the scanner or service behind it is unavailable, the stage fails rather than passes.
2. A waiver names the gate, the commit or digest, the reason, the approver and an expiry date. Waivers are stored with the pipeline run and reported monthly (section 10.3).
3. Re-running a failed job is allowed for infrastructure failures only. The pipeline records the re-run count; more than [two] re-runs of the same test in a week opens a flaky-test ticket.
4. Build once, promote the same digest. Later stages never rebuild from source; they deploy the digest produced in PIPE-STG-050.

5. Environments and promotion

5.1 Environments

5.2 Promotion rules

5.3 Promotion sequence

The sequence shows how one digest moves from build to production without a rebuild.

6. Identity, secrets and permissions

6.1 Workload identity

6.2 Secrets handling

1. Store remaining secrets (third-party API keys used by tests) in the central secrets manager, following Secrets Management Standard (security/secrets-management-standard); the CI store holds only a reference or a federated identity.
2. Scope each secret to the environment and workflow that need it. Pull request workflows from forks receive no secrets.
3. Mask secrets in logs and fail the job if a secret pattern appears in an uploaded artefact.
4. Rotate any secret that a job printed, cached or uploaded, and record the event as a security incident.

6.3 Pipeline permissions

7. Supply chain integrity

7.1 Dependency intake

Builds resolve dependencies only through the package proxy, install from committed lockfiles and verify hashes where the ecosystem supports it. New dependencies, update cadence and cooldown periods are governed by Dependency Management Policy (dev/dependency-management-policy); the pipeline enforces that policy through PIPE-GATE-003.

7.2 SLSA Build track mapping

The Source track (protected branches, history, two-party review) is defined in Branching Strategy (dev/branching-strategy) and Code Ownership Policy (dev/code-ownership-policy). Both documents use the same targets: Build L3, Source L3 for tier 1 (Source L4 for payment services); Build L2, Source L3 for tier 2.

7.3 Artefacts, SBOM and attestations

Assessment of the whole supply chain, Scorecard results and supplier risk belong to Software Supply Chain Security Assessment (security/supply-chain-security).

8. Deployment strategies and rollback

8.1 Strategy per tier

8.2 Rules for safe deployment

1. Separate deploy from release: ship code dark behind a flag where the change is user-visible, following Feature Flag Policy (dev/feature-flag-policy).
2. Apply the expand and contract pattern to schema changes: add new structures first, deploy code that writes both, migrate, then remove old structures in a later release.
3. Keep at least the previous [two] production digests deployable (images retained, configuration compatible).
4. Practise rollback: every tier 1 service performs a rollback in staging at least [once per quarter], recorded in the deployment log.
5. Keep an emergency path that is fast but not unreviewed: an emergency change still runs PIPE-STG-020 to PIPE-STG-050 and needs one approver; skipped stages run after the fact within [24 hours].
6. Use the human procedure in Deployment Runbook (ops/deployment-runbook) for releases that need manual steps.

9. Pipeline threat review

The table lists the OWASP Top 10 CI/CD Security Risks by identifier and short title, with the control chosen in this design. Read the OWASP project page for the full risk descriptions.

Record broader application threats in Threat Model (security/threat-model). Pipeline audit log retention follows Security Logging Standard (security/security-logging-standard).

10. Observability, audit and delivery metrics

10.1 DORA delivery metrics

Example: In a four-week period Corvid Commerce made 240 production deployments; 12 were followed by a rollback or hotfix and 9 were unplanned deployments caused by an incident. Change fail rate is 12 / 240 = 5.0%; deployment rework rate is 9 / 240 = 3.75%; deployment frequency is 240 / 4 = 60 per week across all services.

Report delivery performance quarterly in Delivery Performance Report (dev/delivery-performance-report).

10.2 Pipeline health metrics

10.3 Audit trail

Keep, for each production deployment: commit SHA, pull request and approvers, pipeline run identifier, artefact digest, attestations, promotion approver, gate results and waivers, and rollout outcome. Make the trail queryable by digest and by commit for at least [the retention period set in the security logging standard].

11. Ownership and change management of the pipeline

11.1 RACI

R = responsible, A = accountable, C = consulted, I = informed. One A per row.

11.2 Support and change rules

1. The pipeline library follows semantic versioning; a breaking change ships as a new major version with a migration note and at least [30 days] of support for the previous major version.
2. Pipeline outages that block production deploys for more than [30 minutes] are incidents and follow the organisation's incident process; severity is set with Incident Severity Matrix (ops/incident-severity-matrix).
3. Changes to gates or thresholds are announced [two weeks] ahead in the engineering channel, run in warn mode for [one week], then enforce.
4. The platform team publishes a status page for CI and keeps a runbook for runner capacity, registry and controller failures in Runbook (dev/runbook).

12. Decisions, risks and open issues

12.1 Decisions

Record each decision in Architecture Decision Record (dev/adr).

12.2 Risks

13. Acceptance criteria and traceability

13.1 Acceptance criteria

1. Every tier 1 service runs on the shared pipeline library at a supported major version.
2. PIPE-MET-005 is 100% for [four consecutive weeks].
3. The admission policy rejects an unsigned test image in production (negative test recorded).
4. A rollback of a tier 1 service in staging completes within its target time and is logged.
5. No static cloud credential remains in any CI secret store (scan evidence attached).

13.2 Traceability matrix

14. Glossary and references

14.1 Glossary

14.2 References

Standard and licence note

Based on NIST SP 800-204D (February 2024) and NIST SP 800-218 SSDF Version 1.1 (February 2022), which are US government works, and on the CISA, FBI and ASD's ACSC joint guidance Safe Software Deployment (October 2024). SLSA level and requirement names are used with attribution to the SLSA project (slsa.dev), published under the Community Specification License 1.0. The CICD-SEC identifiers and short titles are from the OWASP Top 10 CI/CD Security Risks project by the OWASP Foundation, licensed CC BY-SA 4.0; if you adapt OWASP material beyond these identifiers and titles, you must share your adaptation under the same licence. DORA metric names follow the DORA metrics guide on dora.dev (Google LLC, CC BY 4.0). Corvid Commerce is fictional. This template is original text written for this collection. Check the current official versions of each source before use. Template licence: MIT.