gitlab-org--gitlab-foss/doc/administration/feature_flags.md

4.5 KiB

stage group info type description
none Development See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines reference GitLab administrator: enable and disable GitLab features deployed behind feature flags

Enable and disable GitLab features deployed behind feature flags (CORE ONLY)

GitLab adopted feature flags strategies to deploy features in an early stage of development so that they can be incrementally rolled out.

Before making them permanently available, features can be deployed behind flags for a number of reasons, such as:

  • To test the feature.
  • To get feedback from users and customers while in an early stage of the development of the feature.
  • To evaluate users adoption.
  • To evaluate how it impacts GitLab's performance.
  • To build it in smaller pieces throughout releases.

Features behind flags can be gradually rolled out, typically:

  1. The feature starts disabled by default.
  2. The feature becomes enabled by default.
  3. The feature flag is removed.

These features can be enabled and disabled to allow or disallow users to use them. It can be done by GitLab administrators with access to GitLab Rails console.

If you used a certain feature and identified a bug, a misbehavior, or an error, it's very important that you provide feedback to GitLab as soon as possible so we can improve or fix it while behind a flag. When you upgrade GitLab to an earlier version, the feature flag status may change.

CAUTION: Caution: Features deployed behind feature flags may not be ready for production use. However, disabling features behind flags that were deployed enabled by default may also present a risk. If they're enabled, we recommend you leave them as-is.

How to enable and disable features behind flags

Each feature has its own flag that should be used to enable and disable it. The documentation of each feature behind a flag includes a section informing the status of the flag and the command to enable or disable it.

Start the GitLab Rails console

The first thing you need to enable or disable a feature behind a flag is to start a session on GitLab Rails console.

For Omnibus installations:

sudo gitlab-rails console

For installations from the source:

sudo -u git -H bundle exec rails console -e production

For details, see starting a Rails console session.

Enable or disable the feature

Once the Rails console session has started, run the Feature.enable or Feature.disable commands accordingly. The specific flag can be found in the feature's documentation itself.

To enable a feature, run:

Feature.enable(:<feature flag>)

Example, to enable a fictional feature flag named my_awesome_feature:

Feature.enable(:my_awesome_feature)

To disable a feature, run:

Feature.disable(:<feature flag>)

Example, to disable a fictional feature flag named my_awesome_feature:

Feature.disable(:my_awesome_feature)

Some feature flags can be enabled or disabled on a per project basis:

Feature.enable(:<feature flag>, Project.find(<project id>))

For example, to enable the :product_analytics feature flag for project 1234:

Feature.enable(:product_analytics, Project.find(1234))

Feature.enable and Feature.disable always return nil, this is not an indication that the command failed:

irb(main):001:0> Feature.enable(:my_awesome_feature)
=> nil

To check if a flag is enabled or disabled you can use Feature.enabled? or Feature.disabled?. For example, for a fictional feature flag named my_awesome_feature:

Feature.enable(:my_awesome_feature)
=> nil
Feature.enabled?(:my_awesome_feature)
=> true
Feature.disabled?(:my_awesome_feature)
=> false

When the feature is ready, GitLab will remove the feature flag, the option for enabling and disabling it will no longer exist, and the feature will become available in all instances.