Skip to content

Document features deployed behind feature flags

GitLab uses feature flags to roll out the deployment of its own features.

The developer who changes the state of a feature flag is responsible for updating the documentation.

When to document features behind a feature flag

Before a feature flag is enabled for all customers in an environment (GitLab Self-Managed, GitLab.com, or GitLab Dedicated), the feature must be documented.

For all other features behind flags, the PM or EM for the group determines whether or not to document the feature.

Even when a flag is not documented alongside the feature, it is automatically documented on a central page.

How to add feature flag documentation

To document feature flags:

Offerings

When documenting the offerings, for features disabled on GitLab Self-Managed, don't list GitLab Dedicated as the feature's offering.

Add history text

When the state of a flag changes (for example, from disabled by default to enabled by default), add the change to the history.

Possible history entries are:

- [Introduced](https://issue-link) in GitLab X.X [with a flag](../../administration/feature_flags.md) named `flag_name`. Disabled by default.
- [Enabled on GitLab.com](https://issue-link) in GitLab X.X.
- [Enabled on GitLab Self-Managed and GitLab Dedicated](https://issue-link) in GitLab X.X.
- [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://issue-link) in GitLab X.X.
- [Generally available](https://issue-link) in GitLab X.Y. Feature flag `flag_name` removed.

These entries might not fit every scenario. You can adjust to suit your needs. For example, a flag might be enabled for a group, project, or subset of users only. In that case, you can use a history entry like:

- [Enabled on GitLab.com](https://issue-link) in GitLab X.X for a subset of users.

Add a flag note

Add this feature flag note at the start of the topic, just below the history.

The final sentence (not ready for production use) is optional.

{{</* alert type="flag" */>}}

The availability of this feature is controlled by a feature flag.
For more information, see the history.
This feature is available for testing, but not ready for production use.

{{</* /alert */>}}

This note renders on the GitLab documentation site as:

The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.

History examples

The following examples show the progression of a feature flag. Update the history with every change:

{{</* history */>}}

- [Introduced](https://issue-link) in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default.

{{</* /history */>}}

{{</* alert type="flag" */>}}

The availability of this feature is controlled by a feature flag. For more information, see the history.

{{</* /alert */>}}

When the feature is enabled by default on GitLab.com:

{{</* history */>}}

- [Introduced](https://issue-link) in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default.
- [Enabled on GitLab.com](https://issue-link) in GitLab 13.8.

{{</* /history */>}}

{{</* alert type="flag" */>}}

The availability of this feature is controlled by a feature flag. For more information, see the history.

{{</* /alert */>}}

When the feature is enabled by default for all offerings:

{{</* history */>}}

- [Introduced](https://issue-link) in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default.
- [Enabled on GitLab.com](https://issue-link) in GitLab 13.8.
- [Enabled on GitLab Self-Managed and GitLab Dedicated](https://issue-link) in GitLab 13.9.

{{</* /history */>}}

{{</* alert type="flag" */>}}

The availability of this feature is controlled by a feature flag. For more information, see the history.

{{</* /alert */>}}

When the flag is removed, add a Generally available entry. Ensure that you delete the FLAG note as well:

{{</* history */>}}

- [Introduced](https://issue-link) in GitLab 13.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Disabled by default.
- [Enabled on GitLab.com](https://issue-link) in GitLab 13.8.
- [Enabled on GitLab Self-Managed and GitLab Dedicated](https://issue-link) in GitLab 13.9.
- [Generally available](https://issue-link) in GitLab 14.0. Feature flag `forti_token_cloud` removed.

{{</* history */>}}

Simplify long history

The history can get long, but you can sometimes simplify or delete entries.

Combine entries if they happened in the same release:

  • Before:

    - [Introduced](https://issue-link) in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ci_include_rules`. Disabled by default.
- [Enabled on GitLab.com](https://issue-link) in GitLab 14.3.
- [Enabled on GitLab Self-Managed and GitLab Dedicated](https://issue-link) in GitLab 14.3.

  • After:

    - [Introduced](https://issue-link) in GitLab 14.2 [with a flag](../../administration/feature_flags.md) named `ci_include_rules`. Disabled by default.
- [Enabled on GitLab.com, GitLab Self-Managed, and GitLab Dedicated](https://issue-link) in GitLab 14.3.

If the feature flag is introduced and enabled in the same release, combine the entries:

- [Introduced](https://issue-link) in GitLab 17.7 [with a flag](../../administration/feature_flags.md) named `forti_token_cloud`. Enabled by default.

Delete Enabled on GitLab.com entries only when the feature is enabled by default for all offerings and the flag is removed:

  • Before:

    

- [Introduced](https://issue-link) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `ci_hooks_pre_get_sources_script`. Disabled by default.
- [Enabled on GitLab.com](https://issue-link) in GitLab 15.7.
- [Enabled on GitLab Self-Managed and GitLab Dedicated](https://issue-link) in GitLab 15.8.
- [Generally available](https://issue-link) in GitLab 15.9. Feature flag `ci_hooks_pre_get_sources_script` removed.

  • After:

    

- [Introduced](https://issue-link) in GitLab 15.6 [with a flag](../../administration/feature_flags.md) named `ci_hooks_pre_get_sources_script`. Disabled by default.
- [Enabled on GitLab Self-Managed and GitLab Dedicated](https://issue-link) in GitLab 15.8.
- [Generally available](https://issue-link) in GitLab 15.9. Feature flag `ci_hooks_pre_get_sources_script` removed.