Skip to main content
Auto-release is available to customers on select plansAuto-release is only available to customers on certain plans. To learn more, read about our pricing or contact Sales.
This topic explains auto-release in Release Autopilot. Auto-release starts after your code is deployed and makes the deployed change available by progressing a flag through its release plan. Auto-release is opt-in and modular. You do not have to use it to use Release Autopilot, and you can use it independently of other Release Autopilot features.

How auto-release works

Each environment’s auto-release starts from a specific trigger. Auto-release triggers include a flag evaluation, a deploy signal from your CI/CD system, a manual start, or completion of the previous environment’s release. Flag evaluations are the default signal. Auto-releases can be progressive, meaning that if you have multiple environments, the release completing in one environment can trigger the release beginning in another environment. When a release starts, you can track its progress on the Releases page. If you need to, you can pause the release to keep the change from being released to the environments where the release hasn’t started yet. An environment already in progress continues to completion.
The Releases page.

The Releases page.

If an environment’s guarded rollout rolls back, LaunchDarkly pauses unstarted subsequent environments in that flag release. A release expires if it makes no progress for 21 days. After you resume, an environment set to release with a flag evaluation waits for the release trigger to occur again. An environment where you started the release manually will continue until complete. To pause an auto-release:
  1. Navigate to the Releases page and find the release you wish to pause.
  2. Click the release to open the associated flag’s Release tab.
  3. Click Pause auto-release.

Types of auto-releases

When you create an auto-release, there are four different types of release process you can use:

By flag evaluation

Flag evaluation releases start when LaunchDarkly detects an evaluation of the flag in a given environment. If the release is linked to a pull request, the environment waits for the pull request to merge, then starts if the flag was evaluated in that environment in the last 24 hours. Evaluations from before the merge count, so the release may start before your deploy finishes. If the release is not linked to a pull request, it starts at the first evaluation. To start a release only after your deploy completes, use the On deploy trigger. This can cause unexpected behavior if you use flags in both staging and production environments, as a flag evaluation in your staging environment can start the auto-release process and may result in the change being released to production prematurely. We recommend manually starting releases in your production environment unless the release contents are low-impact or ready to be released everywhere.

On deploy releases

On deploy releases start when your CI/CD system tells LaunchDarkly that a deploy to the environment finished. In the API, this trigger type is webhook. Your deployment pipeline sends a deploy signal after each deploy to the environment. To learn how to send a deploy signal, read Send a deploy signal.

Manual releases

Manual releases are releases that you start manually. Start a manual environment from the flag’s Release tab, or call the Start environment release API. To learn more, read Starting an auto-release manually.
A promotion release in progress in an environment.

A promotion release in progress in an environment.

Promotion releases

Promotion releases are releases that start when the previous environment’s release completes. For example, your staging environment could require manual releases, and your production environment could use promotion releases, so if the release to the staging environment completes successfully, the auto-release in your production environment starts automatically.

Start an auto-release

If you don’t want to use flag evaluations to start an auto-release, you can start an auto-release another way. There are three ways to begin an auto-releases:

Start an auto-release manually

To release something manually:
  1. Navigate to the flag wrapping the change you wish to release and click into its Release tab.
  2. Click Create release. The “Create flag release” dialog appears. This dialog displays a list of the environments where the release will occur, based on the release plan.
  3. Click Create release. The release is recorded and will start when the release trigger occurs.

Start an auto-release with Vega

To release something with Vega:
  1. Navigate to the flag wrapping the change you wish to release and click into its Release tab.
  2. Click Create release. The “Create flag release” dialog appears. This dialog displays a list of the environments where the release will occur, based on the release plan.
  3. To override the release plan for this release, click Customize. A side panel opens where you can converse with Vega to create a custom release configuration.

Start an auto-release with the GitHub app

To release something from the GitHub app:
  1. Navigate to the pull request for the change you wish to release. The GitHub app analyzes the pull request and posts a proposal. To run the analysis again, or to start it on a draft pull request, comment @launchdarkly plan.
  2. Reply to the proposal with @launchdarkly approve to approve the flag and the release together. If you already approved only the flag with @launchdarkly approve flag, reply @launchdarkly approve release instead.
After the release trigger occurs, the release begins. You can track its progress in the flag’s Release tab.
A flag's Release tab, showing the release status in each environment.

A flag's Release tab, showing the release status in each environment.

Release plans

Every auto-release uses a release plan. The release plan defines the default release process at the environment level. Auto-release also needs a project-level flag release plan. LaunchDarkly does not provide a default flag release plan. To learn how to create one, read Configure a flag release plan. After you create a release plan, it affects auto-releases only after you select it or set it as the default for an environment. An environment release plan says how a release runs inside one environment. A flag release plan says how a flag moves through all your environments, using one environment release plan per environment. Each environment release plan covers one environment and defines audiences, rollout steps, regression metrics, and cleanup. A plan that LaunchDarkly migrated from a fallback release policy has no environment. A flag release plan coordinates one or more environments. To apply the same release plan to multiple environments, duplicate the plan, give the copy a new key, and change the environment it applies to. Environment release plan keys are unique within a project. A copy with the same key fails. A flag release plan is an ordered list of environments, such as staging, then production, then federal. Each step specifies:
  • The environment release plan to use, or “immediate,” which just turns the flag on.
  • The trigger type, which is flag evaluation, on deploy, manual, or promotion.
  • After the release completes, the flag lifecycle can continue through code cleanup and archival. Those stages are not part of the flag release plan.
Assigning a flag release plan to a flag creates the flag release. This is the plan Release Autopilot uses when it ships a flag. You can see it in GitHub bot comments like “Once deploy completes, release automatically across 2 environments with the staging-then-production flag release plan.” The following table compares environment release plans and flag release plans:
AttributeEnvironment release planFlag release plan
ScopeOne environmentThe release process across environments
DefinesHow the rollout runs, including rollout steps, audiences, and metricsEnvironment order, triggers, and which environment release plan to use
RelationshipThe building blockUses environment release plans
Tooling at GAUI, API, and Model Context Protocol (MCP)REST API and CLI only
What about release policies?Environment release plans replace release policies. If you use release policies, your existing policies are migrated over automatically.
A release plan requires you to set up everything necessary to be able to start the release automatically. Flag-specific release plans connect multiple environment release plans together sequentially to allow promotion releases. If you want to customize a flag release so it no longer follows the flag release plan exactly, you can describe the changes you want to make to Vega or the GitHub app, which will allow you to deviate from the release plan.
Flag release plans do not support multi-phase releasesEnvironment release plans that a flag release uses must have only one phase. Standalone environment releases can still use multi-phase environment release plans.

Create a release plan

Here’s how to create a release plan:
  1. Navigate to Project Settings, then click Release settings. The Release settings page appears.
  2. Click Create. The Create environment release plan page appears.
  3. Enter a human-readable Name. The plan’s key generates automatically based on the name you enter.
  4. Optionally, enter a Description.
  5. Choose an Environment from the menu. Optionally, click the Default for environment checkbox to set the plan as the default for the environment.
  6. Choose a rollout strategy by choosing an identifier from the Roll out by menu.
  7. Optionally, to monitor the release for regressions, select a metric or metric group from the Monitor for regressions dropdown.
  8. Choose between a Manual or Automatic release phase advancement strategy.
  9. If you choose Manual, you must manually advance the release between phases.
  10. If you choose Automatic, the release will advance automatically based on the rollout strategy you choose.
  11. Create a release phase by designating an Audience and a Rollout strategy: a. Use the Add clause button to specify the audience that should be targeted. b. In the Rollout section, specify what percentage of that audience should be targeted by the release and for what duration. Click Add Step to make the rollout more granular.
  12. Optionally, create additional release phases by clicking Add phase.
  13. Choose between Release to everyone or Keep the release limited to this audience for the final phase.
  14. Click Create plan.

Troubleshoot auto-releases that did not start

A release that did not start, or started before merge, may be due to allFlags() evaluations, which count as traffic. When this happens, the release does not start and no cleanup PR is created. However, internal errors never block a merge. Use the flag’s Release tab to inspect or manually start the waiting environment. Use @launchdarkly plan to re-run pull-request analysis.

Troubleshoot releases that occur prematurely

You may discover that a release occurred prematurely. This can happen if a flag evaluation occurs that triggers the auto-release to begin and then progress through different environments. For example, if you encounter a flag in a preview environment, that counts as an evaluation and could trigger an auto-release.