Feature flags in the development of GitLab

The documentation below covers feature flags used by GitLab to deploy its own features, which is not the same as the feature flags offered as part of the product.

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.

All newly-introduced feature flags should be disabled by default.
This document is the subject of continued work as part of an epic to improve internal usage of Feature Flags. Raise any suggestions as new issues and attach them to the epic.

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:

# To disable it for the instance:

# 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

# Check if the feature flag is disabled

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

Introduced in GitLab 13.3.

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:

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

Field Required Description
name yes Name of the feature flag.
type yes Type of feature flag.
default_enabled yes The default state of the feature flag.
introduced_by_url no The URL to the merge request that introduced the feature flag.
rollout_issue_url no The URL to the Issue covering the feature flag rollout.
milestone no Milestone in which the feature was added.
group no The group that owns the feature flag.
All validations are skipped when running in RAILS_ENV=production.

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:

>> 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.

To create a feature flag that is only used in EE, add the --ee flag: bin/feature-flag --ee

Risk of a broken master (main) branch

Feature flags must be used in the MR that introduces them. Not doing so causes a broken master scenario due to the rspec:feature-flags job that only runs on the master 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:


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
  # execute code if feature flag is disabled

if Feature.disabled?(:my_feature_flag,