Promotions

Move solution versions through your environment pipeline.

What is Promotion?

Promotion deploys a solution version from one environment to the next in your pipeline:

Promotion Flow

Standard Promotion Path

Environment Order

Promotion follows sort order:

Environment	Sort Order	Promotes To
Development	0	Staging
Staging	10	Production
Production	20	(End of pipeline)

Performing a Promotion

From Solution Detail

┌─────────────────────────────────────────────────────────────┐
│  customer-portal - Environment State                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌────────────┬─────────┬────────────────┬───────────────┐ │
│  │Environment │ Version │ Last Deployed  │ Action        │ │
│  ├────────────┼─────────┼────────────────┼───────────────┤ │
│  │Development │ 1.4.0   │ Today          │ [Promote →]   │ │
│  │Staging     │ 1.3.0   │ 3 days ago     │ [Promote →]   │ │
│  │Production  │ 1.3.0   │ 1 week ago     │ -             │ │
│  └────────────┴─────────┴────────────────┴───────────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Promotion Dialog

┌─────────────────────────────────────────────────────────────┐
│  Promote Solution                                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Solution:    customer-portal                               │
│  Version:     1.4.0                                         │
│                                                             │
│  From:        Development                                   │
│  To:          Staging                                       │
│                                                             │
│  Targets in Staging: 4                                      │
│    web-stg-01, web-stg-02, api-stg-01, db-stg-01            │
│                                                             │
│  ─────────────────────────────────────────────────────────  │
│                                                             │
│                           [Cancel]  [Promote]               │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Via REST API

Promotions are created through the REST API. There is no mantisctl subcommand for promotions. Send a POST to /api/v1/promotions with the solution and the source and target environment IDs:

# Promote to the next environment
curl -X POST https://mantis.example.com/api/v1/promotions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "solution_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "source_environment_id": "11111111-1111-1111-1111-111111111111",
    "target_environment_id": "22222222-2222-2222-2222-222222222222"
  }'

# With execution options (rolling waves)
curl -X POST https://mantis.example.com/api/v1/promotions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "solution_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "source_environment_id": "22222222-2222-2222-2222-222222222222",
    "target_environment_id": "33333333-3333-3333-3333-333333333333",
    "target_mode": { "rolling": { "batch_size": 3 } }
  }'

The promotions:create permission is required. Use POST /api/v1/promotions/preview to preview the resulting deployment before creating it.

Promotion Prerequisites

Before promotion can occur:

Version Must Be Deployed

The version must be successfully deployed to the source environment.

Targets Must Be Available

The target environment needs at least one online target.

Soak Time

Soak time is a minimum wait period before promotion:

┌─────────────────────────────────────────────────────────────┐
│  Promote Blocked: Soak Time                                 │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Version 1.4.0 cannot be promoted yet.                      │
│                                                             │
│  Deployed to Development: 2 hours ago                       │
│  Required soak time: 24 hours                               │
│  Time remaining: 22 hours                                   │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ Soak time ensures versions are stable before          │  │
│  │ promotion. Contact admin for emergency override.      │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Typical Soak Times

Environment	Soak Time	Purpose
Development	None	Rapid iteration
Staging	1-4 hours	Basic validation
Production	24-48 hours	Extended testing

Approval Requirements

Some promotions require approval:

┌─────────────────────────────────────────────────────────────┐
│  Approval Required                                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Promoting to Production requires approval.                 │
│                                                             │
│  Required approvers:                                        │
│  ○ Release Manager                                          │
│  ○ QA Lead                                                  │
│                                                             │
│  Current approvals:                                         │
│  (none)                                                     │
│                                                             │
│                              [Request Approval]             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Approval Flow

Skip Promotion

In emergencies, skip environments:

┌─────────────────────────────────────────────────────────────┐
│  Skip Promotion                                             │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ⚠ Warning: You are skipping environments                  │
│                                                             │
│  Solution:    customer-portal                               │
│  Version:     1.4.1 (hotfix)                                │
│                                                             │
│  From:        Development                                   │
│  Skipping:    Staging                                       │
│  To:          Production                                    │
│                                                             │
│  This is an emergency promotion. Are you sure?              │
│                                                             │
│                           [Cancel]  [Skip and Promote]      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Promotion History

Each promotion is recorded as a deployment of type promotion in the deployment history. The deployments list endpoint has no deployment_type filter, so there is no single call that returns only promotion deployments. To inspect promotions:

# Promotions awaiting approval
curl "https://mantis.example.com/api/v1/promotions/pending" \
  -H "Authorization: Bearer $TOKEN"

# A specific promotion by id
curl "https://mantis.example.com/api/v1/promotions/<promotion-id>" \
  -H "Authorization: Bearer $TOKEN"

Rollback

If promotion causes issues:

┌─────────────────────────────────────────────────────────────┐
│  Rollback Solution                                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Solution:    customer-portal                               │
│  Environment: Production                                    │
│  Current:     v1.4.0                                        │
│                                                             │
│  Rollback to:                                               │
│  ● v1.3.0 - Previous version (recommended)                  │
│  ○ v1.2.0 - 2 weeks ago                                     │
│  ○ v1.1.0 - 1 month ago                                     │
│                                                             │
│                           [Cancel]  [Rollback]              │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Rollback Considerations

Factor	Consider
Database changes	May need manual migration rollback
API compatibility	Clients may need updates
Data format	New data may be incompatible
External dependencies	Third-party integrations

Promotion Dashboard

Visual promotion overview:

┌─────────────────────────────────────────────────────────────┐
│  Promotion Dashboard                                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  customer-portal:                                           │
│  ┌────────────┐    ┌────────────┐    ┌────────────┐        │
│  │Development │ -> │  Staging   │ -> │ Production │        │
│  │   v1.4.0   │    │   v1.3.0   │    │   v1.3.0   │        │
│  │  [Ready]   │    │  [Ready]   │    │  [Current] │        │
│  └────────────┘    └────────────┘    └────────────┘        │
│      ↓                  ↓                                   │
│  [Promote →]       [Promote →]                              │
│                                                             │
│  auth-service:                                              │
│  ┌────────────┐    ┌────────────┐    ┌────────────┐        │
│  │Development │ -> │  Staging   │ -> │ Production │        │
│  │   v2.2.0   │    │   v2.1.0   │    │   v2.1.0   │        │
│  │  [Ready]   │    │ [Soak: 4h] │    │  [Current] │        │
│  └────────────┘    └────────────┘    └────────────┘        │
│      ↓                                                      │
│  [Promote →]                                                │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Best Practices

1. Test Before Promoting

Ensure adequate testing at each stage:

Environment	Minimum Testing
Development	Unit tests, smoke tests
Staging	Integration tests, UAT
Production	Monitoring, rollback ready

2. Use Soak Time Wisely

Configure appropriate soak times:

Too short: Issues reach production
Too long: Delays releases

3. Automate Where Possible

Consider automated promotions for:

Development → Staging (after CI passes)
With manual gates for Production

4. Document Promotions

Record promotion context:

Promotion: customer-portal v1.4.0 to Production
Date: 2024-01-20
Approvers: Release Manager, QA Lead
Testing: 3 days in staging
Changes: New checkout flow, payment fixes
Rollback: v1.3.0 verified working

5. Monitor After Promotion

Watch for issues immediately after promotion:

Error rates
Response times
User complaints
System resources

Troubleshooting

Cannot Promote: Soak Time

Cause: Version hasn’t been in environment long enough

Solution: Wait for soak time, or request emergency 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 logs, fix issues, retry promotion

Version Mismatch After Promotion

Cause: Interrupted promotion or partial failure

Solution: Verify state, redeploy if needed

Next Steps

Creating Environments - Set up environments
Environment State - Track deployed versions
Target Assignment - Assign targets
Overview - Return to environments overview