// Environments

Update an environment

Rename an environment, restyle it, reorder it, or take it out of service.

PUT/api/environment

Description

Updates an environment in place. Pass only the fields you want to change - name, sortOrder, color and enabled are each left alone when you leave them out.

Renaming an environment does not affect releases that already targeted it.

Parameters

NameInTypeRequiredDescription
environmentId body string yes ID of the environment.
name body string no New name.
sortOrder body integer no New display order.
color body string no New hex color.
enabled body boolean no Set to false to stop the environment receiving deployments, or true to let it again. Omit it and the current value is kept. See below.

Disabling an environment

enabled is the switch for taking an environment out of service without deleting it. It is the field to reach for during a maintenance window, or to freeze production while an incident is open.

The environment keeps everything else. Its machines stay assigned, its lifecycle phases still name it, its variables keep their scoping, and its deployment history is untouched. Re-enable it and it carries on. That is the difference between this and Delete an environment, which is a soft delete the environment does not come back from.

What a disabled environment refuses:

  • A deploy or promote naming it fails up front with 400, and the message lists the environment among those that are not available. The same message covers environments blocked by lifecycle phase progression, so a disabled environment and a not-yet-reachable one read alike - check enabled on List environments to tell them apart.
  • A lifecycle will not promote a release into it automatically.

What it does not do: disabling is not a stop button for work already under way. A deployment that was queued before the environment was disabled is not cancelled. It fails when it is picked up, logging Deployment blocked: the environment is disabled. and finishing as Failed. To stop something already running, use Cancel a deployment as well.

Environments are enabled when created unless Create an environment is told otherwise, and every environment that existed before this flag was added is enabled. The current value is returned by List environments.

Errors

StatusMeaning
400 Invalid environmentId or validation failure.
401 Missing or invalid Basic auth credentials, or the service account lacks the required role.