Launchdarkly guarded rollout

LaunchDarkly Guarded Rollouts#

You're using a skill that will guide you through configuring guarded rollouts in LaunchDarkly. Your job is to design rollout stages, select monitoring metrics, configure regression thresholds, and start the rollout.

Prerequisites#

This skill requires the remotely hosted LaunchDarkly MCP server to be configured in your environment.

Required MCP tools:

• start-guarded-rollout -- start a progressive rollout with monitoring
• get-flag -- inspect the flag and its variations
• list-metrics -- find metrics to monitor during the rollout

Optional MCP tools:

• stop-guarded-rollout -- halt an active rollout immediately
• toggle-flag -- ensure the flag is turned on before starting
• create-metric -- create metrics if they don't exist

Core Concepts#

What Are Guarded Rollouts?#

A guarded rollout progressively increases traffic to a new feature flag variation through a series of stages. At each stage, LaunchDarkly monitors selected metrics for regressions. If a regression is detected, the rollout can automatically pause and notify the team — or even roll back.

Key Components#

Rollout Weight Units#

Rollout weights use thousandths (basis points):

• 1000 = 1%
• 10000 = 10%
• 50000 = 50%
• 100000 = 100%

Monitoring Window#

The monitoring window is specified in milliseconds:

• 3600000 = 1 hour
• 86400000 = 24 hours
• 604800000 = 7 days

Core Principles#

1. Start Small: Begin with a low percentage (1-5%) to catch issues early
2. Monitor What Matters: Choose metrics that reflect user experience
3. Set Realistic Thresholds: Too tight = false alarms; too loose = missed regressions
4. Allow Time: Each stage needs enough monitoring time for signal to emerge
5. Have a Rollback Plan: Always configure at least notification on regression

Workflow#

Step 1: Prepare#

Before starting a guarded rollout:

1. Use get-flag to inspect the flag — note the variation IDs for test and control
2. Use list-metrics to find metrics suitable for monitoring
3. Ensure the flag is on in the target environment (use toggle-flag if needed)
4. Confirm there's no active guarded rollout on this flag already

Step 2: Design Stages#

Plan the rollout progression. A typical pattern:

Step 3: Configure Metrics#

Select metrics that indicate problems:

Step 4: Start the Rollout#

Use start-guarded-rollout:

{
  "projectKey": "my-project",
  "flagKey": "new-checkout-flow",
  "environmentKey": "production",
  "testVariationId": "variation-id-for-new-flow",
  "controlVariationId": "variation-id-for-current-flow",
  "randomizationUnit": "user",
  "stages": [
    {"rolloutWeight": 1000, "monitoringWindowMilliseconds": 3600000},
    {"rolloutWeight": 10000, "monitoringWindowMilliseconds": 86400000},
    {"rolloutWeight": 50000, "monitoringWindowMilliseconds": 86400000},
    {"rolloutWeight": 100000, "monitoringWindowMilliseconds": 86400000}
  ],
  "metrics": [
    {
      "metricKey": "api-error-rate",
      "onRegression": {"notify": true, "rollback": true},
      "regressionThreshold": 0.05
    },
    {
      "metricKey": "checkout-completed",
      "onRegression": {"notify": true, "rollback": false},
      "regressionThreshold": 0.1
    }
  ]
}

Step 5: Verify#

1. Use get-flag to confirm the guarded rollout is active
2. Check that the flag shows the rollout configuration in the environment
3. Monitor for any immediate regression notifications

Report results:

• Guarded rollout started with N stages
• M metrics being monitored
• First stage at X% traffic for Y hours

Stopping a Rollout#

If issues arise or you need to halt the rollout:

{
  "projectKey": "my-project",
  "flagKey": "new-checkout-flow",
  "environmentKey": "production"
}

This immediately stops the progressive rollout and locks the flag at its current state.

Edge Cases#

What NOT to Do#

• Don't start a guarded rollout on a flag that's turned off
• Don't skip the monitoring window design — rushing through stages defeats the purpose
• Don't set regression thresholds to 0 — small fluctuations are normal
• Don't forget to configure at least one metric — a rollout without monitoring is just a regular rollout