Feature flags API
- Tier: Free, Premium, Ultimate
- Offering: GitLab Self-Managed
This API is for managing Flipper-based feature flags used in development of GitLab.
All methods require administrator authorization.
Notice that the API only supports boolean and percentage-of-time gate values.
List all features
Get a list of all persisted features, with its gate values.
GET /features
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/features"
Example response:
[
{
"name": "experimental_feature",
"state": "off",
"gates": [
{
"key": "boolean",
"value": false
}
],
"definition": null
},
{
"name": "my_user_feature",
"state": "on",
"gates": [
{
"key": "percentage_of_actors",
"value": 34
}
],
"definition": {
"name": "my_user_feature",
"introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40880",
"rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/244905",
"group": "group::ci",
"type": "development",
"default_enabled": false
}
},
{
"name": "new_library",
"state": "on",
"gates": [
{
"key": "boolean",
"value": true
}
],
"definition": null
}
]
List all feature definitions
Get a list of all feature definitions.
GET /features/definitions
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/features/definitions"
Example response:
[
{
"name": "geo_pages_deployment_replication",
"introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68662",
"rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/337676",
"milestone": "14.3",
"log_state_changes": null,
"type": "development",
"group": "group::geo",
"default_enabled": true
}
]
Set or create a feature
Set a feature’s gate value. If a feature with the given name doesn’t exist yet, it’s created. The value can be a boolean, or an integer to indicate percentage of time.
Before you enable a feature still in development, you should understand the security and stability risks.
POST /features/:name
Attribute | Type | Required | Description |
---|---|---|---|
name | string | yes | Name of the feature to create or update |
value | integer/string | yes | true or false to enable/disable, or an integer for percentage of time |
key | string | no | percentage_of_actors or percentage_of_time (default) |
feature_group | string | no | A Feature group name |
user | string | no | A GitLab username or comma-separated multiple usernames |
group | string | no | A GitLab group’s path, for example gitlab-org , or comma-separated multiple group paths |
namespace | string | no | A GitLab group or user namespace’s path, for example john-doe , or comma-separated multiple namespace paths. Introduced in GitLab 15.0. |
project | string | no | A projects path, for example gitlab-org/gitlab-foss , or comma-separated multiple project paths |
repository | string | no | A repository path, for example gitlab-org/gitlab-test.git , gitlab-org/gitlab-test.wiki.git , , snippets/21.git , to name a few. Use comma to separate multiple repository paths |
force | boolean | no | Skip feature flag validation checks, such as a YAML definition |
You can enable or disable a feature for a feature_group
, a user
,
a group
, a namespace
, a project
, and a repository
in a single API call.
curl --data "value=30" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/features/new_library"
Example response:
{
"name": "new_library",
"state": "conditional",
"gates": [
{
"key": "boolean",
"value": false
},
{
"key": "percentage_of_time",
"value": 30
}
],
"definition": {
"name": "my_user_feature",
"introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40880",
"rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/244905",
"group": "group::ci",
"type": "development",
"default_enabled": false
}
}
Set percentage of actors rollout
Rollout to percentage of actors.
POST https://gitlab.example.com/api/v4/features/my_user_feature?private_token=<your_access_token>
Content-Type: application/x-www-form-urlencoded
value=42&key=percentage_of_actors&
Example response:
{
"name": "my_user_feature",
"state": "conditional",
"gates": [
{
"key": "boolean",
"value": false
},
{
"key": "percentage_of_actors",
"value": 42
}
],
"definition": {
"name": "my_user_feature",
"introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40880",
"rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/244905",
"group": "group::ci",
"type": "development",
"default_enabled": false
}
}
Rolls out the my_user_feature
to 42%
of actors.
Delete a feature
Removes a feature gate. Response is equal when the gate exists, or doesn’t.
DELETE /features/:name
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support