Promotion Lifecycle

The promotion lifecycle defines how solutions progress through environments from development to production.

What is Promotion?

Promotion moves a solution version from one environment to the next:

Environment Progression

Standard Pipeline

Most organizations use a progression like:

Stage	Environment	Purpose
1	Development	Initial testing, feature verification
2	Test/QA	Integration testing, QA validation
3	Staging	Pre-production validation
4	Production	Live customer traffic

Sort Order

Environments are ordered by their sort order value:

Environment	Sort Order	Position
Development	0	First
Test	1	Second
Staging	2	Third
Production	3	Last

Sort order is user-configurable and determines display position. Promotion paths are not determined by sort order — they are defined by explicit promotion rules that specify allowed source and target environment pairs.

Promotion Process

Prerequisites

Before promotion can occur:

1. Successful Deployment - Current environment deployment succeeded (if the promotion rule requires it)
2. Soak Time Met - The version has been running in the source environment for the configured minimum soak time (if set on the promotion rule)
3. Promotion Rule Exists - A promotion lifecycle rule must be configured for this source → target environment pair
4. Approval Obtained - If the rule requires approval, approval from the designated role must be granted

Performing a Promotion

1. Navigate to the solution detail page
2. Find the source environment in the state table
3. Click the Promote button
4. Review the promotion summary
5. Click Promote (or Request Promotion if approval is required)

┌─────────────────────────────────────────────────────────┐
│  Promote Solution                                       │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Solution:     customer-portal                          │
│  Version:      1.3.0                                    │
│                                                         │
│  From:         Development                              │
│  To:           Staging                                  │
│                                                         │
│  Target Count: 4 machines                               │
│                                                         │
│  ┌───────────────────────────────────────────────────┐  │
│  │ ⚠ This will deploy v1.3.0 to all Staging targets │  │
│  └───────────────────────────────────────────────────┘  │
│                                                         │
│                    [Cancel]  [Promote / Request Promotion] │
└─────────────────────────────────────────────────────────┘

Promotion Visualization

The solution dashboard shows promotion state:

┌─────────────────────────────────────────────────────────┐
│  customer-portal - Promotion Status                     │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌────────────┐    ┌────────────┐    ┌────────────┐    │
│  │ Development│    │  Staging   │    │ Production │    │
│  │   v1.4.0   │ -> │   v1.3.0   │ -> │   v1.2.0   │    │
│  │  ✓ Ready   │    │  ✓ Ready   │    │  ✓ Stable  │    │
│  └────────────┘    └────────────┘    └────────────┘    │
│       │                  │                              │
│  [Promote to      [Promote to                          │
│   Staging]         Production]                          │
│                                                         │
└─────────────────────────────────────────────────────────┘

Promotion Rules

Organizations can configure rules for promotions:

Soak Time

Minimum time a version must run before promotion:

Environment	Soak Time	Purpose
Development	None	Rapid iteration
Test	1 hour	Basic validation
Staging	24 hours	Extended testing
Production	N/A	Final destination

Approval Requirements

Some environments require approval:

┌─────────────────────────────────────────────────────────┐
│  Promotion Requires Approval                            │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  To promote to Production, approval is required from:   │
│                                                         │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Release Manager                                  │  │
│  └───────────────────────────────────────────────────┘  │
│                                                         │
│                          [Request Approval]             │
└─────────────────────────────────────────────────────────┘

Each promotion rule can require approval from one designated role. When approval is required, a member of that role must approve before the promotion proceeds.

Success Criteria

Promotion may require:

• The source deployment completed successfully
• The minimum soak time has elapsed (if the rule sets one)
• Required approvals obtained (if the rule requires approval)

Rollback

If a promotion causes issues, you can rollback:

Rollback Process

1. Navigate to environment state
2. Click Rollback
3. Select the target version
4. Confirm rollback

┌─────────────────────────────────────────────────────────┐
│  Rollback Solution                                      │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Solution:     customer-portal                          │
│  Environment:  Production                               │
│  Current:      v1.3.0 (has issues)                      │
│                                                         │
│  Rollback to:                                           │
│  ┌───────────────────────────────────────────────────┐  │
│  │ ● v1.2.0 - Deployed 5 days ago (recommended)     │  │
│  │ ○ v1.1.0 - Deployed 2 weeks ago                  │  │
│  │ ○ v1.0.0 - Deployed 1 month ago                  │  │
│  └───────────────────────────────────────────────────┘  │
│                                                         │
│                        [Cancel]  [Confirm Rollback]     │
└─────────────────────────────────────────────────────────┘

Rollback Considerations

When rolling back:

• Rollback runs the solution at the selected version
• Variable values are resolved for the current environment
• Database migrations may need manual rollback
• Cache invalidation may be required

Caution

Rollbacks execute the old version’s sequences. Ensure your deployments are designed to be reversible.

Skipping Environments Is Not Supported

A promotion requires a direct source → target promotion rule. There is no path that routes a promotion across a non-direct (skipped) hop — a promotion without a matching direct rule is always denied. The rule’s allow_skip flag does not enable skipping; it only changes which blocking error message is shown when a skip is attempted. To move a build to a later environment, promote it through each configured stage in turn.

Pending promotions

There is no dedicated promotion-history view. The promotions API exposes the current lifecycle only — GET /promotions/pending, GET /promotions/{id}, and the approve/reject actions; there is no list-all-past-promotions endpoint. Use the environment state table (above) and the audit log for historical context.

Best Practices

1. Deploy to Development First

Always start in the lowest environment:

2. Observe Before Promoting

Watch each environment before promotion:

Environment	Observation Period
Development	Hours
Test	1 day
Staging	1-3 days
Production	N/A

3. Keep Production Stable

Promote to production only when confident:

• Tested in staging
• Approval obtained (if required)
• Rollback plan ready
• Team available to monitor

4. Document Promotions

Record why promotions occurred:

Promotion: v1.3.0 to Production
Reason: Scheduled release for Sprint 42
Testing: 3 days in staging, QA approved
Rollback: v1.2.0 verified working

5. Use Deployment Windows

Schedule production promotions during low-traffic periods:

• Early morning or late evening
• Weekdays (support available)
• Not during holidays or events

Troubleshooting

Cannot Promote: Soak Time Not Met

Cause: Version hasn’t been in current environment long enough

Solution: Wait for the soak time to elapse (there is no override).

Cannot Promote: Approval Required

Cause: Target environment requires approval

Solution: Request approval from required approvers

Promotion Failed Mid-Way

Cause: Deployment to target environment failed

Solution: Check deployment logs, fix issues, retry

Version Mismatch After Promotion

Cause: Promotion may have been interrupted

Solution: Check environment state, deploy correct version if needed

Next Steps

• Creating Solutions - Create new solutions
• Variables - Configure environment-specific values
• Versioning - Manage solution versions
• Overview - Return to solutions overview