- When to use feature flags
- Feature flags in GitLab development
- Risk of a broken main branch
- Types of feature flags
- Feature flag definition and validation
- Create a new feature flag
- List all the feature flags
- Delete a feature flag
- Develop with a feature flag
- Changelog
- Feature flags in 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:
- 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.
- 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.
- 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.
- 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
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. |
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:
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.
--ee
flag: bin/feature-flag --ee
Risk of a broken master (main) branch
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:
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,