Start an environment release
Creates and starts a release on a flag in an environment, either from inline configuration or from an environment release plan. A release has one or more phases. Each phase is an audience, targeted by one flag rule, and has its own steps: the schedule of allocations at which that rule serves the target variation. After all of a phase’s steps complete, the phase serves the target variation to 100% of its contexts.
Inline configuration. Each entry in phases must specify exactly
one targeting mode:
- Existing rule: set
ruleId. The rule must be enabled. Only a single-phase release can use an existing rule. - New rule: set
clauses, with an optionaldescription. New rules are appended to the end of the flag’s rule list. To insert them before an existing rule instead, set the top-levelbeforeRuleId, which applies to every phase.
Every phase’s rule, including an existing rule passed by ruleId,
must include
{"contextKind": "<randomizationUnit>", "attribute": "kind", "op": "in", "values": ["<randomizationUnit>"]},
not negated and with no other values, so the release only reaches
contexts of the randomizationUnit kind, or multi-contexts
containing the randomizationUnit kind. An existing rule needs the
clause even if its other clauses only match that context kind. A
phase without it returns 400.
For multiple phases, set phases with at least two entries. Each phase
creates a rule. The first rule is enabled and starts immediately.
Subsequent rules stay disabled until the release advances to them:
automatically when advancementMode is automatic, or by an explicit
advance when it is manual. advancementMode is required for a
multi-phase release.
Releases on the flag’s default rule are not supported. A phase that omits both targeting modes is rejected.
The flag must be on in the environment, or the request returns
409. The release only reaches contexts that match a phase’s rule.
Other contexts keep getting the flag’s default rule, which may
already serve the target variation.
The release type is inferred from metrics: an omitted or empty array
creates a progressive release; one or more metrics creates a guarded
release. Metrics must be listed individually; metric groups are not
accepted.
Every start runs release health checks, described in
ReleaseHealthCheckKind. A flag that hasn’t recently been
evaluated for contexts of the randomizationUnit kind fails
flag_evaluations_with_context, and one with no recent evaluations
at all also fails flag_evaluations_any. Guarded releases also
check that each metric receives events. A failing
check returns 400 with code health_checks_failed. To start the
release anyway, list the failing kinds in bypassHealthChecks.
From a release plan. Set releasePlanKey to start from a plan in
this environment instead of configuring the release inline; a request
that also sets fields the plan supplies is rejected. The plan’s current
version runs as stored, with metric groups expanded into their members.
Health checks run against the plan’s randomization unit and metrics.
Returns 400 if the plan is missing or incomplete, and 422 until
environment release plans are available for the account.
Requires the updateRules action on the flag in this environment, plus
updateFallthrough when cleanupBehavior is
remove_rules_and_update_default_rule. A release started from a plan
requires both. The start is recorded in the flag’s audit log as a
targeting change that carries comment.
In an environment that requires approvals, this endpoint fails with
405. Tokens granted the bypassRequiredApproval action can still
call it to start the release directly.
This operation is not idempotent. Retrying a request that already
started a release returns 409 with code release_already_active.
The earlier request may have succeeded; call listEnvironmentReleases
to confirm the running release is yours.
Authorizations
Headers
Version of the endpoint.
beta Body
ID of the variation the release starts from. The release gradually moves traffic from it to the target variation, and moves traffic back to it if the release reverts.
ID of the variation being released. The release gradually moves traffic to it from the original variation, and moves traffic back to the original variation if the release reverts.
Insert the newly created rule or phase rules before this rule. If omitted, append them to the end of the rule list.
Key of an environment release plan in this environment. The plan
supplies randomizationUnit, phases, metrics, advancementMode,
and cleanupBehavior, so omit them. Omit this field to configure
the release inline.
1Key of an existing, non-archived context kind in the project that
the release randomizes on, such as user. Each phase's rule must
include the clause {"contextKind": "<unit>", "attribute": "kind", "op": "in", "values": ["<unit>"]}. Required unless releasePlanKey
is set.
1How the release moves between phases. Required when phases has
more than one entry; a single-phase release ignores it and may omit it.
Omit when releasePlanKey is set.
manual, automatic Ordered phases of the release. Required unless releasePlanKey is set.
1One phase of a release. Each phase creates a flag rule unless it sets ruleId.
- Option 1
- Option 2
Metrics shared by every phase. Omit or pass an empty array for a
progressive release. Metric groups cannot be listed inline; a
release plan's metric groups expand into their member metrics at
start. Omit when releasePlanKey is set.
Health check kinds that do not block this request. LaunchDarkly still runs and enforces every health check kind not listed here.
A release health check:
flag_evaluations_any: The flag has recently been evaluated.flag_evaluations_with_context: The flag has recently been evaluated for contexts of therandomizationUnitkind.metric_events_any: Guarded releases only. The metric has received events.metric_events_with_context: Guarded releases only. The metric has received events for contexts of therandomizationUnitkind.
flag_evaluations_any, flag_evaluations_with_context, metric_events_any, metric_events_with_context What happens to the release rules after the release completes. Omit
for leave_rules_in_place. Omit when releasePlanKey is set.
remove_rules_and_update_default_rule, leave_rules_in_place Optional comment written to the flag's audit-log entry.
Response
Environment release created and started.
A flag release in one environment, made up of one or more ordered
phases. The top-level status is derived from the phases: it reflects
the active phase, reports waiting between successfully completed
phases, and reports the terminal outcome of the release.
High-level status of an environment release or release phase.
pending: The release or phase has not started.in_progress: The release or phase is progressing without requiring action.waiting: The release is partially rolled out, but is paused and waiting for action from the user.completed: The release or phase reached the target variation.reverted: The release or phase returned to the original variation.
pending, in_progress, waiting, completed, reverted ID of the variation the release started from.
The value of the variation. This may be a string, boolean, number, JSON object, or array.
ID of the variation being released.
The value of the variation. This may be a string, boolean, number, JSON object, or array.
Key of the context kind the release randomizes on.
What happens to the release rules when the final phase completes, either on its own or because a stop rolls it forward while it's running:
remove_rules_and_update_default_rule: The release rules are removed and the default rule serves the target variation.leave_rules_in_place: The release rules stay and serve the target variation.
In every other case, including a revert, it has no effect: release
rules left on the flag keep serving the variation the release ended
on, ahead of rules added later without beforeRuleId.
remove_rules_and_update_default_rule, leave_rules_in_place Whether the release uses metric monitoring.
progressive, guarded 1Zero-based index of the active phase. Null before the first phase, between phases, and after the release reaches a terminal status.
x >= 0Whether a multi-phase release advances to the next phase automatically once the current phase's steps complete, or waits for an explicit advance. Has no effect on a single-phase release.
manual, automatic Creation time in Unix milliseconds.
Additional detail for a waiting, completed, or reverted status.
The field may be absent for a waiting status when there is no
specific reason.
waiting_phase_ended appears only on the release, never on a phase.
It means a phase of a multi-phase release with advancementMode
manual ended and the release must be advanced to the next phase.
reverted_discarded means the phase ended without a regression or a
member rolling it back. A running phase is discarded when the flag
changes underneath it, for example when the flag is turned off,
archived, or deleted. A pending phase is discarded when the release
ends before it starts, either because an earlier phase reverted or
because the release was stopped with a resolution that removes pending
phases. A release reports reverted_discarded only when the last phase
that started was discarded.
waiting_regression_detected, waiting_phase_ended, completed_automatic, completed_manual, reverted_regression_detected, reverted_manual, reverted_discarded, reverted_insufficient_data Start of the first phase in Unix milliseconds. Absent until a phase has started.
End of the last started phase in Unix milliseconds. Present only after the release reaches a terminal status of completed or reverted.