REST API deprecations and removals

The following API changes will occur between REST API v4 and v5. No date is set for this upgrade.

For more information, see issue 216456 and issue 387485.

geo_nodes API endpoints

Breaking change. Related issue.

The geo_nodes API endpoints are deprecated and are replaced by geo_sites. It is a part of the global change on how to refer to Geo deployments. Nodes are renamed to sites across the application. The functionality of both endpoints remains the same.

merged_by API field

Breaking change. Related issue.

The merged_by field in the merge request API has been deprecated in favor of the merge_user field which more correctly identifies who merged a merge request when performing actions (set to auto-merge, add to merge train) other than a simple merge.

API users are encouraged to use the new merge_user field instead. The merged_by field will be removed in v5 of the GitLab REST API.

merge_status API field

Breaking change. Related issue.

The merge_status field in the merge request API has been deprecated in favor of the detailed_merge_status field which more correctly identifies all of the potential statuses that a merge request can be in. API users are encouraged to use the new detailed_merge_status field instead. The merge_status field will be removed in v5 of the GitLab REST API.

Null value for private_profile attribute in User API

Breaking change. Related issue.

When creating and updating users through the API, null was a valid value for the private_profile attribute, which would internally be converted to the default value. In v5 of the GitLab REST API, null will no longer be a valid value for this parameter, and the response will be a 400 if used. After this change, the only valid values will be true and false.

Single merge request changes API endpoint

Breaking change. Related issue.

The endpoint to get changes from a single merge request has been deprecated in favor the list merge request diffs endpoint. API users are encouraged to switch to the new diffs endpoint instead.

The changes from a single merge request endpoint will be removed in v5 of the GitLab REST API.

Managed Licenses API endpoint

Breaking change. Related issue.

The endpoint to get all managed licenses for a given project has been deprecated in favor the License Approval policy feature.

Users who wish to continue to enforce approvals based on detected licenses are encouraged to create a new License Approval policy instead.

The managed licenses endpoint will be removed in v5 of the GitLab REST API.

Approvers and Approver Group fields in Merge Request Approval API

Breaking change. Related issue.

The endpoint to get the configuration of approvals for a project returns empty arrays for approvers and approval_groups. These fields were deprecated in favor of the endpoint to get project-level rules for a merge request. API users are encouraged to switch to this endpoint instead.

These fields will be removed from the get configuration endpoint in v5 of the GitLab REST API.

Runner usage of active replaced by paused

Breaking change. Related issue.

Occurrences of the active identifier in the GitLab Runner GraphQL API endpoints will be renamed to paused in GitLab 16.0.

  • In v4 of the REST API, you can use the paused property in place of active
  • In v5 of the REST API, this change will affect endpoints taking or returning active property, such as:
    • 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

The 16.0 release of GitLab Runner will start using the paused property when registering runners.

Runner status will not return paused

Breaking change. Related issue.

In a future v5 of the REST API, the endpoints for GitLab Runner will not return paused or active.

A runner’s status will only relate to runner contact status, such as: online, offline, or not_connected. Status paused or active will no longer appear.

When checking if a runner is paused, API users are advised to check the boolean attribute paused to be true instead. When checking if a runner is active, check if paused is false.

Runner will not return ip_address

Breaking change. Related issue.

In GitLab 17.0, the Runners API will return "" in place of ip_address for runners. In v5 of the REST API, the field will be removed.

Runner will not return version, revision, platform, or architecture

Breaking change. Related issue.

In GitLab 18.0, the Runners API will return "" in place of version, revision, platform, and architecture for runners. In v5 of the REST API, the fields will be removed.

default_branch_protection API field

Breaking change. Related issue.

The default_branch_protection field is deprecated in GitLab 17.0 for the following APIs:

You should use the default_branch_protection_defaults field instead, which provides more finer grained control over the default branch protections.

The default_branch_protection field will be removed in v5 of the GitLab REST API.

require_password_to_approve API field

The require_password_to_approve was deprecated in GitLab 16.9. Use the require_reauthentication_to_approve field instead. If you supply values to both fields, the require_reauthentication_to_approve field takes precedence.

The require_password_to_approve field will be removed in v5 of the GitLab REST API.

Pull mirroring configuration with Project API

Breaking change. Related issue.

In GitLab 17.6, the pull mirroring configuration with the Projects API is deprecated. It is replaced by a new configuration and endpoint, projects/:id/mirror/pull.

The previous configuration using the Projects API will be removed in v5 of the GitLab REST API.