Promotion Pipeline
Complete guide to pipeline configuration, stage progression, promotion approvals, and controlled environment-to-environment movement.
What Is Promotion
Promotion is the controlled movement of proven changes from one environment to the next — for example, staging → production. Instead of manually recreating configuration in each environment, promotion carries forward the exact set of workload versions, variable overrides, and binding configurations that succeeded in the source environment.
Promotion ensures that only validated configurations progress through your deployment pipeline, reducing the risk of environment-specific configuration errors.
Core Principle
Promotion answers the question: "This configuration works in staging — apply the exact same configuration to production." It eliminates manual re-entry and reduces drift between environments.
Pipeline Concept
A promotion pipeline defines the directed graph of environment-to-environment transitions for a project. Each node in the graph is a stage (mapped to an environment), and each edge defines a valid promotion path with its own approval requirements.
Key characteristics:
- Pipelines are project-scoped — each project has its own pipeline definition.
- Stages are ordered but can support parallel paths (e.g., dev → staging AND dev → qa simultaneously).
- Each stage transition defines a
RequiredApprovalscount (0 = auto-approve). - The pipeline is purely a governance construct — it does not dictate deployment mechanics, which are handled by the release and delivery systems.
Pipeline Editor
The pipeline editor is accessible at /projects/:slug/settings under the Pipeline tab.
Visual Editor
The pipeline editor is built with React Flow, providing a visual drag-and-drop interface:
Stages represent environments in your deployment pipeline. Click "Add Stage" to add an environment to the pipeline. Each stage displays as a node with the environment name, color badge, and current policy summary. Drag stages to reorder the visual layout. A stage must be mapped to an existing environment in the project.
Transitions define which promotions are allowed. Draw a connection from a source stage to a target stage to create a transition. Each transition is a directed edge — promotions flow in one direction. Parallel transitions are supported (one source to multiple targets). Invalid transitions (e.g., creating cycles) are blocked by the editor.
Policies control governance per transition. Click a transition edge to configure the number of required approvals (0 = auto-approve).
Pipeline Configuration Example
Each PromotionStage has three fields: From, To, and RequiredApprovals.
Source (From) | Target (To) | Required Approvals |
|---|---|---|
dev | staging | 0 (auto) |
dev | qa | 0 (auto) |
staging | production | 2 |
qa | production | 1 |
Promotion Request Flow
When a team member wants to promote changes from one environment to another, they create a promotion request that flows through the configured approval pipeline.
Step-by-Step
Initiate promotion. From the source environment's deployment view, click "Promote." Select the target environment from the available transitions in the pipeline.
Review the promotion preview. The preview shows a detailed diff of what will change in the target environment. This includes workload versions, HQ Variable differences, binding changes, and any configuration drift between source and target.
Submit the promotion request. Add optional notes explaining the promotion rationale. The request enters the approval queue if the transition requires approvals.
Approval (if required). Approvers review the promotion diff and approve or reject. When the approval quorum (configured via RequiredApprovals on the stage) is met, ApprovePromotion automatically executes the promotion — there is no separate execute step.
Execution (inside ApprovePromotion). Once quorum is met, the system copies the source environment's values into the target environment and creates a promotion release. If the target environment's DeployPolicy is Direct, the release auto-deploys and the promotion moves to completed. Otherwise (or if auto-deploy fails), the promotion moves to pending_release.
Verification. After execution, the promotion status is tracked in the promotion history. The target environment reflects the promoted changes. If the promotion is in pending_release, navigate to the target environment to trigger a manual deployment.
Promotion Preview
The promotion preview is the most critical safety tool in the promotion workflow. It answers: "What exactly will change in the target environment?"
Preview Contents
| Section | Description |
|---|---|
| Workload diff | Image tags, replica counts, and resource configurations that differ between source and target |
| Values diff | Helm values file differences after variable resolution |
| Binding diff | Kustomize and manifest binding changes |
| Variable diff | HQ Variables that have different values between source and target environments |
| Conflict indicators | Flags cases where the target has changes not present in the source (potential conflict) |
Reading the Preview
# Example promotion preview output
workloads:
api-gateway:
image_tag:
source: "v2.1.0" # What staging has
target: "v2.0.5" # What production currently has
action: "update" # Will update production to v2.1.0
worker:
image_tag:
source: "v1.8.0"
target: "v1.8.0"
action: "no_change" # Already in sync
variables:
REPLICA_COUNT:
source: "5"
target: "3"
action: "update" # Will update production to 5Review Variable Differences
Promoting from staging to production may carry staging-specific variable values. Always review the variable diff to ensure environment-appropriate values are preserved.
Promotion States
New promotion requests are always created with the pending_approval status. The system uses the following states:
| State | Description |
|---|---|
pending_approval | Request created. Awaiting approval quorum (RequiredApprovals on the stage). If RequiredApprovals is 0, the promotion is auto-approved and transitions immediately. |
completed | Approval quorum met, source values copied to target, promotion release created, and auto-deploy succeeded (target DeployPolicy is Direct). |
pending_release | Approval quorum met, source values copied to target, promotion release created, but auto-deploy was not attempted (target DeployPolicy is not Direct) or auto-deploy failed. A manual deployment in the target environment is required. |
rejected | An approver rejected the promotion request. |
No Separate Execute Step
There is no approved or executing intermediate state. When ApprovePromotion detects that the quorum is met, it immediately copies the source values into the target, creates a promotion release, and attempts auto-deploy based on the target's DeployPolicy. The promotion moves directly from pending_approval to either completed or pending_release.
Pending Release State
When a promotion reaches pending_release, the source values have been applied to the target environment and a promotion release has been created, but the target environment's DeployPolicy is not Direct (or auto-deploy failed). Navigate to the target environment to trigger a manual deployment.
Promotion History
The promotion history page (/projects/:slug/promotions) provides a complete audit trail:
| Column | Description |
|---|---|
| Timestamp | When the promotion was requested |
| Source → Target | The environment transition |
| Requester | Who initiated the promotion |
| Status | Current state of the promotion |
| Approvers | Who approved (or rejected) and when |
| Changes | Summary count of workload, variable, and binding changes |
| Duration | Time from request to completion |
Filtering
- By environment: Show only promotions targeting production
- By status: Show only failed or rejected promotions for investigation
- By requester: Show promotions initiated by a specific team member
- By date range: Narrow to a specific incident window
Approval Integration
Promotion approvals are part of the unified approvals system:
- Promotion requests requiring approval appear in the Approvals inbox (
/approvals) - Approvers see the full promotion preview (diffs, change summary, request notes)
- Approve or reject with comments
- Quorum enforcement: If the stage's
RequiredApprovalsis 2, both must be met before execution proceeds
Approval Notification Flow
When a promotion request is submitted:
- All users with
project.promotions.approvepermission are notified - Notification includes: source/target environments, change summary, request notes
- Approvers can approve from the notification link or from the Approvals inbox
- The requester is notified when the promotion is approved, rejected, or completed
Interaction with Environment Freeze
If the target environment is frozen, promotion behavior depends on the target environment's freeze configuration (this is an environment-level setting, not a per-stage setting):
- Promotion requests can still be submitted and approved while the target is frozen.
- Deployment in the target environment is gated by the freeze until it is lifted or a break-glass session overrides it.
Feature Gating
The promotion pipeline is gated behind the FeaturePromotion feature flag. When the feature flag is not enabled for a project, all promotion endpoints return a feature-not-available response.
| Plan | Capability |
|---|---|
| Free | Manual deployment only. No structured promotion pipeline. Changes are applied directly per environment. |
| Pro | Full pipeline editor with stage definitions and transitions. Approval policies per transition. Promotion preview and history. |
| Enterprise | All Pro features plus advanced policies and quorum requirements. |
API Routes
| Method | Route | Description |
|---|---|---|
GET | /api/v2/projects/{slug}/promotion/pipeline | Get the promotion pipeline configuration |
PUT | /api/v2/projects/{slug}/promotion/pipeline | Update the promotion pipeline configuration |
POST | /api/v2/projects/{slug}/promotion/preview | Generate a promotion preview (diff between source and target) |
POST | /api/v2/projects/{slug}/promotion/request | Create a new promotion request |
GET | /api/v2/projects/{slug}/promotions | List promotion requests for a project |
GET | /api/v2/promotions/{id} | Get a specific promotion request by ID |
POST | /api/v2/promotions/{id}/approve | Approve a promotion request |
POST | /api/v2/promotions/{id}/reject | Reject a promotion request |
Error Reference
| Error Code | Message | Meaning |
|---|---|---|
400 | invalid stage transition | The requested source → target transition is not defined in the pipeline |
404 | promotion not found | The promotion request ID does not exist or you lack access |
409 | you have already approved this promotion | Same approver attempted to approve the same request again |
423 | environment is frozen | Target environment is frozen and freeze gate is enforced |
409 | promotion already in progress | A promotion to the same target is already executing |
Best Practices
Define a clear promotion path. Most teams use dev → staging → production. Add a parallel QA track if your workflow requires it. Keep the graph simple — complexity in pipeline configuration leads to confusion.
Require approvals for production-bound promotions. Auto-approve for low-risk transitions (dev → staging) to maintain velocity, but always require human review before reaching production.
Use the promotion preview religiously. The preview catches issues that are invisible in the source environment — variable scope differences, binding conflicts, and unintended configuration drift.
Monitor promotion history for patterns. Frequent rollbacks after promotion indicate quality issues in the source environment. Frequent rejections indicate misalignment between requester and approver expectations.
Keep promotion requests focused. Promote related changes together, but avoid mega-promotions that bundle unrelated workload updates. Smaller promotions are easier to review and safer to roll back.