Feature Flags API (CORE)

Introduced in GitLab Premium 12.5.

Moved to GitLab Starter in 13.4.

Moved to GitLab Core in 13.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. 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"