Help us learn about your current experience with the documentation. Take the survey.

功能开关 API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab Self-Managed

此 API 用于管理 GitLab 开发中使用的基于 Flipper 的功能开关。

所有方法都需要管理员权限。

请注意，此 API 仅支持布尔值 (boolean) 和按时间百分比 (percentage-of-time) 的门控值。

获取所有功能列表

获取所有已持久化功能的列表及其门控值。

GET /features
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/features"

示例响应：

[
  {
    "name": "experimental_feature",
    "state": "off",
    "gates": [
      {
        "key": "boolean",
        "value": false
      }
    ],
    "definition": null
  },
  {
    "name": "my_user_feature",
    "state": "on",
    "gates": [
      {
        "key": "percentage_of_actors",
        "value": 34
      }
    ],
    "definition": {
      "name": "my_user_feature",
      "introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40880",
      "rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/244905",
      "group": "group::ci",
      "type": "development",
      "default_enabled": false
    }
  },
  {
    "name": "new_library",
    "state": "on",
    "gates": [
      {
        "key": "boolean",
        "value": true
      }
    ],
    "definition": null
  }
]

获取所有功能定义列表

获取所有功能定义的列表。

GET /features/definitions
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/features/definitions"

示例响应：

[
  {
    "name": "geo_pages_deployment_replication",
    "introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68662",
    "rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/337676",
    "milestone": "14.3",
    "log_state_changes": null,
    "type": "development",
    "group": "group::geo",
    "default_enabled": true
  }
]

设置或创建功能

设置功能的门控值。如果指定名称的功能尚不存在，则会创建它。该值可以是布尔值 (boolean)，也可以是表示时间百分比的整数。

在启用仍在开发中的功能之前，您应该了解其安全性和稳定性风险。

POST /features/:name
属性 类型 必需 描述
name string 是 要创建或更新的功能名称
value integer/string 是 true 或 false 用于启用/禁用，或表示时间百分比的整数
key string 否 percentage_of_actors 或 percentage_of_time（默认）
feature_group string 否 功能组名称
user string 否 GitLab 用户名或逗号分隔的多个用户名
group string 否 GitLab 组的路径，例如 gitlab-org，或逗号分隔的多个组路径
namespace string 否 GitLab 组或用户命名空间的路径，例如 john-doe，或逗号分隔的多个命名空间路径。在 GitLab 15.0 中引入。
project string 否 项目的路径，例如 gitlab-org/gitlab-foss，或逗号分隔的多个项目路径
repository string 否 仓库的路径，例如 gitlab-org/gitlab-test.git、gitlab-org/gitlab-test.wiki.git、snippets/21.git 等。使用逗号分隔多个仓库路径
force boolean 否 跳过功能开关的验证检查，例如 YAML 定义

您可以在单个 API 调用中为 feature_group、user、group、namespace、project 和 repository 启用或禁用功能。

curl --request POST \
  --data "value=30" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/features/new_library"

示例响应：

{
  "name": "new_library",
  "state": "conditional",
  "gates": [
    {
      "key": "boolean",
      "value": false
    },
    {
      "key": "percentage_of_time",
      "value": 30
    }
  ],
  "definition": {
    "name": "my_user_feature",
    "introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40880",
    "rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/244905",
    "group": "group::ci",
    "type": "development",
    "default_enabled": false
  }
}

设置按用户百分比发布

按用户百分比发布。

POST https://gitlab.example.com/api/v4/features/my_user_feature?private_token=<your_access_token>
Content-Type: application/x-www-form-urlencoded
value=42&key=percentage_of_actors&

示例响应：

{
  "name": "my_user_feature",
  "state": "conditional",
  "gates": [
    {
      "key": "boolean",
      "value": false
    },
    {
      "key": "percentage_of_actors",
      "value": 42
    }
  ],
  "definition": {
    "name": "my_user_feature",
    "introduced_by_url": "https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40880",
    "rollout_issue_url": "https://gitlab.com/gitlab-org/gitlab/-/issues/244905",
    "group": "group::ci",
    "type": "development",
    "default_enabled": false
  }
}

将 my_user_feature 发布给 42% 的用户。

删除功能

移除功能的门控。无论门控是否存在，移除操作都会返回相同的响应。

DELETE /features/:name