Feature Flags and Progressive Rollouts: Ship Faster Without Breaking Production

Deploying new features to production has always been a high-stakes operation. One bad release can cascade into downtime, lost revenue, and frustrated users. Yet modern engineering teams are expected to ship continuously, sometimes multiple times per day. The tension between speed and stability seems impossible to resolve — until you introduce feature flags and progressive rollouts into your deployment pipeline.

Feature flags (also called feature toggles or feature switches) decouple code deployment from feature release. Progressive rollouts take this a step further by gradually exposing new functionality to increasing segments of your user base. Together, these techniques let you deploy with confidence, test in production safely, and roll back instantly when something goes wrong.

This guide covers everything you need to implement feature flags and progressive rollouts effectively: from foundational concepts and practical code examples to operational best practices and common pitfalls. Whether you are building a microservices architecture or maintaining a monolithic application, these patterns will transform how you ship software.

What Are Feature Flags?

A feature flag is a conditional wrapper around a piece of functionality that lets you turn it on or off at runtime without redeploying your application. At its simplest, a feature flag is a boolean check: if the flag is enabled, execute the new code path; otherwise, fall back to the existing behavior.

But modern feature flag systems go far beyond simple on/off switches. They support percentage-based rollouts, user segmentation, A/B testing, kill switches, and scheduled activations. The flag evaluation logic can consider user attributes, geographic location, device type, subscription tier, and dozens of other targeting criteria.

Types of Feature Flags

Understanding the different types of feature flags helps you apply them appropriately:

• Release flags — Control the rollout of new features. These are temporary and should be removed once the feature is fully launched. They are the most common type and the primary focus of this guide.
• Experiment flags — Enable A/B testing and multivariate experiments. They route users into different cohorts and track metrics for each variant.
• Operational flags — Act as circuit breakers or kill switches for specific system behaviors. They let you degrade gracefully under load by disabling expensive features.
• Permission flags — Gate access to premium or beta features based on user entitlements, subscription plans, or internal roles.

Each type has a different lifecycle. Release flags live for days or weeks. Experiment flags persist for the duration of the test. Operational flags may stay in the codebase permanently as safety mechanisms. Permission flags are long-lived and tied to your business model.

Why Feature Flags Matter for Modern Development

Feature flags solve several fundamental problems in software delivery:

Decoupling Deployment from Release

Without feature flags, deploying code and releasing a feature happen simultaneously. This means every deployment is a potential incident. With feature flags, you can merge and deploy code that is hidden behind a flag, then release it independently when you are ready. Your CI/CD pipeline deploys continuously, while product and engineering teams control when users actually see new features.

Reducing Risk

A progressive rollout limits blast radius. Instead of exposing a new feature to 100% of users at once, you start with 1%, then 5%, then 25%, and so on. At each stage, you monitor error rates, performance metrics, and user feedback. If something goes wrong, you turn off the flag — no rollback, no hotfix, no emergency deployment. This approach aligns perfectly with a healthy DevOps culture where teams own their releases end to end.

Enabling Trunk-Based Development

Long-lived feature branches create merge conflicts, knowledge silos, and integration headaches. Feature flags let everyone commit to the main branch continuously. Incomplete features are simply wrapped in flags that remain off in production. This dramatically reduces merge complexity and keeps the codebase in a perpetually deployable state.

Supporting Product Experimentation

Product teams need to validate hypotheses quickly. Feature flags let them run experiments in production with real users, collect data, and make informed decisions. The engineering effort to set up an experiment drops from days to minutes once the flag infrastructure is in place.

Building a Feature Flag SDK in TypeScript

Let us build a practical feature flag SDK that supports boolean flags, percentage rollouts, and user targeting. This implementation demonstrates the core concepts you will find in production-grade flag systems.

// feature-flags.ts — A practical feature flag SDK with targeting and rollout support

import { createHash } from 'crypto';

interface UserContext {
  userId: string;
  email?: string;
  country?: string;
  plan?: 'free' | 'starter' | 'pro' | 'enterprise';
  attributes?: Record<string, string | number | boolean>;
}

interface TargetingRule {
  attribute: string;
  operator: 'eq' | 'neq' | 'in' | 'gt' | 'lt' | 'contains';
  value: string | number | boolean | string[];
}

interface FlagConfig {
  key: string;
  enabled: boolean;
  rolloutPercentage: number; // 0-100
  targetingRules: TargetingRule[];
  allowlist: string[];  // User IDs that always see the feature
  blocklist: string[];  // User IDs that never see the feature
  salt?: string;        // For deterministic hashing
}

interface FlagEvaluation {
  flagKey: string;
  enabled: boolean;
  reason: 'killed' | 'allowlisted' | 'blocklisted' | 'targeted' | 'rollout' | 'default';
  timestamp: number;
}

class FeatureFlagClient {
  private flags: Map<string, FlagConfig> = new Map();
  private evaluationLog: FlagEvaluation[] = [];

  constructor(private config: { logEvaluations: boolean }) {}

  registerFlag(flag: FlagConfig): void {
    this.flags.set(flag.key, {
      ...flag,
      salt: flag.salt || flag.key,
    });
  }

  evaluate(flagKey: string, user: UserContext): boolean {
    const flag = this.flags.get(flagKey);
    if (!flag) {
      this.logEvaluation(flagKey, false, 'default');
      return false; // Unknown flags default to off
    }

    // Global kill switch — flag is completely disabled
    if (!flag.enabled) {
      this.logEvaluation(flagKey, false, 'killed');
      return false;
    }

    // Check blocklist first (deny takes precedence)
    if (flag.blocklist.includes(user.userId)) {
      this.logEvaluation(flagKey, false, 'blocklisted');
      return false;
    }

    // Check allowlist (always-on for specific users)
    if (flag.allowlist.includes(user.userId)) {
      this.logEvaluation(flagKey, true, 'allowlisted');
      return true;
    }

    // Evaluate targeting rules (all must match)
    if (flag.targetingRules.length > 0) {
      const targeted = flag.targetingRules.every(rule =>
        this.evaluateRule(rule, user)
      );
      if (!targeted) {
        this.logEvaluation(flagKey, false, 'targeted');
        return false;
      }
    }

    // Percentage-based rollout using deterministic hashing
    const bucket = this.calculateBucket(user.userId, flag.salt!);
    const enabled = bucket < flag.rolloutPercentage;
    this.logEvaluation(flagKey, enabled, 'rollout');
    return enabled;
  }

  private evaluateRule(rule: TargetingRule, user: UserContext): boolean {
    const userValue = this.getUserAttribute(rule.attribute, user);
    if (userValue === undefined) return false;

    switch (rule.operator) {
      case 'eq':  return userValue === rule.value;
      case 'neq': return userValue !== rule.value;
      case 'gt':  return Number(userValue) > Number(rule.value);
      case 'lt':  return Number(userValue) < Number(rule.value);
      case 'in':  return Array.isArray(rule.value) && rule.value.includes(String(userValue));
      case 'contains':
        return typeof userValue === 'string' && userValue.includes(String(rule.value));
      default: return false;
    }
  }

  private getUserAttribute(attr: string, user: UserContext): unknown {
    if (attr in user) return (user as Record<string, unknown>)[attr];
    return user.attributes?.[attr];
  }

  private calculateBucket(userId: string, salt: string): number {
    // Deterministic hash ensures the same user always gets the same bucket
    const hash = createHash('sha256')
      .update(`${salt}:${userId}`)
      .digest('hex');
    const numericHash = parseInt(hash.substring(0, 8), 16);
    return numericHash % 100;
  }

  private logEvaluation(flagKey: string, enabled: boolean, reason: FlagEvaluation['reason']): void {
    if (!this.config.logEvaluations) return;
    this.evaluationLog.push({
      flagKey,
      enabled,
      reason,
      timestamp: Date.now(),
    });
  }

  getEvaluationLog(): FlagEvaluation[] {
    return [...this.evaluationLog];
  }
}

// --- Usage Example ---

const client = new FeatureFlagClient({ logEvaluations: true });

client.registerFlag({
  key: 'new-checkout-flow',
  enabled: true,
  rolloutPercentage: 25,
  targetingRules: [
    { attribute: 'plan', operator: 'in', value: ['pro', 'enterprise'] }
  ],
  allowlist: ['user-internal-qa-1', 'user-internal-qa-2'],
  blocklist: [],
});

const user: UserContext = {
  userId: 'usr_8f3k2',
  email: 'dev@example.com',
  country: 'US',
  plan: 'pro',
};

if (client.evaluate('new-checkout-flow', user)) {
  // Render the new checkout experience
  renderNewCheckout();
} else {
  // Render the existing checkout
  renderLegacyCheckout();
}

This SDK uses a deterministic hashing strategy: a given user always lands in the same rollout bucket for a given flag. This is critical — without deterministic assignment, a user might see the new feature on one page load and the old version on the next, creating a confusing experience. The hash combines the user ID with a flag-specific salt, so different flags can have independent rollout groups.

Implementing a Progressive Rollout Controller

A progressive rollout controller automates the process of gradually increasing a flag’s rollout percentage based on real-time health metrics. Instead of manually bumping from 5% to 10% to 25%, the controller monitors your application and advances the rollout automatically when conditions are healthy — or halts and rolls back when they are not.

// rollout-controller.ts — Automated progressive rollout with health checks

interface HealthMetrics {
  errorRate: number;        // Percentage (0-100)
  p99Latency: number;       // Milliseconds
  saturationRate: number;   // CPU/Memory usage percentage
  businessMetric?: number;  // e.g., conversion rate for the feature
}

interface RolloutStage {
  percentage: number;
  minimumDuration: number;    // Minutes to stay at this stage
  healthThresholds: {
    maxErrorRate: number;
    maxP99Latency: number;
    maxSaturation: number;
  };
}

interface RolloutPlan {
  flagKey: string;
  stages: RolloutStage[];
  rollbackOnFailure: boolean;
  notifyChannels: string[];   // Slack channels, email lists, etc.
}

type RolloutStatus = 'pending' | 'in_progress' | 'paused' | 'completed' | 'rolled_back';

class ProgressiveRolloutController {
  private currentStageIndex: number = 0;
  private stageStartTime: number = 0;
  private status: RolloutStatus = 'pending';
  private healthHistory: HealthMetrics[] = [];

  constructor(
    private plan: RolloutPlan,
    private flagService: { setRolloutPercentage: (key: string, pct: number) => Promise<void> },
    private metricsService: { getCurrentHealth: (flagKey: string) => Promise<HealthMetrics> },
    private notificationService: { send: (channels: string[], message: string) => Promise<void> }
  ) {}

  async start(): Promise<void> {
    this.status = 'in_progress';
    this.currentStageIndex = 0;
    await this.applyCurrentStage();
    this.monitor();
  }

  private async applyCurrentStage(): Promise<void> {
    const stage = this.plan.stages[this.currentStageIndex];
    await this.flagService.setRolloutPercentage(this.plan.flagKey, stage.percentage);
    this.stageStartTime = Date.now();

    await this.notificationService.send(
      this.plan.notifyChannels,
      `Rollout "${this.plan.flagKey}" advanced to ${stage.percentage}% ` +
      `(stage ${this.currentStageIndex + 1}/${this.plan.stages.length})`
    );
  }

  private async monitor(): Promise<void> {
    const CHECK_INTERVAL = 60_000; // Check every minute

    const interval = setInterval(async () => {
      if (this.status !== 'in_progress') {
        clearInterval(interval);
        return;
      }

      try {
        const health = await this.metricsService.getCurrentHealth(this.plan.flagKey);
        this.healthHistory.push(health);

        const stage = this.plan.stages[this.currentStageIndex];
        const isHealthy = this.checkHealth(health, stage);

        if (!isHealthy) {
          await this.handleUnhealthy(health, stage);
          clearInterval(interval);
          return;
        }

        // Check if minimum duration at current stage has passed
        const elapsed = (Date.now() - this.stageStartTime) / 60_000;
        if (elapsed >= stage.minimumDuration) {
          await this.advanceStage();
          if (this.status === 'completed') {
            clearInterval(interval);
          }
        }
      } catch (err) {
        console.error('Health check failed:', err);
        // Don't advance on monitoring failures — stay at current stage
      }
    }, CHECK_INTERVAL);
  }

  private checkHealth(metrics: HealthMetrics, stage: RolloutStage): boolean {
    const { healthThresholds } = stage;
    return (
      metrics.errorRate <= healthThresholds.maxErrorRate &&
      metrics.p99Latency <= healthThresholds.maxP99Latency &&
      metrics.saturationRate <= healthThresholds.maxSaturation
    );
  }

  private async handleUnhealthy(metrics: HealthMetrics, stage: RolloutStage): Promise<void> {
    const detail = `Error rate: ${metrics.errorRate}% (max ${stage.healthThresholds.maxErrorRate}%), ` +
      `P99: ${metrics.p99Latency}ms (max ${stage.healthThresholds.maxP99Latency}ms), ` +
      `Saturation: ${metrics.saturationRate}% (max ${stage.healthThresholds.maxSaturation}%)`;

    if (this.plan.rollbackOnFailure) {
      await this.flagService.setRolloutPercentage(this.plan.flagKey, 0);
      this.status = 'rolled_back';
      await this.notificationService.send(
        this.plan.notifyChannels,
        `ROLLBACK: "${this.plan.flagKey}" rolled back to 0%. Health degraded at ` +
        `${stage.percentage}% rollout.\n${detail}`
      );
    } else {
      this.status = 'paused';
      await this.notificationService.send(
        this.plan.notifyChannels,
        `PAUSED: "${this.plan.flagKey}" rollout paused at ${stage.percentage}%. ` +
        `Health thresholds exceeded.\n${detail}`
      );
    }
  }

  private async advanceStage(): Promise<void> {
    if (this.currentStageIndex >= this.plan.stages.length - 1) {
      this.status = 'completed';
      await this.notificationService.send(
        this.plan.notifyChannels,
        `Rollout "${this.plan.flagKey}" completed at 100%. All stages passed health checks.`
      );
      return;
    }

    this.currentStageIndex++;
    await this.applyCurrentStage();
  }

  getStatus(): { status: RolloutStatus; stage: number; percentage: number } {
    return {
      status: this.status,
      stage: this.currentStageIndex + 1,
      percentage: this.plan.stages[this.currentStageIndex]?.percentage ?? 0,
    };
  }
}

// --- Usage: Define a rollout plan and start ---

const rolloutPlan: RolloutPlan = {
  flagKey: 'new-checkout-flow',
  rollbackOnFailure: true,
  notifyChannels: ['#deployments', '#engineering-alerts'],
  stages: [
    {
      percentage: 1,
      minimumDuration: 30,    // 30 minutes at 1%
      healthThresholds: { maxErrorRate: 0.5, maxP99Latency: 500, maxSaturation: 70 },
    },
    {
      percentage: 5,
      minimumDuration: 60,    // 1 hour at 5%
      healthThresholds: { maxErrorRate: 1.0, maxP99Latency: 600, maxSaturation: 75 },
    },
    {
      percentage: 25,
      minimumDuration: 120,   // 2 hours at 25%
      healthThresholds: { maxErrorRate: 1.5, maxP99Latency: 700, maxSaturation: 80 },
    },
    {
      percentage: 50,
      minimumDuration: 180,   // 3 hours at 50%
      healthThresholds: { maxErrorRate: 2.0, maxP99Latency: 800, maxSaturation: 85 },
    },
    {
      percentage: 100,
      minimumDuration: 0,
      healthThresholds: { maxErrorRate: 2.0, maxP99Latency: 1000, maxSaturation: 90 },
    },
  ],
};

This controller embodies a key principle: never advance a rollout if the system is unhealthy. Each stage defines explicit health thresholds, and the controller checks them continuously. If error rates spike or latency degrades beyond acceptable limits, the rollout pauses or rolls back automatically. This is essential when paired with a robust monitoring and observability setup that feeds real-time metrics into the controller.

Best Practices for Feature Flag Management

1. Keep Flags Short-Lived

Release flags should be temporary. Once a feature is fully rolled out and stable, remove the flag and its conditional logic from the code. Accumulating stale flags creates technical debt: the codebase becomes harder to read, test matrices explode, and developers lose track of which flags are active. Establish a flag hygiene policy — for example, every flag must have an owner and an expiration date.

2. Use a Naming Convention

Adopt a consistent naming scheme that communicates intent. A pattern like release.checkout-redesign, experiment.pricing-page-v2, or ops.disable-recommendation-engine immediately tells developers the flag’s type and purpose. Include the team or domain prefix for larger organizations.

3. Test Both Paths

Every feature flag creates a branch in your code. Both the “on” and “off” paths must be tested. If you only test the new path, you risk breaking the fallback path that most users still rely on during a rollout. Integrate flag states into your test suite and run tests with flags in both positions.

4. Centralize Flag Configuration

Avoid scattering flag definitions across configuration files, environment variables, and hardcoded constants. Use a centralized flag management system — whether it is a dedicated service, a configuration database, or a third-party platform. Centralization gives you a single source of truth, audit trails, and the ability to change flags without code changes. This pairs well with solid API design practices for the flag evaluation endpoints.

5. Monitor Flag Impact

Every flag evaluation should emit telemetry. Track which flags are evaluated, how often each path is taken, and correlate flag state with application metrics. This data is invaluable for debugging issues that only affect users in a specific flag cohort and for measuring the impact of new features on business metrics.

6. Implement Proper Fallbacks

When the flag service is unavailable, your application should still function. Define sensible defaults for each flag — typically “off” for new features and “on” for established ones. The flag evaluation SDK should handle network failures, timeouts, and invalid configurations gracefully without crashing the application.

Progressive Rollout Strategies

There is no single correct rollout strategy. The right approach depends on the risk profile of the change, the size of your user base, and your monitoring capabilities.

Percentage-Based Rollout

The most common strategy. Start at 1%, gradually increase to 5%, 10%, 25%, 50%, and finally 100%. The pace depends on your confidence and the quality of your health signals. For low-risk UI changes, you might go from 0 to 100% in a single day. For critical payment flow changes, the rollout might take two weeks with manual approval gates between stages.

Geographic Rollout

Release to users in a specific region first. This is particularly useful when the feature involves infrastructure changes (new database, third-party integration) that may behave differently across regions. Start with a region that has lower traffic, validate, then expand globally.

Cohort-Based Rollout

Target specific user segments: internal employees first, then beta users, then free-tier users, and finally paying customers. This approach is common for enterprise products where the risk tolerance varies dramatically between customer tiers. Plan your rollout stages thoughtfully, much like you would approach sprint planning — defining clear goals, success criteria, and checkpoints for each phase.

Canary Releases

Deploy the new code to a small subset of servers (the “canaries”) while the majority of servers run the old version. This is an infrastructure-level approach that complements application-level feature flags. Canary releases catch issues related to deployment artifacts, environment configuration, and infrastructure compatibility that feature flags alone cannot detect.

Feature Flags in Different Architectures

Client-Side vs. Server-Side Flags

Server-side flags are evaluated on your backend, giving you full control over the evaluation logic and eliminating the risk of users manipulating flag state. Client-side flags are evaluated in the browser or mobile app, enabling faster UI rendering without a round trip to the server. Most production systems use both: server-side flags for business logic and security-sensitive features, client-side flags for UI components and personalization. When choosing between SSR and CSR rendering strategies, consider how your flag evaluation model interacts with the rendering pipeline.

Flags in Microservices

In a microservices architecture, feature flags introduce coordination challenges. A user-facing feature might span multiple services, each needing to evaluate the same flag consistently. Solutions include propagating flag context through request headers, sharing a centralized flag store, or using a sidecar proxy that injects flag decisions. The key requirement is consistency: a user flagged “on” in the API gateway must also be flagged “on” in downstream services.

Flags and CI/CD Integration

Feature flags should integrate with your CI/CD tooling. Your deployment pipeline can automatically create release flags for new features, run tests against both flag states, and even trigger progressive rollouts after a successful deployment. Some teams automate the entire lifecycle: a pull request creates a flag, merging enables it for internal users, and a manual approval starts the production rollout.

Common Pitfalls and How to Avoid Them

Flag Debt

The number one problem with feature flags is accumulation. Teams add flags enthusiastically but rarely clean them up. Over time, the codebase becomes a maze of conditional logic. Combat this by treating flag removal as part of the feature launch process. A feature is not “done” when it reaches 100% — it is done when the flag is removed and the old code path is deleted.

Testing Complexity

With N flags, you have 2^N possible combinations. Testing all of them is impractical. Instead, focus on testing each flag independently in both states and identify combinations that are likely to interact. Flag dependencies (flag B only makes sense when flag A is on) should be documented and enforced in the evaluation logic.

Inconsistent Evaluation

If a user sees the new checkout flow on the product page but the old flow on the payment page, the experience is broken. Ensure flag evaluation is consistent across all touchpoints within a single user session. Use the deterministic hashing approach shown earlier and cache flag decisions per session.

Performance Impact

Flag evaluation on every request can add latency if the flag store is remote. Mitigate this with local caching, background synchronization, and SDK-level optimizations. The flag SDK should fetch the full flag configuration on startup and refresh it periodically, evaluating flags locally without network calls.

Security Considerations

Client-side flag configurations can be inspected by users. Never use client-side flags to gate access to sensitive features or premium content — the flag might say “off,” but the code for the feature is still in the bundle. Security-sensitive gating must happen server-side, with the server deciding what data and functionality to expose.

Choosing a Feature Flag Solution

You have three main options:

Build in-house: Maximum flexibility and no vendor dependency. Suitable for organizations with strong infrastructure teams that need deep integration with existing systems. The code examples above provide a solid foundation. For teams managing complex projects with feature flags, a structured workflow tool like Taskee can help coordinate rollout stages and flag lifecycle management across team members.

Open-source solutions: Projects like Unleash, Flagsmith, and OpenFeature provide production-ready flag management with self-hosting options. They offer dashboards, audit logs, and SDKs for multiple languages out of the box. A strong choice for teams that want the benefits of a managed solution without vendor lock-in.

Commercial platforms: LaunchDarkly, Split, and similar services offer the most polished experience with advanced targeting, experimentation, and analytics. They handle the operational overhead of running flag infrastructure at scale. Best for organizations where engineering time is expensive and flag management is a core workflow. When evaluating these options, consider working with a professional web development consultancy that can assess your architecture and recommend the approach that fits your team’s maturity and scale.

Real-World Rollout Workflow

Here is how a typical progressive rollout works in practice, from code to full release:

1. Development: A developer implements a new feature behind a release flag. The flag defaults to “off.” Code is merged to the main branch and deployed to production — invisible to users.
2. Internal testing: The flag is enabled for the engineering team using the allowlist. QA verifies the feature in the production environment with real data.
3. Beta rollout (1-5%): The flag is opened to a small percentage of real users. The team monitors error rates, latency, and user feedback for at least 30 minutes.
4. Expanded rollout (10-50%): If health metrics look good, the percentage increases in stages. Each stage has a minimum bake time. Dashboards are watched closely.
5. Full release (100%): The flag is opened to all users. The team continues monitoring for 24-48 hours.
6. Cleanup: After the feature is stable at 100%, the flag is removed from the codebase. The conditional logic is replaced with the new code path only. The flag configuration is archived.

This workflow can be fully automated with the progressive rollout controller shown earlier, or managed manually through a flag dashboard. The right approach depends on the change’s risk profile and your team’s confidence in the monitoring infrastructure.

Measuring Success

Feature flags are not just a deployment mechanism — they are a measurement tool. Track these metrics to understand the impact of your rollout:

• Feature adoption rate: What percentage of eligible users actively use the new feature?
• Error rate delta: How does the error rate for flagged users compare to the control group?
• Performance impact: Is p50/p95/p99 latency affected by the new code path?
• Business metrics: Conversion rates, engagement, retention — are they improving for the flagged cohort?
• Rollback frequency: How often do rollouts fail and trigger rollbacks? This is a proxy for release quality.

These metrics feed into a continuous improvement loop. If rollbacks are frequent, invest in better testing. If feature adoption is low, improve the UX. If performance degrades, optimize before expanding the rollout.

Frequently Asked Questions