# Add a lifecycle phase

Source: https://www.jawsdeploy.net/rest-api/lifecycle-phase-add | Section: Lifecycles

Append a phase to a lifecycle.

`POST /api/lifecycle/phase`

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

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `lifecycleId` | body | string | yes | ID of the lifecycle. |
| `name` | body | string | yes | Phase name. |
| `description` | body | string | no | Optional description. |
| `sortOrder` | body | integer | 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 | integer | 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 }`. |
| `phaseId` | body | string | no | Ignored when adding - the new phase always gets a new ID, returned in the response. |

### 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

| Status | Meaning |
|---|---|
| 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. |

Example request:

```
POST /api/lifecycle/phase

{ "lifecycleId": "lc_1", "name": "Staging", "environments": [ { "environmentId": "env_b", "howToTrigger": "Manual" } ] }
```

Example response:

```
{ "phaseId": "ph_2" }
```