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
| Field | Value |
|---|
| Document ID | [CICD-DES-001] |
| Pipeline family | [Example: Corvid Commerce containerised services to Kubernetes] |
| Version | [0.1] |
| Status | [Draft / In review / Approved / Superseded] |
| Owner | [@platform-lead] |
| Approvers/reviewers | [@appsec-lead], [@sre-lead], [@release-manager], [@engineering-director] |
| Last updated | YYYY-MM-DD |
| Classification | [Internal] |
| CI/CD platform | [Example: Hosted CI service with self-hosted ephemeral runners for production deploys] |
| Repositories in scope | [Example: 41 service repositories listed in the service catalogue under tier 1 and tier 2] |
| Target SLSA levels | [Example: Build L3, Source L3 for tier 1 (Source L4 for payment services); Build L2, Source L3 for tier 2] |
| Next review | YYYY-MM-DD (at least annually and after any pipeline security incident) |
| Related documents | [Branching strategy], [Versioning and release policy], [Dependency management policy], [SBOM and VEX policy] |
Approvals
| Role | Name | Decision | Date |
|---|
| Platform engineering lead | [@name] | [Approve / Approve with conditions / Reject] | YYYY-MM-DD |
| Application security lead | [@name] | [Decision] | YYYY-MM-DD |
| SRE lead | [@name] | [Decision] | YYYY-MM-DD |
| Engineering director | [@name] | [Decision] | YYYY-MM-DD |
Revision history
| Version | Date | Author | Change summary |
|---|
| 0.1 | YYYY-MM-DD | [@name] | First draft |
| 1.0 | YYYY-MM-DD | [@name] | Example: Approved; signature verification at admission set to enforce |
| 1.1 | YYYY-MM-DD | [@name] | Example: Production deploy job moved to isolated runners after PIPE-RSK-002 |
Contents
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
| In scope | Out of scope |
|---|
| Example: Container images for 41 backend services and the web storefront | Mobile apps (separate store-release pipeline, see [link]) |
| Example: Helm charts and environment configuration in the deploy repository | Infrastructure modules, covered by IaC Module Specification (ops/iac-module-specification) |
| Example: Shared libraries published to the internal package registry | Data pipelines and notebooks |
| [Item] | [Item] |
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
- Fast feedback: a developer learns whether a change is good within minutes, so that small batches and trunk-based development stay practical.
- Integrity: every production artefact can be traced to a reviewed commit, a known build platform and a signed provenance statement.
- Safe release: changes reach production through staged exposure with automated health checks and a tested rollback path.
- Least privilege: no job holds more access than its step needs, and no long-lived production credential exists in the pipeline.
- Self-service: service teams adopt the pipeline by configuration, not by copying scripts.
2.2 Requirements
| ID | Requirement | Acceptance condition | Source |
|---|
| PIPE-REQ-001 (Example) | Builds run on a hosted or platform-managed build service, never on developer machines | 100% of production artefacts carry provenance naming the approved builder identity | SLSA Build L2; SSDF PO.3 |
| PIPE-REQ-002 (Example) | Each build runs in an ephemeral, isolated environment | Runner is created per job and destroyed after it; no shared cache writable by untrusted jobs | SLSA Build L3; SP 800-204D |
| PIPE-REQ-003 (Example) | Provenance and signatures are generated by the platform, not by user-defined steps | Signing key or identity is not reachable from build steps | SLSA Build L3; SSDF PS.2 |
| PIPE-REQ-004 (Example) | Every artefact released to production has an SBOM bound to its digest | SBOM attestation present for each image digest in the release registry | SSDF PS.3; SBOM and VEX Policy (security/sbom-vex-policy) |
| PIPE-REQ-005 (Example) | Production deployments use short-lived, workload-bound credentials | No static cloud keys in CI secret stores; OIDC federation only | SSDF PO.5; CICD-SEC-6 |
| PIPE-REQ-006 (Example) | Commit-to-feedback time for the pull request pipeline is at most 10 minutes at the 90th percentile | Measured weekly from pipeline events | Developer experience |
| PIPE-REQ-007 (Example) | Production rollout is staged and halts automatically on health regression | Canary analysis gate configured for every tier 1 service | Safe Software Deployment |
| PIPE-REQ-008 (Example) | Pipeline definitions are versioned, reviewed and protected like production code | Changes to the shared pipeline need platform team approval, made mandatory by a ruleset required-reviewer rule | CICD-SEC-1; CICD-SEC-4; SSDF PS.1 |
| [PIPE-REQ-NNN] | [Requirement] | [Condition] | [Source] |
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
| Component | Role | Trust level | Credentials it holds | Owner |
|---|
| Source platform (Example) | Hosts repositories, enforces rulesets and code owner review | High | None issued to jobs beyond scoped tokens | Platform team |
| CI orchestrator (Example) | Schedules jobs from versioned pipeline definitions | High | OIDC issuer for job identities | Platform team |
| PR runners (Example) | Run checks for pull requests, including from forks | Untrusted | None; read-only token | Platform team |
| Build runners (Example) | Build and test from protected branches and tags | Trusted, isolated per job | Registry push via short-lived token | Platform team |
| Signing service (Example) | Generates provenance and signs by digest outside user steps | High | Signing identity (keyless, short-lived certificate) | Platform team and AppSec |
| Artefact registry (Example) | Stores images, SBOMs and attestations, immutable tags | High | Pull credentials for clusters | Platform team |
| Deploy controller (Example) | Reconciles cluster state from the deploy repository | High | Cluster write within namespaces | SRE team |
| [Component] | [Role] | [Level] | [Credentials] | [@owner] |
3.3 Pipeline as code
| Decision | Choice |
|---|
| Definition location | Example: Shared reusable workflows in corvid/pipeline-library, called by a 20-line file in each service repository |
| Versioning | Example: Library released with semantic versions; services pin a full commit SHA, updated by bot pull requests |
| Change control | Example: Library changes need two platform approvers and pass the library's own test suite |
| Configuration surface | Example: Service tier, language, test command, deploy targets; all other behaviour is fixed by the library |
4. Stages and quality gates
4.1 Stage list
| ID | Stage | Trigger | What runs | Blocking | Time budget (p90) |
|---|
| PIPE-STG-010 (Example) | Validate | Pull request | Lint, format, pipeline-definition lint, commit message check | Yes | 1 min |
| PIPE-STG-020 (Example) | Build and unit test | Pull request, main | Compile from lockfile, unit tests, coverage report | Yes | 4 min |
| PIPE-STG-030 (Example) | Static analysis | Pull request | SAST, secret scan, IaC scan, licence check | Yes on gate PIPE-GATE-002 | 3 min |
| PIPE-STG-040 (Example) | Dependency and image scan | Pull request, main | Software composition analysis, container scan | Yes on gate PIPE-GATE-003 | 2 min |
| PIPE-STG-050 (Example) | Package, SBOM, provenance and sign | Main, release tag | Build image once, push by digest, generate SBOM, platform provenance, signature | Yes | 3 min |
| PIPE-STG-060 (Example) | Deploy to staging | Main | Deploy controller syncs new digest | Yes | 5 min |
| PIPE-STG-070 (Example) | Integration, contract and smoke tests | After staging deploy | API contract tests, end-to-end smoke, DAST baseline | Yes | 10 min |
| PIPE-STG-080 (Example) | Production canary | Promotion approved | 5% of traffic, automated canary analysis | Yes on gate PIPE-GATE-006 | 30 min |
| PIPE-STG-090 (Example) | Production rollout | Canary passed | Progressive waves by region | Yes | 60 min |
| [PIPE-STG-NNN] | [Stage] | [Trigger] | [Jobs] | [Yes/No] | [Budget] |
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
| ID | Gate | Condition to pass | Waiver authority | Evidence kept |
|---|
| PIPE-GATE-001 (Example) | Tests | All unit tests pass; line coverage of changed code at least [80%] | Service tech lead, recorded on the pull request | Test report artefact |
| PIPE-GATE-002 (Example) | Static analysis | No new findings rated high or critical; no verified secret | AppSec lead, time-boxed exception | SARIF report |
| PIPE-GATE-003 (Example) | Dependencies | No known exploited vulnerability; no critical with a fix available; licence on allow-list | AppSec lead per Dependency Management Policy (dev/dependency-management-policy) | SCA report, VEX statements |
| PIPE-GATE-004 (Example) | Integrity | SBOM, provenance and signature exist for the digest | None | Attestations in registry |
| PIPE-GATE-005 (Example) | Staging health | Smoke and contract tests pass; error rate within service SLO | Service owner | Test report, dashboard link |
| PIPE-GATE-006 (Example) | Canary analysis | Canary error rate and p95 latency not worse than baseline by more than [10%] over 30 minutes | SRE on call, during incident only | Canary analysis record |
| PIPE-GATE-007 (Example) | Change window and freeze | Deployment not inside a declared freeze unless an emergency change is approved | Change manager per Change Request (ops/change-request) | Change record |
| [PIPE-GATE-NNN] | [Gate] | [Condition] | [Authority] | [Evidence] |
4.3 Gate rules
- A blocking gate fails closed: when the scanner or service behind it is unavailable, the stage fails rather than passes.
- 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).
- 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.
- 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
| Environment | Purpose | Data | Deploy trigger | Access to deploy | Parity with production |
|---|
| Preview (Example) | Per pull request review environment | Synthetic | Pull request label | Pipeline only | Same chart, reduced replicas |
| Staging (Example) | Integration and release verification | Synthetic and masked samples | Merge to main | Pipeline only | Same chart, same configuration keys, smaller scale |
| Production canary (Example) | Limited real traffic | Production | Promotion approval or automatic for tier 3 | Pipeline only | Identical |
| Production (Example) | All customers, three regions | Production | Canary pass | Pipeline only | Reference |
| [Environment] | [Purpose] | [Data] | [Trigger] | [Who] | [Parity] |
5.2 Promotion rules
| Service tier | Staging to canary | Canary to full rollout | Out-of-hours deploys |
|---|
| Tier 1 (Example) | One approval by a release approver who is not the author | Automatic after PIPE-GATE-006 | Not allowed except emergency changes |
| Tier 2 (Example) | Automatic after PIPE-GATE-005 | Automatic after PIPE-GATE-006 | Allowed with on-call acknowledgement |
| Tier 3 (Example) | Automatic | Automatic | Allowed |
| [Tier] | [Rule] | [Rule] | [Rule] |
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
| Target | Authentication method | Scope | Lifetime |
|---|
| Cloud account (deploy) (Example) | OIDC federation from the CI job identity, trust bound to repository, workflow file and protected branch or tag | Single role per environment | 15 minutes |
| Artefact registry (Example) | Short-lived token from OIDC exchange | Push to one repository path | Job duration |
| Signing (Example) | Keyless signing with a short-lived certificate bound to the workflow identity | Sign by digest | Minutes |
| Package registry publish (Example) | Trusted publishing from release tag workflows | One package | Job duration |
| [Target] | [Method] | [Scope] | [Lifetime] |
6.2 Secrets handling
- 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.
- Scope each secret to the environment and workflow that need it. Pull request workflows from forks receive no secrets.
- Mask secrets in logs and fail the job if a secret pattern appears in an uploaded artefact.
- Rotate any secret that a job printed, cached or uploaded, and record the event as a security incident.
6.3 Pipeline permissions
| Control | Setting |
|---|
| Default job token (Example) | Read-only on contents; write permissions declared per job |
| Who can edit pipeline definitions (Example) | Changes to .ci/ and the shared library require platform team approval: CODEOWNERS requests it and a ruleset required-reviewer rule makes it mandatory, because any one listed code owner can otherwise satisfy code owner review (see Code Ownership Policy, dev/code-ownership-policy) |
| Who can approve production promotion (Example) | Members of the release-approvers group; author cannot approve their own change |
| Third-party actions and plugins (Example) | Allow-listed and pinned by full commit SHA |
| Self-hosted runner registration (Example) | Only through the platform's runner controller; manual registration disabled |
| [Control] | [Setting] |
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
| SLSA Build requirement | How this pipeline meets it | Status |
|---|
| Choose an appropriate build platform (producer) | Builds from protected branches and tags run only on the trusted, isolated build runners in 3.2; PR runners never produce release artefacts | Example: Met |
| Follow a consistent build process (producer) | Shared pipeline library; services cannot override build steps | Example: Met |
| Distribute provenance (producer) | Provenance attached to the image digest in the registry (7.3) | Example: Met |
| Provenance exists (L1) | Platform generates in-toto provenance for every image | Met |
| Hosted build platform (L2) | Builds run only on platform runners; developer pushes to registry are blocked | Met |
| Provenance is authentic (L2) | Provenance signed by the platform signing identity | Met |
| Isolated builds (L3) | Ephemeral runners per job; caches keyed and read-only for untrusted jobs | Partial: shared cache for PR runners (PIPE-RSK-003) |
| Provenance is unforgeable (L3) | Signing happens in a separate trusted job that build steps cannot reach | Met |
| [Requirement] | [Implementation] | [Status] |
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
| Item | Decision |
|---|
| Artefact identity (Example) | Image digest; tags are labels only and are immutable in the release registry |
| SBOM (Example) | CycloneDX JSON generated in PIPE-STG-050 from the lockfile and image layers; attached as an attestation to the digest |
| Provenance (Example) | SLSA provenance predicate in an in-toto attestation |
| Signature (Example) | Keyless signature, recorded in a transparency log |
| Verification points (Example) | Deploy controller admission policy (enforce); customer-facing verification instructions in release notes |
| Retention (Example) | Artefacts and attestations kept for the support life of the version plus [2 years], per SSDF PS.3 |
| Vulnerability statements (Example) | VEX documents produced per SBOM and VEX Policy (security/sbom-vex-policy) |
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
| Tier | Strategy | Halt signal | Rollback method | Target rollback time |
|---|
| Tier 1 (Example) | Canary then regional waves | PIPE-GATE-006 failure or SLO burn-rate alert | Controller reverts to previous digest | 5 minutes |
| Tier 2 (Example) | Rolling update with readiness probes | Failed readiness, error-rate alert | Revert promotion pull request | 10 minutes |
| Tier 3 (Example) | Rolling update | Failed readiness | Revert promotion pull request | 30 minutes |
| [Tier] | [Strategy] | [Signal] | [Method] | [Time] |
8.2 Rules for safe deployment
- Separate deploy from release: ship code dark behind a flag where the change is user-visible, following Feature Flag Policy (
dev/feature-flag-policy).
- 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.
- Keep at least the previous [two] production digests deployable (images retained, configuration compatible).
- Practise rollback: every tier 1 service performs a rollback in staging at least [once per quarter], recorded in the deployment log.
- 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].
- 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.
| OWASP ID | Short title | Control in this design | Residual risk |
|---|
| CICD-SEC-1 | Insufficient Flow Control Mechanisms | Protected main and tags; promotion approval for tier 1; no direct pushes | Example: Low |
| CICD-SEC-2 | Inadequate Identity and Access Management | SSO with MFA on source platform; quarterly access review; no shared accounts | Low |
| CICD-SEC-3 | Dependency Chain Abuse | Package proxy, lockfiles, hash checks, cooldown for new versions | Medium |
| CICD-SEC-4 | Poisoned Pipeline Execution (PPE) | Fork pull requests run on untrusted runners without secrets; pipeline files code-owned | Medium (PIPE-RSK-001) |
| CICD-SEC-5 | Insufficient PBAC (Pipeline-Based Access Controls) | Per-job permissions, per-environment OIDC roles | Low |
| CICD-SEC-6 | Insufficient Credential Hygiene | No static cloud keys; secrets manager; log masking | Low |
| CICD-SEC-7 | Insecure System Configuration | Runner images built and patched by platform; hardened controller | Medium |
| CICD-SEC-8 | Ungoverned Usage of 3rd Party Services | Allow-list of integrations and actions, pinned by SHA | Medium |
| CICD-SEC-9 | Improper Artifact Integrity Validation | Signature and provenance verified at admission | Low |
| CICD-SEC-10 | Insufficient Logging and Visibility | Pipeline audit logs forwarded to the security log platform | Low |
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
| Metric | Definition used here | Formula | Data source |
|---|
| Change lead time | Time from commit on main to running in production | Median of (production deploy time minus commit time) per change | Pipeline events and deploy controller |
| Deployment frequency | Production deployments per service per week | Count of successful production deployments / weeks | Deploy controller |
| Change fail rate | Share of deployments that need immediate intervention | Deployments followed by rollback or hotfix / all deployments | Deploy controller and incident tool |
| Failed deployment recovery time | Time to recover from a failed deployment | Median of (recovery time minus failure detection time) | Incident tool |
| Deployment rework rate | Share of deployments that are unplanned and caused by a production incident | Unplanned incident-driven deployments / all deployments | Deploy records tagged by cause |
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
| ID | Metric | Target | Owner |
|---|
| PIPE-MET-001 (Example) | Pull request pipeline duration p90 | At most 10 minutes | Platform team |
| PIPE-MET-002 (Example) | Pipeline success rate on main excluding genuine test failures | At least 98% | Platform team |
| PIPE-MET-003 (Example) | Flaky test rate (tests that both pass and fail on the same commit) | Below 1% of test cases | Service teams |
| PIPE-MET-004 (Example) | Queue time for runners p90 | At most 60 seconds | Platform team |
| PIPE-MET-005 (Example) | Share of production digests with SBOM, provenance and signature | 100% | AppSec |
| [PIPE-MET-NNN] | [Metric] | [Target] | [@owner] |
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
| Activity | Platform team | Service team | AppSec | SRE | Release manager |
|---|
| Operate CI platform and runners | A/R | I | C | C | I |
| Maintain pipeline library | A/R | C | C | C | I |
| Define security gates and thresholds | C | I | A/R | I | I |
| Fix failing service tests | I | A/R | I | I | I |
| Approve tier 1 production promotion | I | R | I | C | A |
| Respond to pipeline outage | R | I | I | A | I |
| Review this design | R | C | C | C | A |
R = responsible, A = accountable, C = consulted, I = informed. One A per row.
11.2 Support and change rules
- 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.
- 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).
- Changes to gates or thresholds are announced [two weeks] ahead in the engineering channel, run in warn mode for [one week], then enforce.
- 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
| ID | Decision | Rationale | Alternatives considered | ADR |
|---|
| PIPE-DEC-001 (Example) | Pull-based deployment through a controller reading a deploy repository | CI never holds cluster credentials; desired state is auditable | Push from CI with cluster admin token | [ADR-014] |
| PIPE-DEC-002 (Example) | Shared pipeline library pinned by SHA | Consistent controls with safe upgrades | Copy-paste templates per repository | [ADR-015] |
| PIPE-DEC-003 (Example) | Keyless signing bound to workflow identity | No key management; identity is verifiable | Long-lived signing key in a key vault | [ADR-016] |
| [PIPE-DEC-NNN] | [Decision] | [Rationale] | [Alternatives] | [Link] |
Record each decision in Architecture Decision Record (dev/adr).
12.2 Risks
| ID | Risk | Likelihood | Impact | Treatment | Owner | Due |
|---|
| PIPE-RSK-001 (Example) | A maintainer approves a malicious pipeline change from a compromised account | Low | High | Require two platform approvers for library changes; alert on pipeline file changes | [@platform-lead] | YYYY-MM-DD |
| PIPE-RSK-002 (Example) | Production deploy job shares a runner pool with builds | Medium | High | Move deploy jobs to a dedicated isolated pool | [@platform-lead] | YYYY-MM-DD |
| PIPE-RSK-003 (Example) | Shared dependency cache could be poisoned by an untrusted job | Medium | Medium | Separate caches for trusted and untrusted runners | [@platform-lead] | YYYY-MM-DD |
| PIPE-RSK-004 (Example) | Scanner outage blocks all merges because gates fail closed | Medium | Medium | Documented emergency waiver path; scanner redundancy | [@appsec-lead] | YYYY-MM-DD |
| [PIPE-RSK-NNN] | [Risk] | [L] | [I] | [Treatment] | [@owner] | YYYY-MM-DD |
13. Acceptance criteria and traceability
13.1 Acceptance criteria
- Every tier 1 service runs on the shared pipeline library at a supported major version.
- PIPE-MET-005 is 100% for [four consecutive weeks].
- The admission policy rejects an unsigned test image in production (negative test recorded).
- A rollback of a tier 1 service in staging completes within its target time and is logged.
- No static cloud credential remains in any CI secret store (scan evidence attached).
13.2 Traceability matrix
| Requirement | Implemented by | Verified by | Evidence | Standard reference |
|---|
| PIPE-REQ-001 (Example) | PIPE-STG-050, registry push restrictions | Provenance builder check at admission | Admission logs | SLSA Build L2; SSDF PO.3 |
| PIPE-REQ-002 (Example) | Ephemeral runner pools (3.2) | Runner lifecycle audit | Runner controller logs | SLSA Build L3; SP 800-204D |
| PIPE-REQ-003 (Example) | Signing service outside user steps (7.2) | Design review, penetration test of pipeline | Review record | SLSA Build L3; SSDF PS.2 |
| PIPE-REQ-004 (Example) | PIPE-STG-050, PIPE-GATE-004 | PIPE-MET-005 | Registry attestation report | SSDF PS.3 |
| PIPE-REQ-005 (Example) | OIDC federation (6.1) | Secret store scan | Scan report | SSDF PO.5; CICD-SEC-6 |
| PIPE-REQ-006 (Example) | Parallel PR stages (4.1) | PIPE-MET-001 | Weekly metrics | Developer experience |
| PIPE-REQ-007 (Example) | PIPE-STG-080, PIPE-GATE-006 | Canary records | Deployment log | Safe Software Deployment |
| PIPE-REQ-008 (Example) | Code-owned pipeline files with a required-reviewer rule (6.3) | Ruleset export | Ruleset configuration | CICD-SEC-1; CICD-SEC-4; SSDF PS.1 |
| [PIPE-REQ-NNN] | [Stage or control] | [Method] | [Evidence] | [Reference] |
14. Glossary and references
14.1 Glossary
| Term | Meaning in this document |
|---|
| Artefact | Built output that is deployed or distributed, identified by its digest |
| Attestation | Signed statement about an artefact, such as provenance or an SBOM |
| Build once, promote | Deploying the same artefact digest to each environment instead of rebuilding |
| Canary | Small share of production traffic that receives a new version first |
| Gate | Automated or human check that must pass before a stage proceeds |
| OIDC federation | Exchanging a job identity token for short-lived cloud credentials |
| Provenance | Verifiable record of how, where and from what source an artefact was built |
| Poisoned pipeline execution | Running attacker-controlled code in a pipeline by changing its definition or inputs |
| SBOM | Software bill of materials: inventory of components in an artefact |
| Waiver | Approved, time-limited exception to a gate |
14.2 References
| Reference | Version or date checked | Use |
|---|
| NIST SP 800-204D, Strategies for the Integration of Software Supply Chain Security in DevSecOps CI/CD Pipelines, csrc.nist.gov | Final, 2024-02-12 | CI/CD supply chain security strategies |
| NIST SP 800-218, SSDF Version 1.1, csrc.nist.gov | Final, 2022-02-03 | Practices PO.3, PO.5, PS.1 to PS.3 |
| NIST SP 800-218 Rev. 1, SSDF Version 1.2, csrc.nist.gov | Initial public draft, 2025-12-17 (not final) | Watch for changes to release and update practices |
| SLSA specification, slsa.dev | v1.2, approved; checked 2026-10-24 | Build and Source track requirements |
| OWASP Top 10 CI/CD Security Risks, owasp.org | Project page checked 2026-10-24 | Risk identifiers and short titles |
| CISA, FBI and ASD's ACSC, Safe Software Deployment: How Software Manufacturers Can Ensure Reliability for Customers | October 2024 | Staged rollout, testing and emergency playbook themes |
| DORA metrics guide, dora.dev | Page updated 2026-01-05 | Five software delivery metrics |
| OpenSSF Scorecard, github.com/ossf/scorecard | v5.6.0 | Repository checks such as Dangerous-Workflow and Token-Permissions |
| [Internal platform documentation] | [Version] | [Use] |
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.