Feature Flags API
Version history
- Introduced in GitLab Premium 12.5.
- Moved to GitLab Free in 13.5.
API for accessing resources of GitLab Feature Flags.
Users with Developer or higher permissions can access Feature Flag API.
Feature Flags pagination
By default, GET
requests return 20 results at a time because the API results
are paginated.
List feature flags for a project
Gets all feature flags of the requested project.
GET /projects/:id/feature_flags
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the project. |
scope
| string | no | The condition of feature flags, one of: enabled , disabled .
|
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/feature_flags"
Example response:
[
{
"name":"merge_train",
"description":"This feature is about merge train",
"active": true,
"version": "new_version_flag",
"created_at":"2019-11-04T08:13:51.423Z",
"updated_at":"2019-11-04T08:13:51.423Z",
"scopes":[],
"strategies": [
{
"id": 1,
"name": "userWithId",
"parameters": {
"userIds": "user1"
},
"scopes": [
{
"id": 1,
"environment_scope": "production"
}
]
}
]
},
{
"name":"new_live_trace",
"description":"This is a new live trace feature",
"active": true,
"version": "new_version_flag",
"created_at":"2019-11-04T08:13:10.507Z",
"updated_at":"2019-11-04T08:13:10.507Z",
"scopes":[],
"strategies": [
{
"id": 2,
"name": "default",
"parameters": {},
"scopes": [
{
"id": 2,
"environment_scope": "staging"
}
]
}
]
}
]
Get a single feature flag
Gets a single feature flag.
GET /projects/:id/feature_flags/:feature_flag_name
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the project. |
feature_flag_name
| string | yes | The name of the feature flag. |
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature"
Example response:
{
"name": "awesome_feature",
"description": null,
"active": true,
"version": "new_version_flag",
"created_at": "2020-05-13T19:56:33.119Z",
"updated_at": "2020-05-13T19:56:33.119Z",
"scopes": [],
"strategies": [
{
"id": 36,
"name": "default",
"parameters": {},
"scopes": [
{
"id": 37,
"environment_scope": "production"
}
]
}
]
}
Create a feature flag
Creates a new feature flag.
POST /projects/:id/feature_flags
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the project. |
name
| string | yes | The name of the feature flag. |
version
| string | yes | The version of the feature flag. Must be new_version_flag . Omit or set to legacy_flag to create a Legacy Feature Flag.
|
description
| string | no | The description of the feature flag. |
active
| boolean | no | The active state of the flag. Defaults to true. Supported in GitLab 13.3 and later. |
strategies
| JSON | no | The feature flag strategies. |
strategies:name
| JSON | no | The strategy name. Can be default , gradualRolloutUserId , userWithId , or gitlabUserList . In GitLab 13.5 and later, can be flexibleRollout .
|
strategies:parameters
| JSON | no | The strategy parameters. |
strategies:scopes
| JSON | no | The scopes for the strategy. |
strategies:scopes:environment_scope
| string | no | The environment spec for the scope. |
curl "https://gitlab.example.com/api/v4/projects/1/feature_flags" \
--header "PRIVATE-TOKEN: <your_access_token>" \
--header "Content-type: application/json" \
--data @- << EOF
{
"name": "awesome_feature",
"version": "new_version_flag",
"strategies": [{ "name": "default", "parameters": {}, "scopes": [{ "environment_scope": "production" }] }]
}
EOF
Example response:
{
"name": "awesome_feature",
"description": null,
"active": true,
"version": "new_version_flag",
"created_at": "2020-05-13T19:56:33.119Z",
"updated_at": "2020-05-13T19:56:33.119Z",
"scopes": [],
"strategies": [
{
"id": 36,
"name": "default",
"parameters": {},
"scopes": [
{
"id": 37,
"environment_scope": "production"
}
]
}
]
}
Update a feature flag
Updates a feature flag.
PUT /projects/:id/feature_flags/:feature_flag_name
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the project. |
feature_flag_name
| string | yes | The current name of the feature flag. |
description
| string | no | The description of the feature flag. |
active
| boolean | no | The active state of the flag. Supported in GitLab 13.3 and later. |
name
| string | no | The new name of the feature flag. Supported in GitLab 13.3 and later. |
strategies
| JSON | no | The feature flag strategies. |
strategies:id
| JSON | no | The feature flag strategy ID. |
strategies:name
| JSON | no | The strategy name. |
strategies:parameters
| JSON | no | The strategy parameters. |
strategies:scopes
| JSON | no | The scopes for the strategy. |
strategies:scopes:id
| JSON | no | The scopes ID. |
strategies:scopes:environment_scope
| string | no | The environment spec for the scope. |
curl "https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature" \
--header "PRIVATE-TOKEN: <your_access_token>" \
--header "Content-type: application/json" \
--data @- << EOF
{
"strategies": [{ "name": "gradualRolloutUserId", "parameters": { "groupId": "default", "percentage": "25" }, "scopes": [{ "environment_scope": "staging" }] }]
}
EOF
Example response:
{
"name": "awesome_feature",
"description": null,
"active": true,
"version": "new_version_flag",
"created_at": "2020-05-13T20:10:32.891Z",
"updated_at": "2020-05-13T20:10:32.891Z",
"scopes": [],
"strategies": [
{
"id": 38,
"name": "gradualRolloutUserId",
"parameters": {
"groupId": "default",
"percentage": "25"
},
"scopes": [
{
"id": 40,
"environment_scope": "staging"
}
]
},
{
"id": 37,
"name": "default",
"parameters": {},
"scopes": [
{
"id": 39,
"environment_scope": "production"
}
]
}
]
}
Delete a feature flag
Deletes a feature flag.
DELETE /projects/:id/feature_flags/:feature_flag_name
Attribute | Type | Required | Description |
---|---|---|---|
id
| integer/string | yes | The ID or URL-encoded path of the project. |
feature_flag_name
| string | yes | The name of the feature flag. |
curl --header "PRIVATE-TOKEN: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature"