Skip to content

GitLab

Feature Flags API (PREMIUM)

Introduced in GitLab Premium 12.5.

NOTE: Note: This API is behind a feature flag. If this flag is not enabled in your environment, you can use the legacy feature flags API.

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.
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"