# LaunchDarkly

> Connect LaunchDarkly so flag changes join the change ledger next to deploys, and Ace can propose a kill switch, a staged rollout or a version restore.

Source: https://tryace.dev/docs/integrations/launchdarkly

Every LaunchDarkly flag and segment change joins the change ledger, Ace's per-workload record of deploys and config changes. Ace weighs a flag change the same way it weighs a deploy, but LaunchDarkly itself never opens an incident.

| | |
| --- | --- |
| Category | Feature flags |
| Ace reads | Flag and segment changes from the audit log, flag state and targeting, evaluations, flag automation, projects and environments |
| Ace can change | Flag on/off, percentage rollout, restore a flag to an earlier version, only after an admin allows actions |
| Opens incidents | No. Changes join the change ledger. |
| Setup | Settings form. Ace adds its own webhook when the token allows it. |

## What Ace reads

While it investigates a workload with LaunchDarkly under **Investigation sources**, Ace reads:

- Flag and segment changes from the audit log around the incident, with the exact before and after.
- A project's flags in one environment, most recently modified first, with their evaluation status.
- One flag's targeting per environment. Ace gets rule attributes and operators but never the values, and it counts individually targeted contexts without listing them.
- Evaluations per variation in the incident window, compared with the window before. These come from LaunchDarkly's usage API, which is in beta.
- Flag automation: scheduled changes, approvals, triggers, workflows, and guarded or progressive rollouts.

For the System Map, Ace reads projects with their environments and flags, inside your allowlists. On LaunchDarkly **Enterprise** it also reads code references, so it knows which repositories use each flag.

## What Ace can change

Ace proposes LaunchDarkly actions only after an admin turns on **Allow Ace to run approved actions** for the connection. Each one needs approval by default, and earned autonomy can let it run under an Automatic policy for a workload and environment you confirm. See [Actions and approvals](https://tryace.dev/docs/concepts/actions-and-approvals).

| Action | What it does | Approval | Undo |
| --- | --- | --- | --- |
| Flag kill switch | Turns one flag off (or on) in one environment. It can reverse a flag change that Ace tied to the incident. | Approval, or Automatic under your policy | Yes. Restores the previous state as a new action that is approved separately. |
| Percent rollout | Rolls a variation out by percentage in stages. You set the wait between stages (60 to 3,600 seconds). | Approval, or Automatic under your policy | Yes. Serves the previous default again. |
| Flag version restore | Restores a flag's targeting to how it was before a recorded change. | Approval, or Automatic under your policy | Yes |

Ace applies these safeguards:

- Every change carries a comment that names the Ace action, so you can find it in the LaunchDarkly audit log.
- Every change checks the flag version Ace saw. LaunchDarkly refuses the write if the flag changed since.
- Ace refuses to toggle a flag whose changes need a LaunchDarkly approval in that environment.
- Ace rechecks the incident between stages.

Settings shows which actions the token's role allows. Writer, Admin and Owner allow them, and Reader and No access don't. For custom or inline roles, Settings shows that the permission is checked when the action runs.

## What opens an incident

Nothing. LaunchDarkly changes appear on your workloads' timelines and feed investigations, but they never open or join an incident as an alert.

Ace records flag and segment changes in the projects and environments you allow. It keeps the exact fields that changed and any on/off or percentage transition, and it ignores other audit entries. Changes Ace made itself are recorded as part of that action.

Each change belongs to:

1. The workload that routes this connection, if one does. Select **Changes from LaunchDarkly** under the workload's **Integration alerts** sources.
2. Otherwise, each workload mapped to a repository that uses the flag, from code references. This needs LaunchDarkly Enterprise.
3. Otherwise, no workload.

Changes arrive by webhook as they happen. LaunchDarkly retries a delivery only once and doesn't guarantee it, so Ace also polls the audit log every 2 minutes, whether or not a workload routes the connection.

## Before you start

- The **admin** role in Ace.
- A token creator with at least the role you give Ace, for example Writer. A personal access token can't exceed its creator's role.
- LaunchDarkly **Enterprise**, if you want Ace to match changes to workloads through code references.

## Credentials and permissions

| Credential | Where to create it | Role or actions | Why Ace needs it |
| --- | --- | --- | --- |
| Access token (needed) | **Organization settings** > **Authorization** > **Tokens** | Reader role | Read flags, projects, environments and the audit log. |
| Same token (only for the kill switch) | Same | `updateOn` on `proj/*:env/*:flag/*`, or the Writer role | Turn a flag on or off. |
| Same token (only for percent rollouts) | Same | `updateFallthrough`, or the Writer role | Roll a variation out in stages. |
| Same token (only for version restores) | Same | `updateRules`, `updateTargets`, `updateOffVariation`, `updatePrerequisites`, or the Writer role | Restore a flag to an earlier version. |
| Same token (only for automatic webhook setup) | Same | `createWebhook`, `deleteWebhook`, `updateUrl`, `updateSecret`, `updateOn`, `updateStatements` on `webhook/*` | Let Ace add, maintain and remove its own webhook. |
| Signing secret (only for manual webhook setup) | Shown on the webhook once **Sign this webhook** is checked | None | Verifies that deliveries come from LaunchDarkly. |

## Set up

### 1. Create an access token in LaunchDarkly

1. Open **Organization settings** > **Authorization** > **Tokens** and create a token named Ace.
2. Set the role to **Reader**. For approved changes, use **Writer** or an inline policy with the actions above. Add the webhook actions if Ace should set up its own webhook. Keep the latest API version.
3. Save the token and copy it, since LaunchDarkly shows it once.

### 2. Connect LaunchDarkly in Ace

1. Open **Settings** > **Data sources** and choose **LaunchDarkly**.
2. Fill in the form:

   | Field | What to enter |
   | --- | --- |
   | **Access token** | The token you created. |
   | **Instance** | Commercial (app.launchdarkly.com), EU (app.eu.launchdarkly.com) or Federal (app.launchdarkly.us). |
   | **Projects** | Optional. A comma-separated allowlist of project keys. |
   | **Environments** | Optional. A comma-separated allowlist of environment keys, such as `production`. |

3. Select **Connect LaunchDarkly**. Before it saves, Ace checks that it can reach your instance and read projects, flags and the audit log.

### 3. Add the changes webhook

If the token has the webhook permissions, Ace creates a signed webhook named `ace-` plus a short ID, tagged `ace`. It covers every flag and segment change in every environment, and your allowlists decide what Ace records. The **Changes** section then says "Ace set up a signed webhook for flag and segment changes in every environment." Ace rechecks the webhook hourly and removes it when you disconnect.

Without those permissions, the connection still works on polling. To add the webhook yourself:

1. In the **Changes** section, select **Show manual setup** if needed, and copy the webhook URL.
2. In LaunchDarkly, open **Integrations** > **Webhooks**, choose **Add integration**, enter the URL and check **Sign this webhook**.
3. Add a policy statement that allows all actions on `proj/*:env/*:flag/*` and `proj/*:env/*:segment/*`. Accept the Integration Terms and Conditions and save.
4. Copy the signing secret, paste it into Ace and select **Save**.

### 4. Optional: attach changes to a workload

Open the workload in Ace, turn on **Integration alerts**, and select **Changes from LaunchDarkly**. Changes from this connection then belong to that workload.

### 5. Optional: allow actions

Turn on **Allow Ace to run approved actions**. To let flag actions earn Automatic, confirm their workload and environment on the same panel.

## Confirm it's working

- The connection checks the token's identity, projects, flags and audit log. A wrong instance fails with a message that there is no LaunchDarkly API there.
- The **Changes** badge shows **Not set up**, **Waiting for first event**, **Verified** or **Last delivery failed**. Change a flag in an allowed environment, and the badge turns **Verified** when the first signed delivery arrives, and the change appears on the workload's timeline.

## Disconnect

1. In Ace, open the LaunchDarkly connection under **Settings** > **Data sources** and select **Disconnect**. Ace deletes the webhook it created, or shows a warning that names the webhook to remove by hand if it can't.
2. In LaunchDarkly, delete the Ace access token. If you added the webhook yourself, delete it under **Integrations** > **Webhooks**.

## Next steps

- [PostHog](https://tryace.dev/docs/integrations/posthog)
- [Actions and approvals](https://tryace.dev/docs/concepts/actions-and-approvals)
- [All integrations](https://tryace.dev/docs/integrations)