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

A promotion is permitted by a promotion rule naming its exact source and target environments; sort order only decides how the environments are listed and which one the UI suggests next. A rule set matching the sort order below is the common shape:

Environment	Sort Order	Rule 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 Assigned

The target environment needs at least one assigned target. Target health is not consulted — an environment whose only target is offline still promotes, and the commands queue for the agent.

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. Ask an admin to shorten the rule.          │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

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 is four-eyes, not a quorum: a promotion rule carries a single approval_role_id, and one approver who holds that role — and who is not the person who requested the promotion — moves the request forward. There is no per-approver tally and no way to require two approvals.

┌─────────────────────────────────────────────────────────────┐
│  Approval Required                                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Promoting to Production requires approval.                 │
│                                                             │
│  Approver role: Release Manager                             │
│  Requested by:  a.dev (may not self-approve)                │
│                                                             │
│                              [Request Approval]             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Approval Flow

Skipping environments is not supported

A promotion needs a rule matching the exact source → target pair. Without one the promotion is refused, and the rule’s allow_skip flag does not change that — it only selects which blocking message is returned (No direct promotion path exists; skipping is not allowed rather than No promotion rule exists for this source/target environment pair).

To move a build to a later environment, promote it through each configured stage in turn. For an emergency that cannot wait, add a direct rule between the two environments rather than planning around a skip.

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 the soak time to elapse. There is no override: the gate is a direct comparison, so the only other route is an administrator shortening or removing the promotion rule’s minimum_soak_time_minutes.

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