Skip to main content
Environment progression rules ensure that releases are deployed to prerequisite environments before they can proceed to downstream environments. This enforces a deployment pipeline where changes must pass through QA before staging, and staging before production.

​
Overview

​
Why Use Environment Progression?

Environment progression rules help you:
  • Enforce deployment order - Prevent skipping environments in your pipeline
  • Catch issues early - Problems surface in lower environments first
  • Build confidence - Each environment validates before the next
  • Meet compliance - Satisfy audit requirements for change promotion

​
Configuration

Add an environment progression rule to your policy: 
policies:
  - name: staging-requires-qa
    selectors:
      - environment: environment.name == "staging"
    rules:
      - environmentProgression:
          dependsOnEnvironmentSelector:
            matchLabels:
              name: qa

​
Properties

​
environmentProgression.dependsOnEnvironmentSelector
object
required
Selector for the prerequisite environment(s). The release must be successfully deployed to environments matching this selector before proceeding.
​
environmentProgression.minimumSuccessPercentage
float
default:"100"
Percentage of targets in the prerequisite environment that must succeed (0-100). Use a lower value if some targets are expected to be unavailable.
​
environmentProgression.successStatuses
array
Job statuses considered successful. Defaults to standard success statuses.
​
environmentProgression.minimumSoakTimeMinutes
integer
default:"0"
Minutes to wait after the dependency succeeds before allowing progression. Use this to ensure the release has time to stabilize.
​
environmentProgression.maximumAgeHours
integer
Maximum age (in hours) of the dependency deployment. If the prerequisite deployment is older than this, progression is blocked until redeployed.

​
Common Patterns

​
Simple Linear Progression

Enforce QA → Staging → Production order: 
policies:
  # Staging requires QA success
  - name: staging-requires-qa
    selectors:
      - environment: environment.name == "staging"
    rules:
      - environmentProgression:
          dependsOnEnvironmentSelector:
            matchLabels:
              name: qa

  # Production requires Staging success
  - name: production-requires-staging
    selectors:
      - environment: environment.name == "production"
    rules:
      - environmentProgression:
          dependsOnEnvironmentSelector:
            matchLabels:
              name: staging

​
Soak Time Requirements

Require the release to “soak” in staging before production: 
policies:
  - name: production-soak-requirement
    selectors:
      - environment: environment.name == "production"
    rules:
      - environmentProgression:
          dependsOnEnvironmentSelector:
            matchLabels:
              name: staging
          minimumSoakTimeMinutes: 60 # 1 hour soak in staging

​
Freshness Requirements

Block promotion if the staging deployment is too old: 
policies:
  - name: production-freshness
    selectors:
      - environment: environment.name == "production"
    rules:
      - environmentProgression:
          dependsOnEnvironmentSelector:
            matchLabels:
              name: staging
          maximumAgeHours: 24 # Must be deployed to staging within last 24 hours

​
Partial Success Threshold

Allow promotion when most (not all) targets succeed: 
policies:
  - name: staging-partial-success
    selectors:
      - environment: environment.name == "staging"
    rules:
      - environmentProgression:
          dependsOnEnvironmentSelector:
            matchLabels:
              name: qa
          minimumSuccessPercentage: 80 # 80% of QA targets must succeed

​
Complete Pipeline with All Options

Full-featured production gate: 
policies:
  - name: production-full-gate
    selectors:
      - environment: environment.name == "production"
    rules:
      - approval:
          required: 1
      - environmentProgression:
          dependsOnEnvironmentSelector:
            matchLabels:
              name: staging
          minimumSuccessPercentage: 100
          minimumSoakTimeMinutes: 30
          maximumAgeHours: 48
      - gradualRollout:
          rolloutType: linear
          timeScaleInterval: 300

​
Progression Lifecycle

​
1. Version Created

A new deployment version is created and ready for release.

​
2. Lower Environment Deployment

The version is deployed to the prerequisite environment (e.g., QA).

​
3. Success Evaluation

Ctrlplane evaluates if the deployment meets success criteria:
  • Job status matches successStatuses
  • Success percentage meets minimumSuccessPercentage

​
4. Soak Time (if configured)

If minimumSoakTimeMinutes is set, the clock starts after success.

​
5. Progression Allowed

Once all criteria are met, the version can proceed to the next environment.

​
Environment Selector Examples

​
By Name

dependsOnEnvironmentSelector:
  matchLabels:
    name: staging

​
By Multiple Names

dependsOnEnvironmentSelector:
  matchExpression:
    - key: name
      operator: In
      values: ["qa", "integration"]

​
By Metadata

dependsOnEnvironmentSelector:
  matchLabels:
    tier: lower

​
Best Practices

​
Timing Guidelines

TransitionSoak TimeMax AgeNotes
Dev → QA0-Fast iteration
QA → Staging0-15 min24hQuick validation
Staging → Production30-60 min48hThorough soak
Critical services2-4 hours24hExtended observation

​
Recommendations

  • ✅ Start with simple progression, add soak time later
  • ✅ Use maximumAgeHours to prevent stale promotions
  • ✅ Combine with verification for automated quality gates
  • ✅ Use lower minimumSuccessPercentage for environments with flaky tests
  • ✅ Document your progression requirements for the team

​
Next Steps