Promotion Record

A promotion record (kind: promotion-record) is a machine-written audit log documenting a version promotion through a progression. It captures what was promoted, how, gates evaluated, and final outcome.

Purpose

Promotion records enable:

Audit trail — complete history of when, who, and what was promoted
Compliance evidence — gate evaluation results prove promotion gates were checked
Rollback tracking — records link promotion to rollback operations
Deployment linking — records reference deployment manifests created during promotion
Version lineage — track version progression through rings (dev → staging → prod)

Conceptual Model

Entity	Role	When Created
Version Manifest	Input: desired versions	Operator edits
Promotion Record	Output: audit log	`strata promote start`
Version Lock	Snapshot: frozen versions	`strata promote` writes per-ring lock
Deployment Manifest	Deployment artifact	`strata deploy run` references promotion record

A promotion record documents the entire promotion workflow — from initiation through all ring waves to final outcome.

Schema

apiVersion: strata.huybrechts.xyz/v1
kind: promotion-record
meta:
  name: <record_name>            # e.g., prom-20260623-prd-001
  labels:
    target: <target_name>        # e.g., app, traefik
    ring: <ring_name>            # Target ring (e.g., prd)
    outcome: <outcome>           # completed | partial | rolled-back
  annotations:
    description: <description>
spec:
  # What was promoted
  target:
    type: remote | helm_chart | image
    name: <name>
    from_version: <version>      # Previous version
    to_version: <version>        # New version
  
  # How & where
  strategy: <strategy_name>      # Promotion strategy name
  progression: <progression_name>
  rings: [list]                  # Ordered rings from progression
  
  # Outcome
  outcome: completed | partial | rolled-back
  rollback_of: <promotion_record_name>  # If this is a rollback
  
  # Identity & timing
  initiated_by: <user>           # $USER or CI actor
  hostname: <hostname>           # Machine that ran strata
  started_at: <iso8601_utc>      # First wave commit timestamp
  completed_at: <iso8601_utc>    # Last wave commit timestamp (if completed)
  duration_seconds: <int>        # Calendar time elapsed
  
  # Git
  branch: promote/{target}-{version}-{ring}  # Promotion branch name
  commits:                       # Per-wave commits
    - ring_wave: <number>
      sha: <commit_sha>
      message: <message>
      committed_at: <iso8601_utc>
  
  # Gate results (compliance evidence)
  gates:                         # Gate evaluation results
    - gate: <gate_name>
      ring: <ring>
      require: any_one | all
      checked_at: <iso8601_utc>
      passed: <boolean>
      detail: <explanation>
  
  # Ring wave execution
  ring_waves:                    # Summary of each wave
    - ring_wave: <number>
      environments: [list]
      deployment_wave: <wave_name>
      deployments: <names_or_all>
      files_modified: [list]
      fields_removed: [list]
      committed_at: <iso8601_utc>
  
  # Links to deployment manifests
  deployment_manifests: [list]   # Paths to .strata/manifests/ files created by deploy

Example

apiVersion: strata.huybrechts.xyz/v1
kind: promotion-record
meta:
  name: prom-20260721-app-prd-001
  labels:
    target: app
    ring: prd
    outcome: completed
  annotations:
    description: "Promotion of app from v2.1.0 to v2.2.0 through dev→staging→prd"
spec:
  target:
    type: image
    name: app
    from_version: v2.1.0
    to_version: v2.2.0
  
  strategy: blue-green
  progression: prd-progression
  rings: [dev, staging, prd]
  
  outcome: completed
  
  initiated_by: alice
  hostname: ci-runner-1
  started_at: "2026-07-21T14:23:45Z"
  completed_at: "2026-07-21T14:35:12Z"
  duration_seconds: 687
  
  branch: promote/app-v2.2.0-prd
  commits:
    - ring_wave: 1
      sha: abc123def456...
      message: "Wave 1: dev - app v2.1.0→v2.2.0"
      committed_at: "2026-07-21T14:24:00Z"
    - ring_wave: 2
      sha: def456abc789...
      message: "Wave 2: staging - app v2.1.0→v2.2.0"
      committed_at: "2026-07-21T14:29:15Z"
    - ring_wave: 3
      sha: abc789def012...
      message: "Wave 3: prd - app v2.1.0→v2.2.0"
      committed_at: "2026-07-21T14:35:00Z"
  
  gates:
    - gate: require_progression_order
      ring: dev
      require: any_one
      checked_at: "2026-07-21T14:23:50Z"
      passed: true
    - gate: require_progression_order
      ring: staging
      require: any_one
      checked_at: "2026-07-21T14:29:10Z"
      passed: true
    - gate: require_progression_order
      ring: prd
      require: all
      checked_at: "2026-07-21T14:34:50Z"
      passed: true
  
  ring_waves:
    - ring_wave: 1
      environments: [dev]
      deployment_wave: all
      deployments: all
      files_modified:
        - versions/dev.yaml
      committed_at: "2026-07-21T14:24:00Z"
    - ring_wave: 2
      environments: [staging]
      deployment_wave: all
      deployments: all
      files_modified:
        - versions/staging.yaml
      committed_at: "2026-07-21T14:29:15Z"
    - ring_wave: 3
      environments: [prd]
      deployment_wave: canary
      deployments: [canary-deployment]
      files_modified:
        - versions/prd.yaml
      committed_at: "2026-07-21T14:35:00Z"
  
  deployment_manifests:
    - .strata/manifests/prom-20260721-app-prd-001/dev-manifest.yaml
    - .strata/manifests/prom-20260721-app-prd-001/staging-manifest.yaml
    - .strata/manifests/prom-20260721-app-prd-001/prd-manifest.yaml

Key Fields

Field	Type	Required	Description
`meta.name`	string	Yes	Unique record identifier (e.g., `prom-{date}-{target}-{ring}-{seq}`)
`meta.labels.target`	string	No	Artifact name being promoted (for filtering)
`meta.labels.ring`	string	No	Target ring (for filtering)
`meta.labels.outcome`	string	No	Outcome status (for filtering)
`spec.target`	object	Yes	What was promoted: type, name, from/to versions
`spec.strategy`	string	Yes	Promotion strategy name
`spec.progression`	string	Yes	Progression name
`spec.outcome`	string	Yes	`completed` \| `partial` \| `rolled-back`
`spec.initiated_by`	string	Yes	User or CI actor
`spec.started_at`	string	Yes	ISO 8601 UTC timestamp
`spec.branch`	string	Yes	Promotion branch name
`spec.gates`	array	No	Gate evaluation results (compliance evidence)
`spec.ring_waves`	array	No	Per-wave execution summaries
`spec.deployment_manifests`	array	No	Links to deployment manifests

Workflow

Initiating a Promotion

strata promote start --target image:app:v2.2.0 --progression prd-progression
# Writes promotion-record at .strata/promotions/records/

Viewing Promotion History

# List all promotion records
strata promote history

# View details of a specific record
strata promote show prom-20260721-app-prd-001

Rollback

strata promote rollback prom-20260721-app-prd-001
# Creates new promotion-record with rollback_of reference
# Restores previous version state

Storage

Promotion records are stored locally in .strata/promotions/records/ and are typically committed to git as part of the promotion branch. They provide a complete audit trail of all promotions.

Relationship to Other Kinds

Version Manifest → Input: desired versions
Promotion Record → Output: audit log of promotion workflow
Version Lock → Snapshot: frozen versions per-ring after promotion
Deployment Manifest → Final artifact: infrastructure to be deployed