Feature Flags

Moved from GitLab Premium to GitLab Free in 13.5.

With Feature Flags, you can deploy your application’s new features to production in smaller batches. You can toggle a feature on and off to subsets of users, helping you achieve Continuous Delivery. Feature flags help reduce risk, allowing you to do controlled testing, and separate feature delivery from customer launch.

For an example of feature flags in action, see GitLab for Deploys, Feature Flags, and Error Tracking.

note
The Feature Flags GitLab offer as a feature (described in this document) is not the same method used for the development of GitLab.

How it works

GitLab uses Unleash, a feature toggle service.

By enabling or disabling a flag in GitLab, your application can determine which features to enable or disable.

You can create feature flags in GitLab and use the API from your application to get the list of feature flags and their statuses. The application must be configured to communicate with GitLab, so it’s up to developers to use a compatible client library and integrate the feature flags in your app.

Create a feature flag

To create and enable a feature flag:

  1. On the top bar, select Menu > Projects and find your project.
  2. On the left sidebar, select Deployments > Feature Flags.
  3. Select New feature flag.
  4. Enter a name that starts with a letter and contains only lowercase letters, digits, underscores (_), or dashes (-), and does not end with a dash (-) or underscore (_).
  5. Optional. Enter a description (255 characters maximum).
  6. Add Feature Flag Strategies to define how the flag should be applied. For each strategy, include the Type (defaults to All users) and Environments (defaults to all environments).
  7. Select Create feature flag.

To change these settings, select Edit ( ). next to any feature flag in the list.

Maximum number of feature flags

Introduced in GitLab 13.5.

The maximum number of feature flags per project on self-managed GitLab instances is 200. For GitLab SaaS, the maximum number is determined by tier:

Tier Feature flags per project (SaaS) Feature flags per project (self-managed)
Free 50 200
Premium 150 200
Ultimate 200 200

Feature flag strategies

Version history
  • Introduced in GitLab 13.0.
  • It was deployed behind a feature flag, disabled by default.
  • It became enabled by default in GitLab 13.2.
  • It’s recommended for production use.
  • It’s enabled on GitLab.com.

You can apply a feature flag strategy across multiple environments, without defining the strategy multiple times.

GitLab Feature Flags use Unleash as the feature flag engine. In Unleash, there are strategies for granular feature flag controls. GitLab Feature Flags can have multiple strategies, and the supported strategies are:

Strategies can be added to feature flags when creating a feature flag, or by editing an existing feature flag after creation by navigating to Deployments > Feature Flags and selecting Edit ( ).

All users

Enables the feature for all users. It uses the Standard (default) Unleash activation strategy.

Percent Rollout

Introduced in GitLab 13.5.

Enables the feature for a percentage of page views, with configurable consistency of behavior. This consistency is also known as stickiness. It uses the Gradual Rollout (flexibleRollout) Unleash activation strategy.

You can configure the consistency to be based on:

  • User IDs: Each user ID has a consistent behavior, ignoring session IDs.
  • Session IDs: Each session ID has a consistent behavior, ignoring user IDs.
  • Random: Consistent behavior is not guaranteed. The feature is enabled for the selected percentage of page views randomly. User IDs and session IDs are ignored.
  • Available ID: Consistent behavior is attempted based on the status of the user:
    • If the user is logged in, make behavior consistent based on user ID.
    • If the user is anonymous, make the behavior consistent based on the session ID.
    • If there is no user ID or session ID, then the feature is enabled for the selected percentage of page view randomly.

For example, set a value of 15% based on Available ID to enable the feature for 15% of page views. For authenticated users this is based on their user ID. For anonymous users with a session ID it would be based on their session ID instead as they do not have a user ID. Then if no session ID is provided, it falls back to random.

The rollout percentage can be from 0% to 100%.

Selecting a consistency based on User IDs functions the same as the percent of Users rollout.

caution
Selecting Random provides inconsistent application behavior for individual users.

Percent of Users

Enables the feature for a percentage of authenticated users. It uses the Unleash activation strategy gradualRolloutUserId.

For example, set a value of 15% to enable the feature for 15% of authenticated users.

The rollout percentage can be from 0% to 100%.

Stickiness (consistent application behavior for the same user) is guaranteed for logged-in users, but not anonymous users.

Note that percent rollout with a consistency based on User IDs has the same behavior. We recommend using percent rollout because it’s more flexible than percent of users

caution
If the percent of users strategy is selected, then the Unleash client must be given a user ID for the feature to be enabled. See the Ruby example below.

User IDs

Version history

Enables the feature for a list of target users. It is implemented using the Unleash UserIDs (userWithId) activation strategy.

Enter user IDs as a comma-separated list of values (for example, user@example.com, user2@example.com, or username1,username2,username3, and so on). Note that user IDs are identifiers for your application users. They do not need to be GitLab users.

caution
The Unleash client must be given a user ID for the feature to be enabled for target users. See the Ruby example below.

User List

Introduced in GitLab 13.1.

Enables the feature for lists of users created in the Feature Flags UI, or with the Feature Flag User List API. Similar to User IDs, it uses the Unleash UsersIDs (userWithId) activation strategy.

It’s not possible to disable a feature for members of a user list, but you can achieve the same effect by enabling a feature for a user list that doesn’t contain the excluded users.

For example:

  • Full-user-list = User1A, User1B, User2A, User2B, User3A, User3B, ...
  • Full-user-list-excluding-B-users = User1A, User2A, User3A, ...

Create a user list

Version history

To create a user list:

  1. On the top bar, select Menu > Projects and find your project.
  2. On the left sidebar, select Deployments > Feature Flags.
  3. Select View user lists
  4. Select New user list.
  5. Enter a name for the list.
  6. Select Create.

You can view a list’s User IDs by selecting Edit ( ) next to it. When viewing a list, you can rename it by selecting Edit ( ).

Add users to a user list

Introduced in GitLab 13.3.

To add users to a user list:

  1. On the top bar, select Menu > Projects and find your project.
  2. On the left sidebar, select Deployments > Feature Flags.
  3. Select Edit ( ) next to the list you want to add users to.
  4. Select Add Users.
  5. Enter the user IDs as a comma-separated list of values. For example, user@example.com, user2@example.com, or username1,username2,username3, and so on.
  6. Select Add.

Remove users from a user list

Introduced in GitLab 13.3.

To remove users from a user list:

  1. On the top bar, select Menu > Projects and find your project.
  2. On the left sidebar, select Deployments > Feature Flags.
  3. Select Edit ( ) next to the list you want to change.
  4. Select Remove ( ) next to the ID you want to remove.

Search for Code References

Introduced in GitLab 14.4.

Search your project and find any references of a feature flag in your code so that you can clean it up when it’s time to remove the feature flag.

To search for code references of a feature flag:

  1. On the top bar, select Menu > Projects and find your project.
  2. On the left sidebar, select Deployments > Feature Flags.
  3. Edit the feature flag you want to remove.
  4. Select More actions ( ).
  5. Select Search code references.

Disable a feature flag for a specific environment

In GitLab 13.0 and earlier, to disable a feature flag for a specific environment:

  1. On the top bar, select Menu > Projects and find your project.
  2. On the left sidebar, select Deployments > Feature Flags.
  3. For the feature flag you want to disable, select Edit ( ).
  4. To disable the flag:

    • In GitLab 13.0 and earlier: Slide the Status toggle for the environment. Or, to delete the environment spec, on the right, select Remove (X).
    • In GitLab 13.1 and later: For each strategy it applies to, under Environments, delete the environment.
  5. Select Save changes.

Disable a feature flag for all environments

To disable a feature flag for all environments:

  1. On the top bar, select Menu > Projects and find your project.
  2. On the left sidebar, select Deployments > Feature Flags.
  3. For the feature flag you want to disable, slide the Status toggle to Disabled.

The feature flag is displayed on the Disabled tab.

Integrate feature flags with your application

To use feature flags with your application, get access credentials from GitLab. Then prepare your application with a client library.

Get access credentials