Creating Environments

Set up environments to organize your deployment pipeline.

What is an Environment?

An environment represents a stage in your deployment pipeline:

Each environment contains:

• A set of assigned targets
• Environment-specific variable values
• A position in the promotion order

Creating an Environment

Step 1: Navigate to Environments

1. Open Lens in your browser
2. Click Environments in the sidebar
3. Click New Environment

Step 2: Enter Basic Details

┌─────────────────────────────────────────────────────────────┐
│  Create Environment                                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Name:         [Production                          ]       │
│  Description:  [Live customer-facing environment    ]       │
│                                                             │
│  Sort Order:   [30                                  ]       │
│                                                             │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ Sort order determines promotion sequence.            │  │
│  │ Lower values are earlier in the pipeline.            │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                             │
│                           [Cancel]  [Create]                │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Step 3: Configure Sort Order

Sort order determines the promotion sequence:

Environment	Sort Order	Position
Development	0	First
Test	10	Second
Staging	20	Third
Production	30	Last

Tip

Use increments of 10 to leave room for inserting environments later.

Environment Properties

Property	Required	Description
Name	Yes	Display name (the slug derived from it must be unique within scope)
Slug	No	URL-safe key; derived from the name if omitted; must be unique within scope
Description	No	Human-readable description
Sort Order	No	Position in promotion pipeline. Defaults to 0 if omitted.

Naming Conventions

Good	Avoid
Production	prod, prd
Staging	stage, stg
Development	dev
QA-Testing	qa_test_env

Standard Environment Setup

Typical Pipeline

┌─────────────────────────────────────────────────────────────┐
│  Environment Pipeline                                       │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌────────────┐    ┌────────────┐    ┌────────────┐        │
│  │Development │ -> │  Staging   │ -> │ Production │        │
│  │ Order: 0   │    │ Order: 10  │    │ Order: 20  │        │
│  │ 2 targets  │    │ 4 targets  │    │ 12 targets │        │
│  └────────────┘    └────────────┘    └────────────┘        │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Extended Pipeline

For larger organizations:

Environment	Sort Order	Purpose
Development	0	Developer testing
Integration	5	CI/CD automated testing
QA	10	Quality assurance testing
UAT	15	User acceptance testing
Staging	20	Pre-production validation
Production	30	Live environment

Creating Your First Environments

Quick Setup Script

Create standard environments via the REST API (environments are managed in Lens or through /api/v1/environments; there is no mantisctl environment subcommand). sort_order controls promotion ordering:

for env in '{"name":"Development","description":"Developer testing environment","sort_order":0}' \
           '{"name":"Staging","description":"Pre-production environment","sort_order":10}' \
           '{"name":"Production","description":"Live customer environment","sort_order":20}'; do
  curl -X POST "$MANTIS_URL/api/v1/environments" \
    -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
    -d "$env"
done

Verification

After creation, verify the environment list:

┌─────────────────────────────────────────────────────────────┐
│  Environments                                               │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────┬───────────┬─────────┬─────────────────┐   │
│  │ Name        │ Order     │ Targets │ Description     │   │
│  ├─────────────┼───────────┼─────────┼─────────────────┤   │
│  │ Development │ 0         │ 0       │ Developer tes...│   │
│  │ Staging     │ 10        │ 0       │ Pre-productio...│   │
│  │ Production  │ 20        │ 0       │ Live customer...│   │
│  └─────────────┴───────────┴─────────┴─────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Editing Environments

Modifiable Properties

Property	Can Edit	Notes
Name	Yes	Must remain unique
Description	Yes	Free-form text
Sort Order	Yes	Affects promotion flow

Edit Process

1. Click environment name
2. Click Edit
3. Modify properties
4. Click Save

Caution

Changing sort order may affect existing promotion workflows.

Deleting Environments

Prerequisites

Before deleting an environment:

• Remove all target assignments
• Ensure no active deployments
• Consider historical data impact

Delete Process

┌─────────────────────────────────────────────────────────────┐
│  Delete Environment                                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Are you sure you want to delete "Test"?                    │
│                                                             │
│  This will:                                                 │
│  • Remove all target assignments                            │
│  • Remove environment from promotion pipeline               │
│  • Preserve historical deployment data                      │
│                                                             │
│  ⚠ This action cannot be undone                            │
│                                                             │
│                           [Cancel]  [Delete]                │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Environment-Specific Configuration

Variables

Each environment has its own variable values:

Solution: customer-portal
Variable: database_host

Development: dev-db.local
Staging:     staging-db.company.com
Production:  prod-db.company.com

See Variables for details.

Best Practices

1. Match Your Release Process

Create environments that match your actual workflow:

Your process:              Environments:
Code → Review →            Development
Build → Test →             Integration, QA
UAT → Deploy →             UAT, Staging
Release                    Production

2. Use Consistent Naming

Establish naming standards:

Standard	Example
Title case	Production, Staging
Hyphenated compounds	Pre-Production, User-Acceptance
Clear purpose	QA-Testing, not Env3

3. Leave Sort Order Gaps

Use gaps for future flexibility:

Current:          Future possible:
Development (0)   Development (0)
Staging (10)      Integration (5)
Production (20)   Staging (10)
                  Canary (15)
                  Production (20)

4. Document Environments

Maintain documentation of each environment:

Environment	Purpose	Access	Contact
Development	Feature testing	Developers	dev-team@
Staging	Pre-prod validation	QA, DevOps	qa-team@
Production	Live traffic	Operations	ops-team@

5. Start Simple

Begin with essential environments:

Minimum viable:
Development → Production

Standard:
Development → Staging → Production

Extended (as needed):
Development → QA → Staging → Production

Troubleshooting

Cannot Create Environment

Cause: A slug derived from (or matching) the requested name already exists in this scope. Uniqueness is enforced on the slug, not the name.

Solution: Use a different name, or supply an explicit unique slug via the API.

Environment Not in Promotion List

Cause: Sort order may be incorrect

Solution: Verify sort order places environment in correct position

Next Steps

• Target Assignment - Assign targets
• Environment State - Track deployed versions
• Promotions - Promote between environments
• Overview - Return to environments overview