• When to use feature flags
• Feature flags in GitLab development
• Risk of a broken main branch
• Types of feature flags
  • development type
  • ops type
  • experiment type
• Feature flag definition and validation
• Create a new feature flag
  • Risk of a broken master (main) branch
• List all the feature flags
• Delete a feature flag
• Develop with a feature flag
  • Backend
    • Recursion detection
  • Frontend
  • Feature actors
    • Selectively disable by actor
    • Use actors for verifying in production
  • Enable additional objects as actors
  • Feature flags for licensed features
  • Feature groups
  • Enabling a feature flag locally (in development)
  • Removing a feature flag locally (in development)
• Changelog
• Feature flags in tests
  • have_pushed_frontend_feature_flags
  • stub_feature_flags vs Feature.enable*
  • Stubbing actor
  • Controlling feature flags engine in tests
    • stub_feature_flags: true (default and preferred)
  • stub_feature_flags: false
  • End-to-end (QA) tests

Feature flags in the development of GitLab

This document provides guidelines on how to use feature flags for the development of GitLab to conditionally and/or incrementally enable features and test them in production/staging.

For an overview of the feature flag lifecycle, or if you need help deciding if you should use a feature flag or not, please see the feature flag lifecycle handbook page.

When to use feature flags

Moved to the “When to use feature flags” section in the handbook.

Feature flags in GitLab development

The following highlights should be considered when deciding if feature flags should be leveraged:

• The feature flag must be disabled by default.
• Feature flags should remain in the codebase for as short period as possible to reduce the need for feature flag accounting.
• The person operating the feature flag is responsible for clearly communicating the status of a feature behind the feature flag in the documentation and with other stakeholders. The issue description should be updated with the feature flag name and whether it is defaulted on or off as soon it is evident that a feature flag is needed.
• Merge requests that introduce a feature flag, update its state, or remove them existing feature flag because a feature is deemed stable must have the ~"feature flag" label assigned.

When the feature implementation is delivered among multiple merge requests:

1. Create a new feature flag which is off by default, in the first merge request which uses the flag. Flags should not be added separately.
2. Submit incremental changes via one or more merge requests, ensuring that any new code added can only be reached if the feature flag is on. You can keep the feature flag enabled on your local GDK during development.
3. When the feature is ready to be tested, enable the feature flag for a specific project and ensure that there are no issues with the implementation.
4. When the feature is ready to be announced, create a merge request that adds documentation about the feature, including documentation for the feature flag itself, and a changelog entry. In the same merge request either flip the feature flag to be on by default or remove it entirely in order to enable the new behavior.

One might be tempted to think that feature flags will delay the release of a feature by at least one month (= one release). This is not the case. A feature flag does not have to stick around for a specific amount of time (for example, at least one release), instead they should stick around until the feature is deemed stable. Stable means it works on GitLab.com without causing any problems, such as outages.

Risk of a broken main branch

Feature flags must be used in the MR that introduces them. Not doing so causes a broken main branch scenario due to the rspec:feature-flags job that only runs on the main branch.

Types of feature flags

Choose a feature flag type that matches the expected usage.

development type

development feature flags are short-lived feature flags, used for deploying unfinished code to production. Most feature flags used at GitLab are the development type.

A development feature flag must have a rollout issue created from the Feature Flag Roll Out template.

The format for development feature flags is Feature.<state>(:<dev_flag_name>). To enable and disable them, run on the GitLab Rails console:

# To enable it for the instance:
Feature.enable(:<dev_flag_name>)

# To disable it for the instance:
Feature.disable(:<dev_flag_name>)

# To enable for a specific project:
Feature.enable(:<dev_flag_name>, Project.find(<project id>))

# To disable for a specific project:
Feature.disable(:<dev_flag_name>, Project.find(<project id>))

To check a development feature flag’s state:

# Check if the feature flag is enabled
Feature.enabled?(:dev_flag_name)

# Check if the feature flag is disabled
Feature.disabled?(:dev_flag_name)

For development feature flags, the type doesn’t need to be specified (they’re the default type).

ops type

ops feature flags are long-lived feature flags that control operational aspects of GitLab product behavior. For example, feature flags that disable features that might have a performance impact such as Sidekiq worker behavior.

ops feature flags likely do not have rollout issues, as it is hard to predict when they are enabled or disabled.

To invoke ops feature flags, you must append type: :ops:

# Check if feature flag is enabled
Feature.enabled?(:my_ops_flag, project, type: :ops)

# Check if feature flag is disabled
Feature.disabled?(:my_ops_flag, project, type: :ops)

# Push feature flag to Frontend
push_frontend_feature_flag(:my_ops_flag, project, type: :ops)

experiment type

experiment feature flags are used for A/B testing on GitLab.com.

An experiment feature flag should conform to the same standards as a development feature flag, although the interface has some differences. An experiment feature flag should have a rollout issue, created using the Experiment Tracking template. More information can be found in the experiment guide.

Feature flag definition and validation

During development (RAILS_ENV=development) or testing (RAILS_ENV=test) all feature flag usage is being strictly validated.

This process is meant to ensure consistent feature flag usage in the codebase. All feature flags must:

• Be known. Only use feature flags that are explicitly defined.
• Not be defined twice. They have to be defined either in FOSS or EE, but not both.
• Use a valid and consistent type: across all invocations.
• Have an owner.

All feature flags known to GitLab are self-documented in YAML files stored in:

• config/feature_flags
• ee/config/feature_flags

Each feature flag is defined in a separate YAML file consisting of a number of fields:

Create a new feature flag

The GitLab codebase provides bin/feature-flag, a dedicated tool to create new feature flag definitions. The tool asks various questions about the new feature flag, then creates a YAML definition in config/feature_flags or ee/config/feature_flags.

Only feature flags that have a YAML definition file can be used when running the development or testing environments.

$ bin/feature-flag my_feature_flag
>> Specify the group introducing the feature flag, like `group::apm`:
?> group::memory

>> URL of the MR introducing the feature flag (enter to skip):
?> https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38602

>> Open this URL and fill in the rest of the details:
https://gitlab.com/gitlab-org/gitlab/-/issues/new?issue%5Btitle%5D=%5BFeature+flag%5D+Rollout+of+%60test-flag%60&issuable_template=Feature+Flag+Roll+Out

>> URL of the rollout issue (enter to skip):
?> https://gitlab.com/gitlab-org/gitlab/-/issues/232533
create config/feature_flags/development/my_feature_flag.yml
---
name: my_feature_flag
introduced_by_url: https://gitlab.com/gitlab-org/gitlab/-/merge_requests/38602
rollout_issue_url: https://gitlab.com/gitlab-org/gitlab/-/issues/232533
group: group::memory
type: development
default_enabled: false

All newly-introduced feature flags must be disabled by default.

Features that are developed and merged behind a feature flag should not include a changelog entry. The entry should be added either in the merge request removing the feature flag or the merge request where the default value of the feature flag is set to enabled. If the feature contains any database migrations, it should include a changelog entry for the database changes.

Risk of a broken master (main) branch

List all the feature flags

To use ChatOps to output all the feature flags in an environment to Slack, you can use the run feature list command. For example:

/chatops run feature list --dev
/chatops run feature list --staging

Delete a feature flag

See cleaning up feature flags for more information about deleting feature flags.

Develop with a feature flag

There are two main ways of using Feature Flags in the GitLab codebase:

• Backend code (Rails)
• Frontend code (VueJS)

Backend

The feature flag interface is defined in lib/feature.rb. This interface provides a set of methods to check if the feature flag is enabled or disabled:

if Feature.enabled?(:my_feature_flag, project)
  # execute code if feature flag is enabled
else
  # execute code if feature flag is disabled
end

if Feature.disabled?(:my_feature_flag,