Storage Backends

Manage where deployment scripts and artifacts are stored.

What is a Storage Backend?

Storage backends define where Mantis retrieves scripts and artifacts for deployments:

Storage Types

Mantis supports three storage backend types:

Type	Best For	Features
Local	Development, single-server	Simple paths, fast access
Git	Version control, GitOps	Branch tracking, audit trail
S3	Large artifacts, distributed	Multi-region, immutable storage

Choosing a Storage Type

Local Storage

Best when:

• Development and testing
• Single-server deployments
• Air-gapped environments without network storage
• Quick setup without external dependencies

Git Storage

Best when:

• Scripts need version control
• GitOps workflows with PR-based changes
• Audit trails via Git history are required
• Multiple teams collaborate on deployment scripts

S3 Storage

Best when:

• Large deployment artifacts
• Multi-region deployments
• Immutable artifact storage
• Cloud-native infrastructure

Storage List View

┌─────────────────────────────────────────────────────────────┐
│  Storage Backends                                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Search: [____________________________] [+ New Storage]     │
│                                                             │
│  ┌────────────────┬────────┬─────────────────┬───────────┐ │
│  │ Name           │ Type   │ Location        │ Actions   │ │
│  ├────────────────┼────────┼─────────────────┼───────────┤ │
│  │ scripts        │ Local  │ /var/mantis/... │ [View]    │ │
│  │ deploy-repo    │ Git    │ github.com/...  │ [View]    │ │
│  │ artifacts      │ S3     │ s3://bucket/... │ [View]    │ │
│  └────────────────┴────────┴─────────────────┴───────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘

How Scripts Use Storage

Actions reference scripts from storage backends:

Script Reference Example

When creating an action, you specify the storage and filename:

┌─────────────────────────────────────────────────────────────┐
│  Create Action                                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Name:     [deploy-app                    ]                 │
│                                                             │
│  Payload Type: ● Script  ○ Command                          │
│                                                             │
│  Storage:  [scripts               ▼]                        │
│  Filename: [deploy.sh                     ]                 │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ Script will be read from:                             │  │
│  │ /var/mantis/scripts/deploy.sh                         │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Security

Path Traversal Protection

All storage backends implement path traversal protection:

Protection	Description
Null bytes	Rejected
Absolute paths	Rejected
Parent traversal	../ sequences rejected
Canonicalization	Paths verified within storage root
Symlink protection	Files read with O_NOFOLLOW (Unix)

Example: Blocked Access

# These filenames are blocked:
../../../etc/passwd    # Parent traversal
/etc/passwd           # Absolute path
script�.sh         # Null byte injection

Credential Security

Sensitive credentials are encrypted at rest:

Storage Type	Encrypted Fields
Git	SSH private key, SSH passphrase, password
S3	Access key ID, secret access key

Encryption uses AES-256-GCM with AAD binding.

Creating a Storage Backend

Via Lens UI

1. Open the Infrastructure group in the top navigation, then the Storage pill
2. Click New Storage
3. Click the tab for your storage type
4. Configure backend-specific settings
5. Click the per-type create button (e.g. Create Local Storage / Create Git Storage / Create S3 Storage / Create Git Auth)

Via REST API

Storage sources are managed in Lens or through the /api/v1/storage/* endpoints (there is no mantisctl storage subcommand). Each backend has its own endpoint:

Global-admin tokens must include tenant_id. Storage creation calls resolve_tenant_id_for_write, which rejects with 400 tenant_id is required for storage creation when it resolves to None — exactly the case for an admin token that omits it. Add "tenant_id": "<uuid>" to the request body (or use a tenant-scoped token, which supplies it automatically).

# Create local storage
curl -X POST "$MANTIS_URL/api/v1/storage/local" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "scripts", "path": "/var/mantis/scripts"}'

# Create git storage (auth_id references a git auth credential)
curl -X POST "$MANTIS_URL/api/v1/storage/git" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "deploy-repo",
    "path": "/var/mantis/git/deploy-repo",
    "url": "https://github.com/org/scripts.git",
    "reference": "main",
    "auth_id": "<git-auth-id>"
  }'

# Create S3 storage (static credentials)
curl -X POST "$MANTIS_URL/api/v1/storage/s3" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "name": "artifacts",
    "bucket": "my-artifacts-bucket",
    "region": "us-west-2",
    "path_prefix": "deployments/",
    "auth_type": "static",
    "access_key_id": "AKIA...",
    "secret_access_key": "..."
  }'

Storage Configuration

Common Settings

Setting	Required	Description
Name	Yes	Unique identifier
Type	Yes	Local, Git, or S3

Type-Specific Settings

See detailed configuration guides:

• Local Storage
• Git Storage
• S3 Storage

Best Practices

1. Use Git for Version Control

Store deployment scripts in Git for:

• Change history and audit trails
• PR-based review workflows
• Rollback to previous versions

2. Use S3 for Large Artifacts

Use S3 for binary artifacts:

• Application packages
• Container images
• Large data files

3. Use Local for Development

Local storage is ideal for:

• Quick iteration during development
• Testing new scripts
• Air-gapped environments

4. Organize by Purpose

Create separate storages for different purposes:

Storage Backends:
├── scripts-local     # Development scripts
├── scripts-git       # Production scripts (version controlled)
├── artifacts-dev     # Development artifacts
└── artifacts-prod    # Production artifacts

Troubleshooting

Cannot Read Script from Storage

Cause: File doesn’t exist or path is incorrect

Solution:

1. Verify file exists in storage location
2. Check filename spelling (case-sensitive)
3. Ensure storage backend is accessible

Git Storage Not Updating

Cause: Cache or authentication issues

Solution:

1. Check last fetch time (last_fetched on the git storage location)
2. Verify authentication credentials
3. Verify the configured reference still exists and that the credentials are valid; there is no refresh endpoint — the clone re-syncs on the next read

S3 Access Denied

Cause: Insufficient permissions

Solution:

1. Check IAM policy allows required actions
2. Verify bucket policy
3. Confirm credential configuration

Next Steps

• Local Storage - Configure local file storage
• Git Storage - Set up Git repositories
• S3 Storage - Configure S3 buckets
• Authentication - Manage storage credentials