Feature flag API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Version history

Introduced in GitLab Premium 12.5.
Moved to GitLab Free in 13.5.

Use this API to interact with GitLab feature flags.

Prerequisites:

You must have at least the Developer role.

List feature flags for a project

Gets all feature flags of the requested project.

GET /projects/:id/feature_flags

Use the page and per_page pagination parameters to control the pagination of results.

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"
            }
          ],
          "user_list": null
        }
      ]
   },
   {
      "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"
            }
          ],
          "user_list": null
        }
      ]
   },
   {
      "name":"user_list",
      "description":"This feature is about user list",
      "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": "gitlabUserList",
          "parameters": {},
          "scopes": [
            {
              "id": 2,
              "environment_scope": "staging"
            }
          ],
          "user_list": {
            "id": 1,
            "iid": 1,
            "name": "My user list",
            "user_xids": "user1,user2,user3"
          }
        }
      ]
   }
]

Get a single feature flag

Gets a single feature flag.

GET /projects/:id/feature_flags/:feature_flag_name

Use the page and per_page pagination parameters to control the pagination of results.

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"
        }
      ],
      "user_list": null
    }
  ]
}

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	Deprecated The version of the feature flag. Must be `new_version_flag`. Omit 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.
`strategies`	array of strategy JSON objects	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 scope of the scope.
`strategies:user_list_id`	integer/string	no	The ID of the feature flag user list. If strategy is `gitlabUserList`.

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.
`name`	string	no	The new name of the feature flag.
`strategies`	array of strategy JSON objects	no	The feature flag strategies.
`strategies:id`	JSON	no	The feature flag strategy ID.
`strategies:name`	JSON	no	The strategy name.
`strategies:_destroy`	boolean	no	Delete the strategy when true.
`strategies:parameters`	JSON	no	The strategy parameters.
`strategies:scopes`	JSON	no	The scopes for the strategy.
`strategies:scopes:id`	JSON	no	The environment scope ID.
`strategies:scopes:environment_scope`	string	no	The environment scope of the scope.
`strategies:scopes:_destroy`	boolean	no	Delete the scope when true.
`strategies:user_list_id`	integer/string	no	The ID of the feature flag user list. If strategy is `gitlabUserList`.

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/feature_flags"
```0

Example response:

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/feature_flags"
```1

## Delete a feature flag

Deletes a feature flag.

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/feature_flags"
```2

| Attribute           | Type             | Required   | Description                                                                            |
| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------|
| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](rest/_index.md#namespaced-paths).       |
| `feature_flag_name` | string           | yes        | The name of the feature flag.                                                          |

```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/feature_flags"
```3