// Lifecycles

Add a lifecycle phase

Append a phase to a lifecycle.

POST/api/lifecycle/phase

Description

Adds a phase to a lifecycle. The phase is appended at the end unless sortOrder is provided.

Each phase environment has a howToTrigger mode: Manual (the default) or Automatic.

Parameters

NameInTypeRequiredDescription
lifecycleId body string yes ID of the lifecycle.
name body string yes Phase name.
description body string no Optional description.
sortOrder body number no Position. Defaults to end.
progressRequirement body string no How many of the phase environments must complete before the release can move on. One of AllMustComplete (the default), MinimumNumberToComplete, or OptionalPhase. See below for what each one means.
progressRequirementCount body number no How many environments must complete. Only used when progressRequirement is MinimumNumberToComplete, and discarded otherwise.
progressRequirementErrorMode body string no How a finished deployment is judged when counting phase progress. One of NoErrorsNoWarnings (the default), NoErrorsAllowWarnings, or Always. See below for what each one means.
environments body array<object> no List of { environmentId, howToTrigger }.

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. 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. 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 is created with NoErrorsNoWarnings.

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 lifecycleId, validation failure, or referenced environment not in the workspace.
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.