Action Versioning

Mantis uses semantic versioning for actions, ensuring controlled updates and reproducible deployments.

Semantic Versioning

Actions follow Semantic Versioning 2.0:

MAJOR.MINOR.PATCH
  │     │     │
  │     │     └── Bug fixes (backward compatible)
  │     └──────── New features (backward compatible)
  └────────────── Breaking changes

Examples

Version Change	Type	Description
1.0.0 → 1.0.1	Patch	Bug fix in script
1.0.0 → 1.1.0	Minor	Added optional argument
1.0.0 → 2.0.0	Major	Changed required arguments

Why Version Actions?

Reproducibility

Same version = same behavior:

Rollback Capability

If a new version causes issues:

1. Identify the working previous version
2. Update sequence to require that version
3. Deploy with confidence

Audit Trail

Every deployment records exactly which action version was used.

Creating New Versions

When to Create a New Version

Scenario	Version Bump
Fix a bug in the script	Patch (x.x.1)
Add a new optional argument	Minor (x.1.x)
Optimize performance	Patch (x.x.1)
Add new functionality	Minor (x.1.x)
Change existing argument names	Major (1.x.x)
Remove an argument	Major (1.x.x)
Change script behavior	Major (1.x.x)

In the UI

1. Navigate to the action detail page
2. Click Add Version
3. Enter the new version number
4. Modify the payload or arguments
5. Click Create Version

┌─────────────────────────────────────────────────────────┐
│  Action: deploy-webapp                                  │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Versions:                                              │
│  ┌─────────┬──────────┬───────────┬────────────────┐    │
│  │ Version │ Type     │ Executor  │ Created        │    │
│  ├─────────┼──────────┼───────────┼────────────────┤    │
│  │ 2.0.0   │ script   │ bash      │ Today          │    │
│  │ 1.1.0   │ script   │ bash      │ 2 weeks ago    │    │
│  │ 1.0.0   │ command  │           │ 1 month ago    │    │
│  └─────────┴──────────┴───────────┴────────────────┘    │
│                                                         │
│  [+ Add Version]                                        │
│                                                         │
└─────────────────────────────────────────────────────────┘

Version Immutability

Note

Once created, action versions are immutable. You cannot modify a published version.

This ensures:

• Deployments using v1.0.0 always get the same behavior
• Audit trails are accurate
• Rollbacks are reliable

What You Cannot Change

• Payload content
• Argument definitions
• Environment variables
• Executor type

What You Can Change

• Add new versions (versions themselves are fully immutable once created)

Version Requirements in Sequences

When adding actions to sequences, you specify a version requirement:

Requirement	Meaning	Matches
^1.0.0	Compatible with 1.x.x	1.0.0, 1.5.3, 1.9.9
~1.5.0	Patch updates only	1.5.0, 1.5.1, 1.5.99
>=1.2.0	This version or higher	1.2.0, 2.0.0, 3.1.0
=1.2.3	Exact version only	1.2.3
>=1.0.0,<2.0.0	Range	1.0.0 through 1.x.x

Recommended Strategy

Use caret (^) requirements for most cases:

^1.0.0  # Get bug fixes and minor updates automatically

Use exact (=) requirements when:

• Regulatory compliance requires pinning
• Testing a specific version before upgrade
• Working around a known issue

Version Resolution

When a deployment runs, Mantis resolves version requirements:

Resolution Rules

1. Find all versions matching the requirement
2. Select the highest matching version
3. Record the resolved version in deployment logs

Best Practices

1. Start at 1.0.0

Don’t start at 0.x.x for production actions:

Good: 1.0.0 → 1.0.1 → 1.1.0 → 2.0.0
Bad:  0.0.1 → 0.0.2 → 0.1.0 → 1.0.0

3. Test Before Publishing

Test new versions in lower environments:

4. Avoid Major Bumps When Possible

Design actions for forward compatibility:

Instead of:

v1.0.0: Required args: [name]
v2.0.0: Required args: [name, region]  # Breaking!

Do:

v1.0.0: Required args: [name]
v1.1.0: Optional args: [name, region]  # Non-breaking

5. Use Consistent Naming

Action names should be stable across versions:

Good: deploy-webapp (versions 1.0.0, 1.1.0, 2.0.0)
Bad:  deploy-webapp-v1, deploy-webapp-v2, deploy-webapp-new

Viewing Version History

The action detail page shows:

• All versions with version number, payload type, executor, and creation date

Next Steps

• Testing Actions - Validate versions before use
• Creating Sequences - Use version requirements
• Overview - Return to actions overview