Use this API to manage the Flipper-based feature flags used in the development of GitLab itself.

These endpoints support only boolean and percentage-of-time gate values, and require administrator authorization.

List all feature flags

GET /api/v4/features

Lists all feature flags for the instance.

Responses

CodeDescriptionSchema
200OKAPIEntitiesFeature
401Unauthorized—
403Forbidden—

List all feature flag definitions

GET /api/v4/features/definitions

Lists all feature flag definitions.

Responses

CodeDescriptionSchema
200OKAPIEntitiesFeatureDefinition
401Unauthorized—
403Forbidden—

Create or update a feature flag

POST /api/v4/features/{name}

Creates or updates a feature flag value. If a feature with the given name doesn’t exist yet, the operation creates one. The value can be a boolean or an integer to indicate percentage of time.

Parameters

NameTypeDescription
name
Path, required
StringThe name of the feature flag

Request body (application/json)

PropertyTypeDescription
endpointStringA caller_id identifying a code path, for example GET /api/v4/projects/:id or ProjectsController#show. Use comma to separate multiple endpoint paths. Mutually exclusive with key
feature_groupStringA Feature group name. Mutually exclusive with key
forceBooleanSkip feature flag validation checks, such as a YAML definition
groupStringA GitLab group’s path, for example gitlab-org, or comma-separated multiple group paths. Mutually exclusive with key
keyStringpercentage_of_actors or percentage_of_time (default). Mutually exclusive with feature_group, user, group, namespace, project, organization, repository, runner, endpoint
namespaceStringA GitLab group or user namespace’s path, for example john-doe, or comma-separated multiple namespace paths. Introduced in GitLab 15.0. Mutually exclusive with key
organizationStringAn organization ID or path, for example 1 or default, or comma-separated multiple organization IDs or paths. Mutually exclusive with key
projectStringA projects path, for example gitlab-org/gitlab-foss, or comma-separated multiple project paths. Mutually exclusive with key
repositoryStringA repository path, for example gitlab-org/gitlab-test.git, gitlab-org/gitlab-test.wiki.git, snippets/21.git, to name a few. Use comma to separate multiple repository paths. Mutually exclusive with key
runnerStringA runner ID, or comma-separated list of runner IDs. Mutually exclusive with key
userStringA GitLab username or comma-separated multiple usernames. Mutually exclusive with key
value
Required
String or integertrue or false to enable/disable, or an integer for percentage of time

Responses

CodeDescriptionSchema
201CreatedAPIEntitiesFeature
400Bad request—
401Unauthorized—
403Forbidden—
404Not Found—

Delete a feature

DELETE /api/v4/features/{name}

Deletes a feature gate. Returns the same response if the feature gate does not exist.

Parameters

NameTypeDescription
name
Path, required
StringThe name of the feature flag

Responses

CodeDescriptionSchema
204Resource deleted—
400Bad Request—
404Not Found—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesFeature

PropertyTypeDescription
definitionAPIEntitiesFeatureDefinition—
gatesAPIEntitiesFeatureGate—
nameStringExample: experimental_feature
stateStringExample: off

APIEntitiesFeatureDefinition

PropertyTypeDescription
default_enabledBoolean—
feature_issue_urlString—
groupString—
intended_to_rollout_byString—
introduced_by_urlString—
log_state_changesBoolean—
milestoneString—
nameString—
rollout_issue_urlString—
typeString—

APIEntitiesFeatureGate

PropertyTypeDescription
keyStringExample: percentage_of_actors
valueIntegerExample: 34