Feature Flags in GrowthBook

Purpose

Define common patterns and processes for defining, creating, maintaining, and cleaning up feature flags in GrowthBook to ensure consistency, maintainability, and effective feature management across our apps and services.

Naming Conventions

Feature flag names should be descriptive, consistent, and follow these patterns:

Standard Naming Format

Use dot notation and snake-case with a clear hierarchy:

{service}.{feature}.{version (opt)}.{component (opt)}.{purpose}

Examples:

  • app.floats.select_payback_date.rollout

  • floats.collections.max_ach_attempts.config

  • floats.webhook.balance_check.enabled

  • insight.income_detection.ml.enabled

  • insight.income_detection.ml.rollout

  • prosper.project.enabled

  • prosper.loans.fee_schedule.config

  • global.tiers.config

Purpose

  • enabled - Turn functionality on/off

  • config - Configuration changes

  • rollout - Gradual rollouts of a feature

  • experiment - A/B testing or experiments

  • killswitch - Emergency disable switches

  • maintenance - Maintenance mode or system changes

Naming Anti-Patterns

Avoid:

  • Generic names: test_flag, new_feature

  • Abbreviations: usr-mgmt, pmt-sys

  • Personal identifiers: johns-experiment

Tagging and Labeling

Required Tags

Every feature flag should include tags:

  • service:name (e.g., service:loc, service:floats)

  • env:{name} (e.g. env:test, env:prod)

  • lifecycle:{temporary|permanent}

Component Tags:

  • frontend

  • backend

Feature Flag Descriptions

Description Template

Every flag should include a comprehensive description following this template. This will ensure that it is clear what a feature flag does, how it works, and what needs to be taken into account when someone enables or disables it.

**Purpose:** Brief description of what this flag controls

**Impact:** What happens when enabled/disabled

**Rollout Plan:** How this will be deployed (if applicable)

**Dependencies:** Other flags or systems this depends on

**Rollback Plan:** How to safely disable if issues occur

**Cleanup Date:** When this flag should be removed (if temporary). Link to the cleanup Jira ticket.

Types of Feature Flags

1. Release Flags (Temporary)

Purpose: Control rollout of new features

Lifecycle: Temporary - removed after full rollout has been completed

Default State: Disabled

Characteristics:

  • Used for gradual feature rollouts

  • Allow safe deployment of incomplete features

  • Should be removed once feature is stable

2. Experiment Flags (Temporary)

Purpose: A/B testing and experimentation

Lifecycle: Temporary - removed after experiment concludes

Default State: Control group

Characteristics:

  • Split traffic between variants

  • Include statistical tracking

  • Time-bound with clear end dates

3. Configuration Flags (Permanent)

Purpose: Runtime configuration without deployments

Lifecycle: Permanent

Default State: Production default

Characteristics:

  • Long-term operational controls

  • Environment-specific settings

  • Business rule modifications

4. Kill Switch Flags (Permanent)

Purpose: Emergency disable of features

Lifecycle: Permanent

Default State: Enabled (feature on)

Characteristics:

  • Immediate response capability

  • Critical system protection

  • Always accessible to on-call team

5. Permission Flags (Permanent)

Purpose: Control feature access by user groups

Lifecycle: Permanent

Default State: Disabled for most users

Characteristics:

  • User/role-based targeting

  • Gradual feature access

  • Beta testing capabilities

Implementation Patterns

Boolean Flags

Simple on/off switches for basic feature controls, kill switches, or gradual rollout:

  • For feature enabling, use a boolean flag with a forced value setting.

  • For gradual rollouts, use a boolean flag with a percent rollout setting.

  • For kill switches, use a boolean flag with a forced value setting.

String / Number Flags

For runtime configuration values:

  • Use a string flag for simple text-based configurations.

  • Use a string flag for simple comma separated lists.

  • Use a number flag for simple numeric configurations.

  • DO NOT use a number flag for gradual percentage rollouts. Use a boolean flag with percent rollout instead.

JSON Flags

For more complex configurations requiring basic structured data.

NOTE: Avoid using JSON flags with large payloads. If you need a large JSON configuration payload, consider other options.

Targeting and Audiences

When a specific set of users needs to be targeted, use a saved group instead of defining ad-hoc rules.

Saved Groups

Define a saved group with relevant attributes. Set this saved group on the feature flag rule.

Cleanup and Maintenance

Have a plan in place for cleaning up feature flags at the time of creation. Create Jira tickets and link them in the feature flag description.

Removal Criteria

Remove flags when:

  • Feature rollout is 100% complete for 2+ weeks

  • Experiments have concluded and results implemented

  • No traffic hits the old code path for 30+ days

  • Flag has been disabled for 60+ days without issues

Removal Process

  1. Preparation Phase (1 week before)

    • Announce in team channels with links to Jira ticket and expected timeline

    • Verify no dependencies exist

    • Confirm metrics are stable

  2. Code Cleanup

    • Remove feature flag checks

    • Delete unused code paths

    • Update tests and documentation

    • Force-update app versions if necessary

  3. Flag Retirement

    • Archive flag in GrowthBook

    • Document removal date and reason

    • Update related documentation

Best Practices Summary

Do’s

  • Use descriptive, consistent naming

  • Include comprehensive descriptions

  • Set cleanup dates for temporary flags

  • Monitor flag performance impact

  • Regular cleanup and maintenance

  • Test flag behavior in all environments

  • Document dependencies and rollback plans

  • Share feature flags across frontend and backend when applicable

  • Use a JSON flag instead of multiple individual flags for related configurations

Don’ts

  • Don’t create permanent flags without justification

  • Don’t use flags for quick fixes without proper planning

  • Don’t ignore cleanup dates

  • Don’t create complex nested flag dependencies

  • Don’t deploy flags without proper testing

  • Don’t forget to remove old code paths

  • Don’t use generic or unclear names