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 Confirm

┌─────────────────────────────────────────────────────────┐
│  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]  [Confirm 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.

Promotion History

View the complete promotion history:

┌─────────────────────────────────────────────────────────┐
│  Promotion History: customer-portal                     │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌───────────────┬─────────┬────────────┬───────────┐   │
│  │ Date          │ Version │ From → To  │ By        │   │
│  ├───────────────┼─────────┼────────────┼───────────┤   │
│  │ Today 14:30   │ 1.3.0   │ Stg → Prod │ admin     │   │
│  │ Yesterday     │ 1.3.0   │ Dev → Stg  │ alice     │   │
│  │ 3 days ago    │ 1.2.0   │ Stg → Prod │ admin     │   │
│  │ 1 week ago    │ 1.2.0   │ Dev → Stg  │ bob       │   │
│  └───────────────┴─────────┴────────────┴───────────┘   │
│                                                         │
└─────────────────────────────────────────────────────────┘

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