Feature flags API

DETAILS: Tier: Free, Premium, Ultimate Offering: SaaS, self-managed

Introduced in GitLab Premium 12.5.

Moved to GitLab Free in 13.5.

API for accessing resources of GitLab feature flags.

Users with at least the Developer role can access the 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"
            }
          ],
          "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

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. Supported in GitLab 13.3 and later.
`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. 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`	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 "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"