How to Document a Pipeline as a Control Mapping
A version-controlled table that maps each control to its workflow step and its evidence turns your pipeline into self-documenting compliance.
Auditors want to see the mapping from a control to where it is enforced and what evidence it emits. Keep that mapping in the repo next to the workflows so it stays current. This page shows the structure; it is educational, not a certified control set.
Steps
- List each control your pipeline enforces.
- Map it to the workflow, job, or setting that implements it.
- Note the evidence artifact and where it is stored.
controls.md
docs/controls.md
# CI/CD Control Mapping (educational, review with your auditor)
| Control | Enforced by | Evidence |
|-----------------------------|-------------------------------------|--------------------------------|
| Peer review of changes | Branch protection, 2 approvals | PR reviews export (JSON) |
| Separation of duties | Protected env required reviewers | Deployment approvals export |
| Vulnerability management | Trivy gate (HIGH,CRITICAL) | Scan report artifact |
| Change ticket linkage | Deploy job ticket check | Deployment record + ticket id |
| Immutable audit trail | S3 Object Lock archive | Locked log objects + checksum |Notes
- Keep controls.md in review scope so a control change and its doc land together.
- Link each row to the exact workflow file and the evidence export command.
Related guides
How to Collect CI Evidence for an AuditExport GitHub Actions workflow runs, approvals, and reviews with the gh CLI and REST API to produce audit evi…
How to Use Required Status Checks as ControlsMake security and compliance jobs required status checks in GitHub so a pull request cannot merge until the s…
How to Run Automated Compliance Checks With tfsec and CISRun automated compliance checks in GitHub Actions with tfsec for Terraform and a CIS benchmark scan, failing…