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. Open the Deployment group in the top navigation, then the Actions pill
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 7 (pwsh), else Windows PowerShell 5.1
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 the Binary field (and in a script payload’s file path), because those name what actually runs. The characters not allowed there are: ; | & $ ` ( ) { } < > ' " \ ! * ? [ ] # ~ as well as newline and carriage return.

Arguments are not character-checked. They are single-quoted before the shell line is built, which makes a metacharacter inert rather than rejecting it — so a deployment variable may legitimately contain $, &, a quote or the #{ ... } braces of a template. The consequence is the same either way: an argument cannot chain commands (&&, ;), pipe (|), expand shell variables ($VAR) or glob, because the shell sees it as one literal string. 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 name, content, arguments, working directory and declared environment variable values are templates, and resolved non-sensitive variables are also passed to the script as MANTIS_* environment variables (see Variables and Runtime below).

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 as #{variable_name} (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. #{...} templates in command arguments, the working directory, and a script’s file name and content. A template can apply filters and conditions and read the Mantis.* system variables; see Variables.
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.

Inside a script, #{version} and $MANTIS_VERSION reach the same value. A sensitive variable is not in the MANTIS_* set; see Sensitive Variables for how a script receives one.

Action Editor Interface

┌─────────────────────────────────────────────────────────┐
│  Create New Action                                      │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Name:        [deploy-webapp                    ]       │
│  Version:     [1.0.0                            ]       │
│                                                         │
│  ─────────────────────────────────────────────────────  │
│                                                         │
│  Payload Type:  [ Command                     ▼ ]      │
│  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 from its MANTIS_* environment variable:

#!/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