Deployment Provenance

Overview

P0 Safety & Integrity - Deployment provenance establishes immutable traceability from running artifact back to source commit, build process, and deployment actor. Critical for audit compliance, security incident response, and confident rollback decisions.

REQUIRED: superpowers:verification-before-completion

When to Use

• Deploying to production or staging environments
• Setting up CI/CD pipelines for any deployable artifact
• Investigating production incidents requiring deployment history
• Establishing audit compliance for regulated environments
• Enabling confident rollback decisions

Core Workflow

1. Source Identification: Tag or record exact commit SHA deployed
2. Build Provenance: Capture build number, pipeline, and build timestamp
3. Artifact Signing: Sign artifacts cryptographically (optional but recommended)
4. Deployment Recording: Log deployment timestamp, environment, and actor
5. Artifact Labelling: Embed provenance metadata in artifact (labels, manifests)
6. Audit Trail: Persist deployment records to immutable store
7. Verification: Validate provenance chain before and after deployment

Provenance Record Schema

Every deployment MUST capture:

Implementation Patterns

Container Deployments

LABEL org.opencontainers.image.revision="${GIT_SHA}"
LABEL org.opencontainers.image.created="${BUILD_TIMESTAMP}"
LABEL org.opencontainers.image.source="${REPO_URL}"
LABEL com.example.build-id="${BUILD_ID}"
LABEL com.example.pipeline-url="${PIPELINE_URL}"

Kubernetes Deployments

metadata:
  annotations:
    deployment.kubernetes.io/revision: "1"
    app.example.com/git-sha: "${GIT_SHA}"
    app.example.com/build-id: "${BUILD_ID}"
    app.example.com/deployed-by: "${ACTOR}"
    app.example.com/deployed-at: "${DEPLOY_TIMESTAMP}"

Application Version Endpoints

Expose /version or /health endpoint returning provenance:

{
  "version": "1.2.3",
  "commit": "a1b2c3d4",
  "build": "12345",
  "built_at": "2025-01-15T10:30:00Z",
  "environment": "production"
}

Audit Trail Storage

Store deployment records in an append-only audit log:

• Git-based: Deployment log file in ops repository
• Database: Append-only table with deployment events
• External: Audit systems (Splunk, CloudTrail, Azure Monitor)

Minimum retention: Follow organisational compliance requirements (typically 1-7 years).

Verification Checklist

Before deployment:

• Commit SHA matches expected release
• Build provenance chain intact (commit to artifact)
• Artifact digest matches build output
• Signature valid (if signing enabled)
• Deployment actor authorised for target environment

After deployment:

• Version endpoint returns expected provenance
• Deployment event recorded in audit log
• Rollback target identified (previous deployment record)

Red Flags - STOP

• "We deploy from local builds" - No reproducibility or audit trail
• "Version is just a timestamp" - Cannot trace to source code
• "Anyone can deploy to production" - No actor accountability
• "We don't track what's deployed" - Incident investigation impossible
• "Rollback means redeploy latest main" - May not match previous state

All mean: Establish provenance tracking before proceeding with deployment.

Tooling Integration

Related Practices

• SLSA Framework: Supply-chain Levels for Software Artifacts
• Sigstore: Keyless signing and verification
• SBOM: Software Bill of Materials for dependency provenance
• GitOps: Git as single source of truth for deployments