Actions

An Action is the fundamental building block of automation in Mantis. It represents a single, versioned executable unit that performs a specific task on deployment targets.

What is an Action?

Actions define what gets executed on your targets. They can be as simple as a single command or as complex as a multi-step script. Each action is:

• Versioned - Supports semantic versioning for controlled updates
• Reusable - Can be referenced by multiple sequences and solutions
• Configurable - Accepts arguments and environment variables
• Auditable - All executions are logged with full history

Action Structure

Every action consists of:

Component	Description
Name	Descriptive identifier (e.g., “Deploy Docker Container”)
Version	Semantic version number (e.g., “1.0.0”, “2.1.3”)
Payload	The actual execution content (command, script, or restart)
Executor	How the payload runs (shell type or direct execution)

Payload Types

Actions support three payload types:

Command Payload

Executes a binary or executable with arguments. Best for single, well-defined operations.

Field	Description	Example
Binary	Path to executable	/usr/bin/docker
Arguments	Command-line arguments	["pull", "nginx:latest"]
Environment Variables	Key-value pairs	{"DOCKER_HOST": "unix:///var/run/docker.sock"}
Working Directory	Execution directory	/opt/app

Example Use Cases:

• Run a Docker command
• Execute a system utility
• Call an API endpoint with curl

Script Payload

Executes a script file from a configured storage backend. Best for complex, multi-step operations.

Field	Description	Example
Storage	Storage backend reference	Git repository, local path, or S3 bucket
File Name	Script filename	deploy.sh
Arguments	Script arguments	["--environment", "production"]
Environment Variables	Key-value pairs	{"LOG_LEVEL": "info"}
Relative Path	Path within storage	scripts/deployment/

Example Use Cases:

• Complex deployment workflows
• Configuration management
• Database migrations

Restart Payload

Triggers a system restart on the target. Used for scenarios requiring a full system reboot.

Caution

Restart payloads will reboot the target machine. Ensure your deployment sequence accounts for the reconnection time.

Executors

The executor determines how commands and scripts are run:

Executor	Shell	Platform	Security Level
Default	None (direct)	Cross-platform	Highest - no shell interpretation
sh	POSIX shell	Linux/macOS (WSL on Windows)	Good - metacharacter validation
bash	Bash shell	Linux/macOS (WSL/Git Bash on Windows)	Good - metacharacter validation
pwsh	PowerShell Core	Cross-platform	Good - metacharacter validation
zsh	Z shell (-f)	Linux/macOS (WSL/MSYS2 on Windows)	Good - metacharacter validation

Tip

Use the Default executor when possible. It passes arguments directly to the process without shell interpretation, preventing injection attacks.

Shell Security

When using shell executors (sh, bash, pwsh, zsh), Mantis validates inputs for dangerous metacharacters:

• Rejected: ;, |, &, $, `, (, ), {, }, <, >, \n, \r, ', ", \, !, *, ?, [, ], #, ~
• Arguments are quoted to prevent expansion
• Path traversal attempts (../) are blocked

Versioning

Actions use semantic versioning (MAJOR.MINOR.PATCH):

• MAJOR - Breaking changes to behavior or interface
• MINOR - New features, backward compatible
• PATCH - Bug fixes, backward compatible

Version Benefits

1. Rollback Support - Deploy a previous version if issues arise
2. Controlled Updates - Test new versions before promoting
3. Dependency Pinning - Sequences can specify version requirements (^1.0.0, >=2.0.0)

Creating New Versions

Each version is immutable once created. To modify an action:

1. Navigate to the action detail page
2. Click Add Version
3. Specify the new version number
4. Configure the payload
5. Save the version

Best Practices

Naming Conventions

Use descriptive, action-oriented names:

Good	Bad
deploy-nginx-container	script1
backup-database	db_stuff
restart-web-services	fix

Idempotency

Design actions to be safely re-runnable:

• Check if work is already done before doing it
• Use docker pull instead of assuming image exists
• Handle “already exists” errors gracefully

Error Handling

• Set appropriate timeouts for long-running operations
• Use meaningful exit codes (0 = success, non-zero = failure)
• Log enough context for debugging

Next Steps

• Creating Actions - Step-by-step guide to create your first action
• Command Payloads - More on command configuration
• Script Payloads - Configure script-based actions
• Versioning - Version management strategies