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

REST API 废弃

你应该定期审查以下废弃内容并做出相应更改。这些废弃通常意味着 API 功能的改进，建议使用新字段或端点来实现相关功能。

尽管某些废弃提到了 v5 REST API，但实际上并没有活跃的 v5 REST API 开发。 GitLab 不会在 REST API v4 中进行这些更改，因为我们承诺遵循语义化版本控制来管理我们的 REST API [_index.md#versioning-and-deprecations]。

geo_nodes API 端点

破坏性变更。相关 issue。

geo_nodes API 端点 已被废弃，由 geo_sites 替代。 这是关于如何引用 Geo 部署全局变更的一部分。 整个应用中，“nodes” 已重命名为 “sites”。两个端点的功能保持不变。

merged_by API 字段

破坏性变更。相关 issue。

合并请求 API 中的 merged_by 字段已被废弃， 取而代之的是 merge_user 字段，该字段能更准确地识别在执行操作（如设置为自动合并、添加到合并队列）时（而不仅仅是简单合并）谁合并了合并请求。

建议 API 用户使用新的 merge_user 字段。merged_by 字段将在 GitLab REST API v5 中被移除。

merge_status API 字段

破坏性变更。相关 issue。

合并请求 API 中的 merge_status 字段已被废弃， 取而代之的是 detailed_merge_status 字段，该字段能更准确地识别合并请求可能处于的所有潜在状态。 建议 API 用户使用新的 detailed_merge_status 字段。merge_status 字段将在 GitLab REST API v5 中被移除。

User API 中 private_profile 属性的 Null 值

破坏性变更。相关 issue。

通过 API 创建和更新用户时，null 曾是 private_profile 属性的有效值，该值会在内部被转换为默认值。 在 GitLab REST API v5 中，null 将不再是此参数的有效值，使用时将返回 400 错误。 此变更后，唯一的有效值将是 true 和 false。

单个合并请求变更 API 端点

破坏性变更。相关 issue。

获取单个合并请求的变更的端点已被废弃， 取而代之的是列出合并请求差异端点。 建议 API 用户切换到新的差异端点。

单个合并请求变更端点将在 GitLab REST API v5 中被移除。

托管许可证 API 端点

破坏性变更。相关 issue。

获取给定项目所有托管许可证的端点已被废弃，取而代之的是 许可证审批策略功能。

希望继续基于检测到的许可证强制执行审批的用户，建议创建新的许可证审批策略。

托管许可证端点将在 GitLab REST API v5 中被移除。

合并请求审批 API 中的审批人和审批人组字段

破坏性变更。相关 issue。

获取项目审批配置的端点返回 approvers 和 approval_groups 的空数组。 这些字段已被废弃，取而代之的是获取合并请求列出所有审批规则的端点。 建议 API 用户切换到此端点。

这些字段将在 获取配置 端点中于 GitLab REST API v5 中被移除。

Runner 使用 active 被 paused 替代

破坏性变更。相关 issue。

GitLab Runner GraphQL API 端点中的 active 标识符将在 GitLab 16.0 中重命名为 paused。

  • 在 REST API v4 中，你可以使用 paused 属性替代 active
  • 在 REST API v5 中，此变更将影响接受或返回 active 属性的端点，例如：
    • GET /runners
    • GET /runners/all
    • GET /runners/:id / PUT /runners/:id
    • PUT --form "active=false" /runners/:runner_id
    • GET /projects/:id/runners / POST /projects/:id/runners
    • GET /groups/:id/runners

GitLab Runner 16.0 版本将在注册 Runner 时开始使用 paused 属性。

Runner 状态将不再返回 paused

破坏性变更。相关 issue。

在未来的 REST API v5 中，GitLab Runner 的端点将不再返回 paused 或 active。

Runner 的状态将仅与 Runner 的联系状态相关，例如： online（在线）、offline（离线）或 not_connected（未连接）。状态 paused 或 active 将不再出现。

当检查 Runner 是否为 paused 时，建议 API 用户检查布尔属性 paused 是否为 true。 当检查 Runner 是否为 active 时，检查 paused 是否为 false。

Runner 将不再返回 ip_address

破坏性变更。相关 issue。

在 GitLab 17.0 中，Runners API 将为 Runner 返回空字符串 "" 而不是 ip_address。 在 REST API v5 中，该字段将被移除。

default_branch_protection API 字段

破坏性变更。相关 issue。

default_branch_protection 字段在 GitLab 17.0 中对以下 API 被废弃：

你应该使用 default_branch_protection_defaults 字段，它提供了对默认分支保护更细粒度的控制。

default_branch_protection 字段将在 GitLab REST API v5 中被移除。

require_password_to_approve API 字段

require_password_to_approve 字段在 GitLab 16.9 中被废弃。请使用 require_reauthentication_to_approve 字段替代。 如果你同时为两个字段提供值，require_reauthentication_to_approve 字段将优先。

require_password_to_approve 字段将在 GitLab REST API v5 中被移除。

使用 Projects API 端点进行拉取镜像配置

破坏性变更。相关 issue。

在 GitLab 17.6 中，使用 Projects API 进行拉取镜像配置 已被废弃。 它被新的配置和端点 projects/:id/mirror/pull 替代。

使用 Projects API 的旧配置将在 GitLab REST API v5 中被移除。

Projects API 端点中的 restrict_user_defined_variables 参数

在 GitLab 17.7 中，Projects API 中的 restrict_user_defined_variables 参数 已被废弃， 建议仅使用 ci_pipeline_variables_minimum_override_role。

要匹配 restrict_user_defined_variables: false 的相同行为，请将 ci_pipeline_variables_minimum_override_role 设置为 developer。