Sequence Versioning

Sequences use semantic versioning to track changes and ensure reproducible deployments.

Why Version Sequences?

Reproducibility

Sequence v1.0.0 always executes the same steps in the same order:

Change Tracking

Version history shows how sequences evolved:

v1.0.0 - Initial release (3 steps)
v1.1.0 - Added health check step
v1.2.0 - Updated deploy-files to ^2.0.0
v2.0.0 - Removed deprecated backup step

Rollback Capability

If a new sequence version causes issues, revert to the previous:

Semantic Versioning for Sequences

Version Components

MAJOR.MINOR.PATCH
  │     │     │
  │     │     └── Configuration tweaks
  │     └──────── Added/modified steps
  └────────────── Breaking changes

When to Bump Versions

Change	Version Bump	Example
Fix typo in step config	Patch	1.0.0 → 1.0.1
Update action version requirement	Minor	1.0.0 → 1.1.0
Add a new step	Minor	1.0.0 → 1.1.0
Remove a step	Major	1.0.0 → 2.0.0
Reorder steps	Major	1.0.0 → 2.0.0
Change step’s action	Major	1.0.0 → 2.0.0

Creating New Versions

In the UI

1. Navigate to the sequence detail page
2. Click Add Version
3. Enter the new version number
4. Make your changes
5. Click Create Version

┌─────────────────────────────────────────────────────────┐
│  Add New Version                                        │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Current Version: 1.2.0                                 │
│  New Version:     [1.3.0                        ]       │
│                                                         │
│  Changes:                                               │
│  ┌───────────────────────────────────────────────────┐  │
│  │ - Updated health-check version to ^1.2.0          │  │
│  │ - Added smoke-test step at position 5             │  │
│  └───────────────────────────────────────────────────┘  │
│                                                         │
│                           [Cancel]  [Create]            │
└─────────────────────────────────────────────────────────┘

Version Immutability

Note

Published sequence versions are immutable. You cannot modify them after creation.

What Cannot Change

• Step list
• Step order
• Action references
• Version requirements

What Can Change

• The parent sequence’s name (via the sequence edit page — this does not affect any version)
• Creating new versions (which captures a new immutable snapshot)
• Deleting a version (the API allows deleting any version except the last remaining one; to remove the final version, delete the sequence)

Version Requirements in Solutions

Solutions reference sequences with version requirements:

Requirement	Resolved (once, at solution-version creation) to
^1.0.0	Highest matching 1.x.x version
~1.2.0	Highest matching 1.2.x version
=1.2.3	Exactly 1.2.3
>=1.0.0	Highest version >= 1.0.0

Once a solution version is created, its sequence-version pins are frozen and do not follow newer releases (see Action Version Resolution below for the same one-shot behavior).

Recommended Strategy

For production solutions:

=1.2.3  # Exact version for stability

For development:

^1.0.0  # Get updates automatically

Action Version Resolution

When you create a sequence version, Mantis resolves the action version requirement once and stores the specific action version at that moment:

This means a sequence version always executes the exact same action version it was created with — it does not automatically pick up newer action versions released later.

Adopting a Newer Action Version

To use a newer action version in your sequences:

1. Create a new sequence version with the updated version requirement
2. The new sequence version resolves the action version at creation time

Version History View

The sequence detail page shows all versions:

┌─────────────────────────────────────────────────────────┐
│  Sequence: deploy-web-app                               │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Versions:                                              │
│                                                         │
│  ┌─────────┬───────────────┬──────────┐                 │
│  │ Version │ Created       │ Actions  │                 │
│  ├─────────┼───────────────┼──────────┤                 │
│  │ 2.0.0   │ 2 days ago    │ 4        │                 │
│  │ 1.3.0   │ 1 week ago    │ 5        │                 │
│  │ 1.2.0   │ 2 weeks ago   │ 4        │                 │
│  │ 1.1.0   │ 1 month ago   │ 4        │                 │
│  │ 1.0.0   │ 2 months ago  │ 3        │                 │
│  └─────────┴───────────────┴──────────┘                 │
│                                                         │
│  [+ Add Version]                                        │
│                                                         │
└─────────────────────────────────────────────────────────┘

Best Practices

1. Version Meaningfully

Don’t create versions for trivial changes:

Good: v1.0.0 → v1.1.0 (added step)
Bad:  v1.0.0 → v1.0.1 → v1.0.2 → v1.0.3 (typo fixes)

2. Document Changes

Include clear change notes:

Version 1.3.0:
- Added smoke-test step after deployment
- Updated deploy-files to use v2.x for parallel support

3. Test Before Promoting

Test new versions in lower environments:

4. Retire Old Versions Gracefully

When moving solutions off an old sequence version:

1. Notify solution maintainers
2. Update each solution to require a newer version
3. Confirm nothing still pins the old version before stopping its use

5. Avoid Major Version Churn

Design sequences for forward compatibility:

Instead of:
v1.0.0 → v2.0.0 → v3.0.0 (frequent breaking changes)

Prefer:
v1.0.0 → v1.1.0 → v1.2.0 (incremental improvements)

Troubleshooting

Version Not Showing in Dropdown

Cause: The version requirement may not match any existing version

Solution: Check the available versions and the requirement; create a new version if needed

Wrong Version Selected

Cause: Version requirement matches multiple versions

Solution: Use more specific requirement (e.g., =1.2.3 instead of ^1.0.0)

Cannot Modify Sequence

Cause: Published versions are immutable

Solution: Create a new version with desired changes

Next Steps

• Creating Sequences - Create new sequences
• Ordering Actions - Manage step order
• Overview - Return to sequences overview