Merge Trains API

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Use this API to interact with merge trains.

Prerequisites:

  • You must have at least the Developer role.

List Merge Trains for a project

Get all Merge Trains of the requested project:

GET /projects/:id/merge_trains
GET /projects/:id/merge_trains?scope=complete

Use the page and per_page pagination parameters to control the pagination of results.

AttributeTypeRequiredDescription
idinteger/stringYesThe ID or URL-encoded path of the project.
scopestringNoReturn Merge Trains filtered by the given scope. Available scopes are active (to be merged) and complete (have been merged).
sortstringNoReturn Merge Trains sorted in asc or desc order. Default: desc.
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/merge_trains"

Returns:

  • 403: Forbidden if Merge Trains are not available for the project
  • 404: Not Found if the user is not a member of a private project

Example response:

[
  {
    "id": 110,
    "merge_request": {
      "id": 126,
      "iid": 59,
      "project_id": 20,
      "title": "Test MR 1580978354",
      "description": "",
      "state": "merged",
      "created_at": "2020-02-06T08:39:14.883Z",
      "updated_at": "2020-02-06T08:40:57.038Z",
      "web_url": "http://local.gitlab.test:8181/root/merge-train-race-condition/-/merge_requests/59"
    },
    "user": {
      "id": 1,
      "name": "Administrator",
      "username": "root",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
      "web_url": "http://local.gitlab.test:8181/root"
    },
    "pipeline": {
      "id": 246,
      "sha": "bcc17a8ffd51be1afe45605e714085df28b80b13",
      "ref": "refs/merge-requests/59/train",
      "status": "success",
      "created_at": "2020-02-06T08:40:42.410Z",
      "updated_at": "2020-02-06T08:40:46.912Z",
      "web_url": "http://local.gitlab.test:8181/root/merge-train-race-condition/pipelines/246"
    },
    "created_at": "2020-02-06T08:39:47.217Z",
    "updated_at": "2020-02-06T08:40:57.720Z",
    "target_branch": "feature-1580973432",
    "status": "merged",
    "merged_at": "2020-02-06T08:40:57.719Z",
    "duration": 70
  }
]

List merge requests in a merge train

Get all merge requests added to a merge train for the requested target branch.

GET /projects/:id/merge_trains/:target_branch

Use the page and per_page pagination parameters to control the pagination of results.

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringYesThe ID or URL-encoded path of the project.
target_branchstringYesThe target branch of the merge train.
scopestringNoReturn Merge Trains filtered by the given scope. Available scopes are active (to be merged) and complete (have been merged).
sortstringNoReturn Merge Trains sorted in asc or desc order. Default: desc.

Example request:

curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/597/merge_trains/main"

Returns:

  • 403: Forbidden if Merge Trains are not available for the project
  • 404: Not Found if the user is not a member of a private project

Example response:

[
  {
    "id": 267,
    "merge_request": {
      "id": 273,
      "iid": 1,
      "project_id": 597,
      "title": "My title 9",
      "description": null,
      "state": "opened",
      "created_at": "2022-10-31T19:06:05.725Z",
      "updated_at": "2022-10-31T19:06:05.725Z",
      "web_url": "http://localhost/namespace18/project21/-/merge_requests/1"
    },
    "user": {
      "id": 933,
      "username": "user12",
      "name": "Sidney Jones31",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/6c8365de387cb3db10ecc7b1880203c4?s=80\u0026d=identicon",
      "web_url": "http://localhost/user12"
    },
    "pipeline": {
      "id": 273,
      "iid": 1,
      "project_id": 598,
      "sha": "b83d6e391c22777fca1ed3012fce84f633d7fed0",
      "ref": "main",
      "status": "pending",
      "source": "push",
      "created_at": "2022-10-31T19:06:06.231Z",
      "updated_at": "2022-10-31T19:06:06.231Z",
      "web_url": "http://localhost/namespace19/project22/-/pipelines/273"
    },
    "created_at": "2022-10-31T19:06:06.237Z",
    "updated_at":"2022-10-31T19:06:06.237Z",
    "target_branch":"main",
    "status":"idle",
    "merged_at":null,
    "duration":null
  }
]

Get the status of a merge request on a merge train

Get merge train information for the requested merge request.

GET /projects/:id/merge_trains/merge_requests/:merge_request_iid

Use the page and per_page pagination parameters to control the pagination of results.

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringYesThe ID or URL-encoded path of the project.
merge_request_iidintegerYesThe internal ID of the merge request.

Example request:

curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/597/merge_trains/merge_requests/1"

Returns:

  • 403: Forbidden if Merge Trains are not available for the project
  • 404: Not Found if the user is not a member of a private project

Example response:

{
  "id": 267,
  "merge_request": {
    "id": 273,
    "iid": 1,
    "project_id": 597,
    "title": "My title 9",
    "description": null,
    "state": "opened",
    "created_at": "2022-10-31T19:06:05.725Z",
    "updated_at": "2022-10-31T19:06:05.725Z",
    "web_url": "http://localhost/namespace18/project21/-/merge_requests/1"
  },
  "user": {
    "id": 933,
    "username": "user12",
    "name": "Sidney Jones31",
    "state": "active",
    "avatar_url": "https://www.gravatar.com/avatar/6c8365de387cb3db10ecc7b1880203c4?s=80\u0026d=identicon",
    "web_url": "http://localhost/user12"
  },
  "pipeline": {
    "id": 273,
    "iid": 1,
    "project_id": 598,
    "sha": "b83d6e391c22777fca1ed3012fce84f633d7fed0",
    "ref": "main",
    "status": "pending",
    "source": "push",
    "created_at": "2022-10-31T19:06:06.231Z",
    "updated_at": "2022-10-31T19:06:06.231Z",
    "web_url": "http://localhost/namespace19/project22/-/pipelines/273"
  },
  "created_at": "2022-10-31T19:06:06.237Z",
  "updated_at":"2022-10-31T19:06:06.237Z",
  "target_branch":"main",
  "status":"idle",
  "merged_at":null,
  "duration":null
}

Add a merge request to a merge train

Add a merge request to the merge train targeting the merge request’s target branch.

POST /projects/:id/merge_trains/merge_requests/:merge_request_iid

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringYesThe ID or URL-encoded path of the project.
merge_request_iidintegerYesThe internal ID of the merge request.
auto_mergebooleanNoIf true, the merge request is added to the merge train when the checks pass. When false or unspecified, the merge request is added directly to the merge train.
shastringNoIf present, the SHA must match the HEAD of the source branch, otherwise the merge fails.
squashbooleanNoIf true, the commits are squashed into a single commit on merge.
when_pipeline_succeedsbooleanNoDeprecated in GitLab 17.11. Use auto_merge instead.

Example request:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/597/merge_trains/merge_requests/1"

Returns:

  • 403: Forbidden if Merge Trains are not available for the project

Example response:

[
  {
    "id": 267,
    "merge_request": {
      "id": 273,
      "iid": 1,
      "project_id": 597,
      "title": "My title 9",
      "description": null,
      "state": "opened",
      "created_at": "2022-10-31T19:06:05.725Z",
      "updated_at": "2022-10-31T19:06:05.725Z",
      "web_url": "http://localhost/namespace18/project21/-/merge_requests/1"
    },
    "user": {
      "id": 933,
      "username": "user12",
      "name": "Sidney Jones31",
      "state": "active",
      "avatar_url": "https://www.gravatar.com/avatar/6c8365de387cb3db10ecc7b1880203c4?s=80\u0026d=identicon",
      "web_url": "http://localhost/user12"
    },
    "pipeline": {
      "id": 273,
      "iid": 1,
      "project_id": 598,
      "sha": "b83d6e391c22777fca1ed3012fce84f633d7fed0",
      "ref": "main",
      "status": "pending",
      "source": "push",
      "created_at": "2022-10-31T19:06:06.231Z",
      "updated_at": "2022-10-31T19:06:06.231Z",
      "web_url": "http://localhost/namespace19/project22/-/pipelines/273"
    },
    "created_at": "2022-10-31T19:06:06.237Z",
    "updated_at":"2022-10-31T19:06:06.237Z",
    "target_branch":"main",
    "status":"idle",
    "merged_at":null,
    "duration":null
  }
]