// Lifecycles

Update a lifecycle phase

Update name, requirements, or environments of a phase.

PUT/api/lifecycle/phase

Description

Updates a phase. Pass only the fields you want to change. If environments is set, it fully replaces the phase's environments.

Parameters

NameInTypeRequiredDescription
lifecycleId body string yes ID of the lifecycle.
phaseId body string yes ID of the phase.
name body string no New name.
description body string no New description.
sortOrder body number no New position.
progressRequirement body string no New progress requirement: AllMustComplete, MinimumNumberToComplete, or OptionalPhase. Omit to leave the stored requirement unchanged. See below for what each one means.
progressRequirementCount body number no New required count. Only used when progressRequirement is MinimumNumberToComplete, and discarded otherwise.
progressRequirementErrorMode body string no New error mode: NoErrorsNoWarnings, NoErrorsAllowWarnings, or Always. Omit to leave the stored mode unchanged. See below for what each one means.
environments body array<object> no Replacement environment list.

Progress requirements

progressRequirement decides how many of the phase environments must record a counted deployment before the release may move on. One of:

  • AllMustComplete - the default. Every environment in the phase must complete.
  • MinimumNumberToComplete - only progressRequirementCount of them must complete. The rest stay deployable but no longer hold the release back.
  • OptionalPhase - nothing is required. Following phases become eligible immediately, and progressRequirementErrorMode is stored as Unset.

progressRequirementCount is kept only for MinimumNumberToComplete. Under the other two it is discarded and reads back as 0. It is not checked against the number of environments in the phase, and a count of 0 leaves the phase requiring nothing, exactly like OptionalPhase.

Progress error modes

progressRequirementErrorMode decides whether a finished deployment counts towards its phase's progress. A deployment that never reached Completed does not count, whatever the mode.

  • NoErrorsNoWarnings - the default for a newly added phase. The deployment counts only if it finished with no errors and no warnings.
  • NoErrorsAllowWarnings - the deployment counts if it finished with no errors. Warnings are ignored.
  • Always - every completed deployment counts, whatever its error and warning counts.
  • Unset - what the server stores for an optional phase (progressRequirement = OptionalPhase), where the mode has no meaning. It is accepted on input and behaves like Always, but prefer sending one of the three modes above.

Values are matched case insensitively, so always and Always are equivalent, but the name must be spelled out in full - a bare number such as 1 is rejected.

An unrecognised value fails the request with 400 and errorcode = InvalidParameter, and the phase is left exactly as it was. The message names the field, the value you sent, and the full list of valid values, and every bad enum field in the request is reported together.

Omitting the field is not an error: the phase keeps its stored mode.

Setting progressRequirement to OptionalPhase overwrites the stored mode with Unset. If you later move that phase back to a non-optional requirement, send progressRequirementErrorMode in the same request - otherwise the phase keeps Unset and every completed deployment counts.

Errors

StatusMeaning
400 Invalid IDs or validation failure.
401 Missing or invalid Basic auth credentials, or the service account lacks the required role.
400 An enum field was sent with a value that is not one of its defined names, for example progressRequirementErrorMode or environments[].howToTrigger. The message names each rejected field, the value sent, and the valid values for that field. The phase is left unchanged.