Creating Actions

This guide walks you through creating your first action in Mantis.

Before You Begin

Make sure you have:

• Access to Mantis Lens UI
• Appropriate permissions to create actions
• A clear understanding of what your action should do

Creating an Action

Step 1: Navigate to Actions

1. Open Lens in your browser
2. Click Actions in the sidebar
3. Click the New Action button

Step 2: Basic Information

Enter the action’s identifying information:

Field	Description	Example
Name	Unique identifier for the action	deploy-webapp
Initial Version	Starting version number	1.0.0

Tip

Use descriptive, lowercase names with hyphens. Good names describe what the action does, not how it does it.

Step 3: Select Payload Type

Choose the type of payload for your action:

Type	Use Case
Command	Run a single binary with structured arguments (e.g., docker)
Script	Run a script file stored in a storage backend
Restart	Reboot the target machine

Step 4: Choose Executor

Select how the payload should be executed:

Executor	Platform	Description
Default	Cross-platform	Direct execution without shell (safest)
Sh	Linux/macOS (WSL on Windows)	POSIX shell
Bash	Linux/macOS (WSL/Git Bash on Windows)	Bash shell scripts
Pwsh	Cross-platform	PowerShell Core (7+)
Zsh	Linux/macOS (WSL/MSYS2 on Windows)	Z shell, invoked with -f (no user startup files)

Step 5: Configure Payload

For Command Payloads

A command payload is structured, not a freeform shell line. You provide:

Field	Description	Example
Binary	Path to the executable to run (bin)	docker
Arguments	Ordered list of plain-string arguments	pull, myregistry/myapp:{{version}}
Working Directory	Optional directory to run the binary in	/opt/myapp

Each argument is a single plain string and is added in order. There are no per-argument Default, Required, or Type fields — arguments are passed directly to the binary.

For the Sh, Bash, Pwsh, and Zsh executors, shell metacharacters are rejected in command arguments to prevent command injection. The following characters are not allowed: ; | & $ ` ( ) { } < > ' " \ ! * ? [ ] # ~ as well as newline and carriage return. This means a command payload cannot chain commands (&&, ;), pipe (|), expand shell variables ($VAR), or use globs. If you need that kind of logic, use a Script payload instead.

For example, instead of a single line like docker pull myregistry/myapp:1.0, configure:

• Binary: docker
• Argument 1: pull
• Argument 2: myregistry/myapp:{{version}}

For Script Payloads

A script payload references a file in a storage backend — you do not edit the script body inline in the action editor. You provide:

Field	Description
Storage Backend	The storage backend that holds the script file
File Name	The script file to run
Relative Path	Optional path to the file within the storage backend

The script file’s content is not variable-substituted. At runtime, resolved variables are passed to the script as MANTIS_* environment variables (see Variables and Runtime below). The file name, command arguments, and working directory support {{...}} substitution.

Step 6: Add Arguments (Optional)

Define arguments that are passed to your action’s binary or script:

1. Click Add Argument
2. Enter the argument value

Arguments are plain strings appended in order. You can reference a resolved variable in an argument using {{variable_name}} syntax (for example, myregistry/myapp:{{version}}).

Step 7: Environment Variables (Optional)

Define environment variables for execution:

1. Click Add Environment Variable
2. Enter variable name (e.g., API_KEY)
3. Set value or reference a solution variable

Step 8: Save

Click Save to create your action.

Variables and Runtime

When a deployment runs, Mantis resolves variables and makes them available to your action in two ways:

1. {{...}} substitution in command arguments, the script file name, and the working directory. The matching syntaxes are {{variable}} (mustache) and ${variable} (shell-style).
2. MANTIS_* environment variables injected into the executed process. Each resolved variable is exposed as an uppercased, MANTIS_-prefixed environment variable — for example, the variable version becomes MANTIS_VERSION.

Because a script file’s content is not substituted, the way to read a variable from inside a script is via its MANTIS_* environment variable. For example, a Bash script stored in a backend would read $MANTIS_VERSION rather than {{version}}.

Action Editor Interface

┌─────────────────────────────────────────────────────────┐
│  Create New Action                                      │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Name:        [deploy-webapp                    ]       │
│  Version:     [1.0.0                            ]       │
│                                                         │
│  ─────────────────────────────────────────────────────  │
│                                                         │
│  Payload Type:  ● Command  ○ Script                     │
│  Executor:      [Bash                          ▼]       │
│                                                         │
│  ─────────────────────────────────────────────────────  │
│                                                         │
│  Binary:            [docker                      ]      │
│  Working Directory: [/opt/myapp                  ]      │
│                                                         │
│  Arguments:                                             │
│  ┌───────────────────────────────────────────────────┐  │
│  │ pull                                              │  │
│  │ myregistry/myapp:{{version}}                      │  │
│  └───────────────────────────────────────────────────┘  │
│  [+ Add Argument]                                       │
│                                                         │
│                           [Cancel]  [Save]              │
└─────────────────────────────────────────────────────────┘

Example Actions

Simple Command Action

Name: docker-pull Type: Command Executor: Bash

• Binary: docker
• Argument 1: pull
• Argument 2: {{image}}:{{tag}}

The image and tag variables are substituted into the argument at runtime. Because this is a command payload, the arguments are passed directly to the docker binary — no shell chaining, pipes, or $VAR expansion are permitted.

Service Restart Script

Name: restart-service Type: Script Executor: Bash

The script file (stored in a storage backend, e.g. restart-service.sh) reads the resolved variable via its MANTIS_* environment variable rather than {{...}} substitution, since script content is not substituted:

#!/bin/bash
set -e

SERVICE="$MANTIS_SERVICE_NAME"
echo "Stopping $SERVICE..."
systemctl stop "$SERVICE"

echo "Starting $SERVICE..."
systemctl start "$SERVICE"

echo "Checking status..."
systemctl status "$SERVICE"

The service_name solution variable is injected into the process as MANTIS_SERVICE_NAME.

Windows Service Deployment

Name: deploy-windows-service Type: Script Executor: Pwsh

The script file references resolved variables through MANTIS_* environment variables:

$serviceName = $env:MANTIS_SERVICE_NAME
$sourcePath  = $env:MANTIS_SOURCE_PATH
$installPath = $env:MANTIS_INSTALL_PATH

Write-Host "Stopping $serviceName..."
Stop-Service -Name $serviceName -Force -ErrorAction SilentlyContinue

Write-Host "Copying files..."
Copy-Item -Path "$sourcePath\*" -Destination $installPath -Recurse -Force

Write-Host "Starting $serviceName..."
Start-Service -Name $serviceName

Write-Host "Deployment complete!"

Validation

Before saving, Mantis validates:

Check	Description
Slug uniqueness	No other action in scope resolves to the same slug (derived from name)
Version format	Valid semantic version
Executor	Must be one of: sh, bash, pwsh, zsh, default
Required fields	bin required for Command; storage_id and file_name for Script

After Creation

Once created, your action:

1. Appears in the action list
2. Can be added to sequences
3. Is exercised by deploying a sequence (or solution) that includes it
4. Is ready for versioning

Next Steps

• Command Payloads - More on command execution
• Script Payloads - Complex script patterns
• Versioning - Managing action versions
• Testing Actions - Validating before deployment