Progressive Rollouts: Ship Features Without Breaking Production

Shipping a feature to 100% of users on day one is a gamble. No matter how thorough your testing, production traffic finds edge cases that staging environments can't replicate. Progressive rollouts eliminate this gamble by gradually exposing new features to increasing percentages of users, with automated safety checks at each stage.

This guide covers the mechanics of progressive rollouts, the patterns that work in practice, and how to set up automated rollouts with safety gates.

What Is a Progressive Rollout?

A progressive rollout is a staged release strategy where a feature is gradually enabled for larger groups of users over time. Instead of a binary on/off deployment, you follow a sequence:

0% → 1% → 5% → 25% → 50% → 100%

At each stage, you monitor key metrics (error rates, latency, conversion rates) and either proceed to the next stage or roll back. The critical property: rollback is instant. You toggle a flag, not redeploy code.

Why Progressive Rollouts Beat Big-Bang Releases

Blast Radius Control

If a feature breaks at 5% rollout, only 5% of users are affected. You roll back in seconds, not the minutes or hours a deployment rollback takes. The total user-impact-minutes are orders of magnitude lower.

Real Production Validation

Staging environments approximate production, but they can't replicate:

• Real traffic patterns and volumes
• Geographic distribution and network conditions
• The full diversity of user data and edge cases
• Third-party service behavior under real load

Progressive rollouts let you validate in production with a safety net.

Data-Driven Decisions

At each rollout stage, you collect real metrics. Is the new checkout flow actually faster? Does the new recommendation algorithm improve engagement? Progressive rollouts turn releases into experiments.

Implementing Progressive Rollouts

Stage 1: Internal Dogfooding (0% Public)

Before any external users see the feature, enable it for your team:

// Target internal users first
{
  "flag": "release-new-search",
  "rules": [
    {
      "conditions": [{
        "attribute": "email",
        "operator": "ends_with",
        "value": "@yourcompany.com"
      }],
      "percentage": 100
    }
  ],
  "defaultValue": false
}

This catches obvious issues — broken layouts, missing error handling, wrong copy — before any real users encounter them.

Stage 2: Canary Release (1-5%)

Enable for a small percentage of real users. The goal is to detect issues that only appear with diverse, real-world usage:

{
  "flag": "release-new-search",
  "rules": [
    // Internal: always on
    {
      "conditions": [{ "attribute": "email", "operator": "ends_with", "value": "@yourcompany.com" }],
      "percentage": 100
    },
    // Canary: 5% of all users
    {
      "conditions": [],
      "percentage": 5
    }
  ]
}

What to monitor at this stage:

• Error rates (5xx responses, client-side exceptions)
• Latency (p50, p95, p99)
• Core business metrics (conversion, engagement)
• Resource utilization (CPU, memory, database queries)

Stage 3: Expanded Rollout (25-50%)

If canary metrics look healthy after a defined soak period (typically 1-4 hours), increase the percentage. At this point, you're looking for performance issues that only appear at scale:

• Database query patterns that don't scale linearly
• Cache hit rates changing under load
• Rate limiting or quota issues with third-party services

Stage 4: General Availability (100%)

Roll out to everyone. Keep the flag active for a few days as a kill switch, then schedule flag removal.

Consistent Hashing: Why User Experience Matters

A naive percentage rollout might randomly select different users each time. User A sees the new feature on one page load, then gets the old experience on the next. This is jarring and makes debugging impossible.

Consistent hashing solves this. The flag evaluation engine hashes the user ID to produce a stable number between 0 and 100. If a user's hash is 23, they see the feature when the rollout is at 25% or higher, and don't see it when it's below 23%.

User "alice" → hash: 23 → included at 25% rollout
User "bob"   → hash: 67 → included at 75% rollout
User "carol" → hash: 3  → included at 5% rollout

Properties of consistent hashing:

• Sticky — the same user always gets the same experience for a given rollout percentage
• Monotonic — users added at a lower percentage stay included at higher percentages
• Uniform — users are evenly distributed across the hash space

Flaggr uses MurmurHash3 for consistent flag evaluation. See advanced evaluation for implementation details.

Automated Safety Checks

Manual rollouts work for small teams, but they don't scale. Automated safety checks (also called "guardrail metrics") let you define conditions that must be met before advancing to the next stage.

Define Guardrail Metrics

rollout:
  flag: release-new-checkout
  stages:
    - percentage: 5
      duration: 2h
      gates:
        - metric: error_rate
          threshold: "< 0.5%"
        - metric: p99_latency
          threshold: "< 500ms"
        - metric: conversion_rate
          threshold: "> 95% of baseline"
    - percentage: 25
      duration: 4h
      gates:
        - metric: error_rate
          threshold: "< 0.5%"
    - percentage: 100
      duration: 0  # Final stage

Automatic Rollback

If any guardrail metric breaches its threshold, the rollout automatically pauses or rolls back:

1. Pause — stop advancing but keep current percentage
2. Roll back — revert to previous stage or 0%
3. Alert — notify the flag owner for manual investigation

The appropriate response depends on severity. A slight latency increase might warrant a pause, while a spike in error rates demands immediate rollback.

Rollout Patterns for Different Scenarios

Ring-Based Rollout

Instead of random percentages, roll out in defined rings:

This is common in enterprise environments where you want feedback from specific user segments before broad release.

Geographic Rollout

Roll out to specific regions first:

{
  "rules": [
    {
      "conditions": [{ "attribute": "country", "operator": "in", "value": ["AU", "NZ"] }],
      "percentage": 100
    }
  ]
}

Useful when:

• You want to test during low-traffic hours (roll out to regions ahead in timezone)
• Regulatory requirements differ by region
• You want to validate localization

Cohort-Based Rollout

Target specific user segments rather than random percentages:

{
  "rules": [
    // Free users first (lower risk)
    {
      "conditions": [{ "attribute": "plan", "operator": "equals", "value": "free" }],
      "percentage": 50
    },
    // Enterprise users last (highest risk)
    {
      "conditions": [{ "attribute": "plan", "operator": "equals", "value": "enterprise" }],
      "percentage": 0
    }
  ]
}

Common Pitfalls

1. Skipping the Soak Period

Advancing from 5% to 100% after 10 minutes of green metrics is tempting but dangerous. Some issues only manifest over hours — memory leaks, cache degradation, rate limit exhaustion. Let each stage soak for at least 1-2 hours.

2. Not Monitoring the Right Metrics

Monitoring only server-side error rates misses client-side issues. Track:

• Server error rates AND client-side exceptions
• Core Web Vitals (LCP, FID, CLS) for frontend features
• Business metrics, not just technical metrics

3. Rolling Out Multiple Features Simultaneously

If you roll out features A and B to overlapping user groups, you can't determine which one caused a metric regression. Use mutual exclusion groups to ensure clean experiment isolation.

4. No Rollback Plan

Every rollout should have a documented rollback procedure. With feature flags, this is usually just "set percentage to 0%." But make sure:

• The flag actually controls all paths (no hardcoded behavior)
• Rollback doesn't cause data inconsistencies (e.g., users who started a multi-step flow)
• The team knows who can trigger a rollback and how

Progressive Rollouts in Flaggr

Flaggr supports progressive rollouts with:

• Percentage-based targeting with consistent hashing for sticky user assignment
• Targeting rules for ring-based, geographic, and cohort-based rollouts
• Scheduled rules for time-based stage advancement
• Flag health monitoring for automated metric tracking
• Alerting with configurable thresholds for error rates and latency
• Instant rollback via the dashboard, API, or Terraform

See the progressive rollouts guide for step-by-step setup instructions.

Ready to set up your first progressive rollout? Start with the Flaggr quick start and follow the targeting rules guide to configure staged releases.