Environments

Maintain separate execution environments with different configurations for your tasks, runbooks, and more.

Overview

Environments allow your team to maintain separate execution spaces with their own tasks, runbooks, schedules, resources, and config variables. Environments are isolated from one another, meaning a task in a certain environment will only have access to the resources and config variables in that environment.

Depending on the execution environment, the List Users task will resolve different resource configurations.

Environments are powerful for the following use cases (and more):

Test changes in a dev or staging environment before releasing to your team.
Run the same task against different configs, resources and agents.
Create a safe isolated playground to experiment with new tasks and/or runbooks.

Managing environments

You can create, modify, and archive environments via the Environments page. All teams start with a single, default "Production" environment.

When you create an environment, you can choose a name, slug, and template from which to create the environment. The slug identifies the environment when working with the CLI and other APIs (e.g. listing tasks, deploying tasks, and updating configs/resources).

To clone your existing tasks, runbooks, configs, resources and schedules when creating a new environment, select your existing Production environment as the template. (Note that schedules in newly created environments will be disabled by default.)

You can switch environments by selecting any active environment in the team dropdown in the top left. Once you switch environments, all tasks, runbooks, configs, resources, and schedules will reflect their states in that specific environment.

Environments can be archived, but they cannot be deleted. If you want to re-use the slug of an archived environment, you can change the slug of the environment to something like environment_slug_archived to free up the slug.

Accessing environment information from tasks

Certain environment-specific information is available via environment variables when your task runs, as well as via JS templates.

Environment variables (with example values):

AIRPLANE_ENV_ID: "env20220125z7pz51c"
AIRPLANE_ENV_SLUG: "prod"

These environment variables can be accessed within your task:

javascript
Copied
1
export default async function (params) {
2
  console.log(`Running in ${process.env.AIRPLANE_ENV_SLUG}`);
3
}

The following variables are available in JS templates (example values shown):

env.id: "env20220125z7pz51c"
env.slug: "prod"
env.name: "Production"
env.default: true

These variables can be accessed in any field that accepts JS templates. For example, consider the following configuration for a REST task:

Depending on the execution environment, the env key in the JSON request body will have different values.

For a full list of available variables, see the Task globals and Runbook globals pages.

Restricting self-hosted agents to an environment

When using self-hosted agents, you can restrict an agent to execute runs from a specific environment by passing the environment slug during installation. For example, you can pass envSlug in the Helm chart or env_slug in the Terraform module.

Alternatively, JS template interpolation can be used when setting run constraints. This makes it possible to ensure tasks in certain environments run only on certain agents with the certain labels.