Environments

Environments are usually isolated instantiations of the same project representing a stage in its development lifecycle, e.g. from “development” through to “production”.

Runners and environments #

Each environment will have exactly one runner linked to it at any time as a result of the runner rules. To create an environment you must have a runner which matches it.

The runner creates the link to the Terraform/OpenTofu state for that environment through its state storage configuration.

The environment remains linked to a runner even when the runner rules change until the refresh_runner API is called on the environment. This is because changing a runner may lead to dropping access to the previously used Terraform/OpenTofu state and thus a potentially undesired destruction of resources.

Refresh the runner for an environment #

An environment remains linked to a runner even when the runner rules change. Execute the refresh_runner command on the environment to re-assign a runner based on the current runner rules.

Use the dry_run flag to test the result of the command without applying any change.

If a runner could be identified for the environment, the command will return that runner’s id.

If no runner could be identified, the command will return an error.