debian-mirror-gitlab/doc/api/merge_requests.md

2619 lines
107 KiB
Markdown
Raw Normal View History

2020-10-24 23:57:45 +05:30
---
stage: Create
2021-04-17 20:07:23 +05:30
group: Code Review
2021-02-22 17:27:13 +05:30
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments"
2020-10-24 23:57:45 +05:30
type: reference, api
---
2021-03-11 19:13:27 +05:30
# Merge requests API **(FREE)**
2017-09-10 17:25:29 +05:30
2021-03-08 18:12:59 +05:30
> - `author_id`, `author_username`, and `assignee_id` were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 9.5.
> - `my_reaction_emoji` was [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0.
> - For the `scope` attribute, `created-by-me` and `assigned-to-me` were [deprecated](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18935) in favor of `created_by_me` and `assigned_to_me` in GitLab 11.0.
> - `with_labels_details` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7.
> - `author_username` and `author_username` were [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 12.10.
> - `reference` was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/20354) in GitLab 12.10 in favour of `references`.
> - `with_merge_status_recheck` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0.
> - `reviewer_username` and `reviewer_id` were [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8.
2021-03-11 19:13:27 +05:30
> - `reviewer_ids` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51186) in GitLab 13.8.
2021-09-04 01:27:46 +05:30
> - `draft` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/63473) as an eventual replacement for `work_in_progress` in GitLab 14.0
2014-09-02 18:07:02 +05:30
2021-03-08 18:12:59 +05:30
Every API call to merge requests must be authenticated.
2020-03-13 15:44:24 +05:30
2021-03-08 18:12:59 +05:30
**Important notes:**
- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29984) in GitLab 12.8, the mergeability (`merge_status`)
of each merge request is checked asynchronously when a request is made to this endpoint. Poll this API endpoint
to get updated status. This affects the `has_conflicts` property as it is dependent on the `merge_status`. It returns
`false` unless `merge_status` is `cannot_be_merged`.
- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0, listing merge requests may
not proactively update `merge_status` (which also affects the `has_conflicts`), as this can be an expensive operation.
If you need the value of these fields from this endpoint, set the `with_merge_status_recheck` parameter to
`true` in the query.
- `references.relative` is relative to the group or project that the merge request is being requested. When the merge request
is fetched from its project, `relative` format would be the same as `short` format, and when requested across groups or projects, it is expected to be the same as `full` format.
2021-03-11 19:13:27 +05:30
- If `approvals_before_merge` is not provided, it inherits the value from the target project. If provided, the following conditions must hold for it to take effect:
2021-03-08 18:12:59 +05:30
- The target project's `approvals_before_merge` must be greater than zero. A
value of zero disables approvals for that project.
- The provided value of `approvals_before_merge` must be greater than the
target project's `approvals_before_merge`.
This API returns `HTTP 201 Created` for a successful response.
- [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/46190) in GitLab 13.6,
diffs associated with the set of changes have the same size limitations applied as other diffs
returned by the API or viewed via the UI. When these limits impact the results, the `overflow`
field contains a value of `true`. Diff data without these limits applied can be retrieved by
2021-04-17 20:07:23 +05:30
adding the `access_raw_diffs` parameter, accessing diffs not from the database but from Gitaly directly.
This approach is generally slower and more resource-intensive, but isn't subject to size limits
placed on database-backed diffs. [Limits inherent to Gitaly](../development/diffs.md#diff-limits)
still apply.
2020-03-13 15:44:24 +05:30
2014-09-02 18:07:02 +05:30
## List merge requests
2020-05-24 23:13:21 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 9.5.
2017-09-10 17:25:29 +05:30
Get all merge requests the authenticated user has access to. By
default it returns only merge requests created by the current user. To
get all merge requests, use parameter `scope=all`.
The `state` parameter can be used to get only merge requests with a
2021-03-08 18:12:59 +05:30
given state (`opened`, `closed`, `locked`, or `merged`) or all of them (`all`). It should be noted that when searching by `locked` it mostly returns no results as it is a short-lived, transitional state.
2017-09-10 17:25:29 +05:30
The pagination parameters `page` and `per_page` can be used to
restrict the list of merge requests.
2020-04-08 14:13:33 +05:30
```plaintext
2017-09-10 17:25:29 +05:30
GET /merge_requests
GET /merge_requests?state=opened
GET /merge_requests?state=all
GET /merge_requests?milestone=release
GET /merge_requests?labels=bug,reproduced
GET /merge_requests?author_id=5
2020-04-22 19:07:51 +05:30
GET /merge_requests?author_username=gitlab-bot
2018-03-17 18:26:18 +05:30
GET /merge_requests?my_reaction_emoji=star
2018-11-08 19:23:39 +05:30
GET /merge_requests?scope=assigned_to_me
2019-03-02 22:35:43 +05:30
GET /merge_requests?search=foo&in=title
2017-09-10 17:25:29 +05:30
```
Parameters:
2020-03-13 15:44:24 +05:30
| Attribute | Type | Required | Description |
| ------------------------------- | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
2021-03-08 18:12:59 +05:30
| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`. |
| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`. |
| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc`. |
2020-03-13 15:44:24 +05:30
| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. |
2021-03-08 18:12:59 +05:30
| `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. |
2020-03-13 15:44:24 +05:30
| `labels` | string | no | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. |
2021-03-08 18:12:59 +05:30
| `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. |
| `with_merge_status_recheck` | boolean | no | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. |
2021-01-29 00:20:46 +05:30
| `created_after` | datetime | no | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
| `created_before` | datetime | no | Return merge requests created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
| `updated_after` | datetime | no | Return merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
| `updated_before` | datetime | no | Return merge requests updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
2020-03-13 15:44:24 +05:30
| `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead. |
2021-03-08 18:12:59 +05:30
| `author_id` | integer | no | Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. |
| `author_username` | string | no | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`. |
2020-03-13 15:44:24 +05:30
| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. |
2021-03-11 19:13:27 +05:30
| `approver_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. |
| `approved_by_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have been approved by all the users with the given `id`s (Max: 5). `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. |
2021-03-08 18:12:59 +05:30
| `reviewer_id` | integer | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. |
| `reviewer_username` | string | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. |
| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. |
| `source_branch` | string | no | Return merge requests with the given source branch. |
| `target_branch` | string | no | Return merge requests with the given target branch. |
| `search` | string | no | Search merge requests against their `title` and `description`. |
| `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description`. |
2021-04-17 20:07:23 +05:30
| `wip` | string | no | Filter merge requests against their `wip` status. `yes` to return *only* draft merge requests, `no` to return *non-draft* merge requests. |
2021-03-08 18:12:59 +05:30
| `not` | Hash | no | Return merge requests that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `reviewer_id`, `reviewer_username`, `my_reaction_emoji`. |
2021-01-29 00:20:46 +05:30
| `environment` | string | no | Returns merge requests deployed to the given environment. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
| `deployed_before` | datetime | no | Return merge requests deployed before the given date/time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
| `deployed_after` | datetime | no | Return merge requests deployed after the given date/time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
2020-03-13 15:44:24 +05:30
2017-09-10 17:25:29 +05:30
```json
[
{
"id": 1,
"iid": 1,
"project_id": 3,
"title": "test1",
2018-12-05 23:21:45 +05:30
"description": "fixed login page css paddings",
2018-12-13 13:39:08 +05:30
"state": "merged",
"merged_by": {
"id": 87854,
"name": "Douwe Maan",
"username": "DouweM",
"state": "active",
"avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png",
"web_url": "https://gitlab.com/DouweM"
},
"merged_at": "2018-09-07T11:16:17.520Z",
"closed_by": null,
"closed_at": null,
2018-03-17 18:26:18 +05:30
"created_at": "2017-04-29T08:46:00Z",
"updated_at": "2017-04-29T08:46:00Z",
2018-12-05 23:21:45 +05:30
"target_branch": "master",
"source_branch": "test1",
2017-09-10 17:25:29 +05:30
"upvotes": 0,
"downvotes": 0,
"author": {
"id": 1,
"name": "Administrator",
2018-12-05 23:21:45 +05:30
"username": "admin",
2017-09-10 17:25:29 +05:30
"state": "active",
2018-11-08 19:23:39 +05:30
"avatar_url": null,
"web_url" : "https://gitlab.example.com/admin"
2017-09-10 17:25:29 +05:30
},
"assignee": {
"id": 1,
"name": "Administrator",
2018-12-05 23:21:45 +05:30
"username": "admin",
2017-09-10 17:25:29 +05:30
"state": "active",
2018-11-08 19:23:39 +05:30
"avatar_url": null,
"web_url" : "https://gitlab.example.com/admin"
2017-09-10 17:25:29 +05:30
},
2019-07-31 22:56:46 +05:30
"assignees": [{
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
"web_url": "https://gitlab.example.com/axel.block"
}],
2021-03-08 18:12:59 +05:30
"reviewers": [{
"id": 2,
"name": "Sam Bauch",
"username": "kenyatta_oconnell",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/956c92487c6f6f7616b536927e22c9a0?s=80&d=identicon",
"web_url": "http://gitlab.example.com//kenyatta_oconnell"
}],
2017-09-10 17:25:29 +05:30
"source_project_id": 2,
"target_project_id": 3,
2018-12-05 23:21:45 +05:30
"labels": [
"Community contribution",
"Manage"
],
2021-09-04 01:27:46 +05:30
"draft": false,
2017-09-10 17:25:29 +05:30
"work_in_progress": false,
"milestone": {
"id": 5,
"iid": 1,
"project_id": 3,
"title": "v2.0",
"description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.",
"state": "closed",
"created_at": "2015-02-02T19:49:26.013Z",
"updated_at": "2015-02-02T19:49:26.013Z",
2018-12-05 23:21:45 +05:30
"due_date": "2018-09-22",
"start_date": "2018-08-08",
"web_url": "https://gitlab.example.com/my-group/my-project/milestones/1"
2017-09-10 17:25:29 +05:30
},
"merge_when_pipeline_succeeds": true,
"merge_status": "can_be_merged",
"sha": "8888888888888888888888888888888888888888",
"merge_commit_sha": null,
2019-12-26 22:10:19 +05:30
"squash_commit_sha": null,
2017-09-10 17:25:29 +05:30
"user_notes_count": 1,
2018-12-05 23:21:45 +05:30
"discussion_locked": null,
2017-09-10 17:25:29 +05:30
"should_remove_source_branch": true,
"force_remove_source_branch": false,
2018-12-05 23:21:45 +05:30
"allow_collaboration": false,
"allow_maintainer_to_push": false,
"web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
2020-03-13 15:44:24 +05:30
"references": {
"short": "!1",
"relative": "my-group/my-project!1",
"full": "my-group/my-project!1"
},
2018-03-17 18:26:18 +05:30
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
2018-12-05 23:21:45 +05:30
},
2019-09-04 21:01:54 +05:30
"squash": false,
"task_completion_status":{
"count":0,
"completed_count":0
}
2017-09-10 17:25:29 +05:30
}
]
```
2021-03-11 19:13:27 +05:30
Users on GitLab Premium or higher also see
2019-09-30 21:07:59 +05:30
the `approvals_before_merge` parameter:
```json
[
{
"id": 1,
"title": "test1",
"approvals_before_merge": null
...
}
]
```
2017-09-10 17:25:29 +05:30
## List project merge requests
2016-04-02 18:10:28 +05:30
Get all merge requests for this project.
2018-11-08 19:23:39 +05:30
The `state` parameter can be used to get only merge requests with a given state (`opened`, `closed`, `locked`, or `merged`) or all of them (`all`).
The pagination parameters `page` and `per_page` can be used to restrict the list of merge requests.
2014-09-02 18:07:02 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2014-09-02 18:07:02 +05:30
GET /projects/:id/merge_requests
GET /projects/:id/merge_requests?state=opened
GET /projects/:id/merge_requests?state=all
2017-08-17 22:00:37 +05:30
GET /projects/:id/merge_requests?iids[]=42&iids[]=43
GET /projects/:id/merge_requests?milestone=release
GET /projects/:id/merge_requests?labels=bug,reproduced
2018-03-17 18:26:18 +05:30
GET /projects/:id/merge_requests?my_reaction_emoji=star
2014-09-02 18:07:02 +05:30
```
2018-03-17 18:26:18 +05:30
`project_id` represents the ID of the project where the MR resides.
2021-03-08 18:12:59 +05:30
`project_id` always equals `target_project_id`.
2018-03-17 18:26:18 +05:30
In the case of a merge request from the same project,
`source_project_id`, `target_project_id` and `project_id`
2021-03-08 18:12:59 +05:30
are the same. In the case of a merge request from a fork,
`target_project_id` and `project_id` are the same and
`source_project_id` is the fork project's ID.
2018-03-17 18:26:18 +05:30
2014-09-02 18:07:02 +05:30
Parameters:
2020-03-13 15:44:24 +05:30
| Attribute | Type | Required | Description |
| ------------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `iids[]` | integer array | no | Return the request having the given `iid`. |
| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`. |
| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`. |
| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc`. |
2020-03-13 15:44:24 +05:30
| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. |
2021-03-08 18:12:59 +05:30
| `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. |
2020-03-13 15:44:24 +05:30
| `labels` | string | no | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. |
2021-03-08 18:12:59 +05:30
| `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. |
| `with_merge_status_recheck` | boolean | no | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. |
2021-01-29 00:20:46 +05:30
| `created_after` | datetime | no | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
| `created_before` | datetime | no | Return merge requests created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
| `updated_after` | datetime | no | Return merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
| `updated_before` | datetime | no | Return merge requests updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
2021-03-08 18:12:59 +05:30
| `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me`, or `all`. |
| `author_id` | integer | no | Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. |
| `author_username` | string | no | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`.|
| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. |
2021-03-11 19:13:27 +05:30
| `approver_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. |
| `approved_by_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have been approved by all the users with the given `id`s (Max: 5). `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. |
2021-03-08 18:12:59 +05:30
| `reviewer_id` | integer | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. |
| `reviewer_username` | string | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. |
| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. |
| `source_branch` | string | no | Return merge requests with the given source branch. |
| `target_branch` | string | no | Return merge requests with the given target branch. |
| `search` | string | no | Search merge requests against their `title` and `description`. |
2021-04-17 20:07:23 +05:30
| `wip` | string | no | Filter merge requests against their `wip` status. `yes` to return *only* draft merge requests, `no` to return *non-draft* merge requests. |
2021-03-08 18:12:59 +05:30
| `not` | Hash | no | Return merge requests that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `reviewer_id`, `reviewer_username`, `my_reaction_emoji`. |
2014-09-02 18:07:02 +05:30
```json
[
{
"id": 1,
"iid": 1,
"project_id": 3,
"title": "test1",
2018-12-05 23:21:45 +05:30
"description": "fixed login page css paddings",
2018-12-13 13:39:08 +05:30
"state": "merged",
"merged_by": {
"id": 87854,
"name": "Douwe Maan",
"username": "DouweM",
"state": "active",
"avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png",
"web_url": "https://gitlab.com/DouweM"
},
"merged_at": "2018-09-07T11:16:17.520Z",
"closed_by": null,
"closed_at": null,
2018-03-17 18:26:18 +05:30
"created_at": "2017-04-29T08:46:00Z",
"updated_at": "2017-04-29T08:46:00Z",
2018-12-05 23:21:45 +05:30
"target_branch": "master",
"source_branch": "test1",
2014-09-02 18:07:02 +05:30
"upvotes": 0,
"downvotes": 0,
"author": {
"id": 1,
"name": "Administrator",
2018-12-05 23:21:45 +05:30
"username": "admin",
2014-09-02 18:07:02 +05:30
"state": "active",
2018-11-08 19:23:39 +05:30
"avatar_url": null,
"web_url" : "https://gitlab.example.com/admin"
2014-09-02 18:07:02 +05:30
},
"assignee": {
"id": 1,
"name": "Administrator",
2018-12-05 23:21:45 +05:30
"username": "admin",
2014-09-02 18:07:02 +05:30
"state": "active",
2018-11-08 19:23:39 +05:30
"avatar_url": null,
"web_url" : "https://gitlab.example.com/admin"
},
2019-07-31 22:56:46 +05:30
"assignees": [{
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
"web_url": "https://gitlab.example.com/axel.block"
}],
2021-03-08 18:12:59 +05:30
"reviewers": [{
"id": 2,
"name": "Sam Bauch",
"username": "kenyatta_oconnell",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/956c92487c6f6f7616b536927e22c9a0?s=80&d=identicon",
"web_url": "http://gitlab.example.com//kenyatta_oconnell"
}],
2018-11-08 19:23:39 +05:30
"source_project_id": 2,
"target_project_id": 3,
2018-12-05 23:21:45 +05:30
"labels": [
"Community contribution",
"Manage"
],
2021-09-04 01:27:46 +05:30
"draft": false,
2018-11-08 19:23:39 +05:30
"work_in_progress": false,
"milestone": {
"id": 5,
"iid": 1,
"project_id": 3,
"title": "v2.0",
"description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.",
"state": "closed",
"created_at": "2015-02-02T19:49:26.013Z",
"updated_at": "2015-02-02T19:49:26.013Z",
2018-12-05 23:21:45 +05:30
"due_date": "2018-09-22",
"start_date": "2018-08-08",
"web_url": "https://gitlab.example.com/my-group/my-project/milestones/1"
2018-11-08 19:23:39 +05:30
},
"merge_when_pipeline_succeeds": true,
"merge_status": "can_be_merged",
"sha": "8888888888888888888888888888888888888888",
"merge_commit_sha": null,
2019-12-26 22:10:19 +05:30
"squash_commit_sha": null,
2018-11-08 19:23:39 +05:30
"user_notes_count": 1,
2018-12-05 23:21:45 +05:30
"discussion_locked": null,
2018-11-08 19:23:39 +05:30
"should_remove_source_branch": true,
"force_remove_source_branch": false,
2018-12-05 23:21:45 +05:30
"allow_collaboration": false,
"allow_maintainer_to_push": false,
"web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
2020-03-13 15:44:24 +05:30
"references": {
"short": "!1",
"relative": "!1",
"full": "my-group/my-project!1"
},
2018-11-08 19:23:39 +05:30
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
2018-12-05 23:21:45 +05:30
},
2019-09-04 21:01:54 +05:30
"squash": false,
"task_completion_status":{
"count":0,
"completed_count":0
2019-12-26 22:10:19 +05:30
},
"has_conflicts": false,
"blocking_discussions_resolved": true
2018-11-08 19:23:39 +05:30
}
]
```
2021-09-04 01:27:46 +05:30
The `merge_status` field may hold one of the following values:
| Value | Interpretation |
|----------------------------|-----------------------------------------------------------------------|
| `unchecked` | We have not checked this yet |
| `checking` | We are currently checking if the merge request can be merged |
| `can_be_merged` | This merge request can be merged without conflict |
| `cannot_be_merged` | There are merge conflicts between the source and target branches |
| `cannot_be_merged_recheck` | Currently unchecked. Before the current changes, there were conflicts |
2021-03-11 19:13:27 +05:30
Users on GitLab Premium or higher also see
2019-09-30 21:07:59 +05:30
the `approvals_before_merge` parameter:
```json
[
{
"id": 1,
"title": "test1",
"approvals_before_merge": null
...
}
]
```
2018-11-08 19:23:39 +05:30
## List group merge requests
Get all merge requests for this group and its subgroups.
The `state` parameter can be used to get only merge requests with a given state (`opened`, `closed`, `locked`, or `merged`) or all of them (`all`).
The pagination parameters `page` and `per_page` can be used to restrict the list of merge requests.
2020-04-08 14:13:33 +05:30
```plaintext
2018-11-08 19:23:39 +05:30
GET /groups/:id/merge_requests
GET /groups/:id/merge_requests?state=opened
GET /groups/:id/merge_requests?state=all
GET /groups/:id/merge_requests?milestone=release
GET /groups/:id/merge_requests?labels=bug,reproduced
GET /groups/:id/merge_requests?my_reaction_emoji=star
```
`group_id` represents the ID of the group which contains the project where the MR resides.
Parameters:
2020-03-13 15:44:24 +05:30
| Attribute | Type | Required | Description |
| ------------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`. |
| `order_by` | string | no | Return merge requests ordered by `created_at` or `updated_at` fields. Default is `created_at`. |
| `sort` | string | no | Return merge requests sorted in `asc` or `desc` order. Default is `desc`. |
2020-03-13 15:44:24 +05:30
| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. |
2021-03-08 18:12:59 +05:30
| `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. |
2020-03-13 15:44:24 +05:30
| `labels` | string | no | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. |
2021-03-08 18:12:59 +05:30
| `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. Introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413).|
| `with_merge_status_recheck` | boolean | no | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. Introduced in [GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890). |
| `created_after` | datetime | no | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
| `created_before` | datetime | no | Return merge requests created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
| `updated_after` | datetime | no | Return merge requests updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
| `updated_before` | datetime | no | Return merge requests updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
| `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. |
| `author_id` | integer | no | Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 9.5)_. |
| `author_username` | string | no | Returns merge requests created by the given `username`. Mutually exclusive with `author_id`. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 12.10)_. |
| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13060) in GitLab 9.5)_. |
2021-06-08 01:23:25 +05:30
| `approver_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. |
2021-03-11 19:13:27 +05:30
| `approved_by_ids` **(PREMIUM)** | integer array | no | Returns merge requests which have been approved by all the users with the given `id`s (Max: 5). `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. |
| `reviewer_id` | integer | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`. |
| `reviewer_username` | string | no | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. |
2021-03-08 18:12:59 +05:30
| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/14016) in GitLab 10.0)_. |
| `source_branch` | string | no | Return merge requests with the given source branch. |
| `target_branch` | string | no | Return merge requests with the given target branch. |
| `search` | string | no | Search merge requests against their `title` and `description`. |
| `non_archived` | boolean | no | Return merge requests from non archived projects only. Default is true. _(Introduced in [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23809))_. |
| `not` | Hash | no | Return merge requests that do not match the parameters supplied. Accepts: `labels`, `milestone`, `author_id`, `author_username`, `assignee_id`, `assignee_username`, `reviewer_id`, `reviewer_username`, `my_reaction_emoji`. |
2018-11-08 19:23:39 +05:30
```json
[
{
"id": 1,
"iid": 1,
"project_id": 3,
"title": "test1",
2018-12-05 23:21:45 +05:30
"description": "fixed login page css paddings",
2018-12-13 13:39:08 +05:30
"state": "merged",
"merged_by": {
"id": 87854,
"name": "Douwe Maan",
"username": "DouweM",
"state": "active",
"avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png",
"web_url": "https://gitlab.com/DouweM"
},
"merged_at": "2018-09-07T11:16:17.520Z",
"closed_by": null,
"closed_at": null,
2018-11-08 19:23:39 +05:30
"created_at": "2017-04-29T08:46:00Z",
"updated_at": "2017-04-29T08:46:00Z",
2018-12-05 23:21:45 +05:30
"target_branch": "master",
"source_branch": "test1",
2018-11-08 19:23:39 +05:30
"upvotes": 0,
"downvotes": 0,
"author": {
"id": 1,
"name": "Administrator",
2018-12-05 23:21:45 +05:30
"username": "admin",
2018-11-08 19:23:39 +05:30
"state": "active",
"avatar_url": null,
"web_url" : "https://gitlab.example.com/admin"
},
"assignee": {
"id": 1,
"name": "Administrator",
2018-12-05 23:21:45 +05:30
"username": "admin",
2018-11-08 19:23:39 +05:30
"state": "active",
"avatar_url": null,
"web_url" : "https://gitlab.example.com/admin"
2014-09-02 18:07:02 +05:30
},
2019-07-31 22:56:46 +05:30
"assignees": [{
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
"web_url": "https://gitlab.example.com/axel.block"
}],
2021-03-08 18:12:59 +05:30
"reviewers": [{
"id": 2,
"name": "Sam Bauch",
"username": "kenyatta_oconnell",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/956c92487c6f6f7616b536927e22c9a0?s=80&d=identicon",
"web_url": "http://gitlab.example.com//kenyatta_oconnell"
}],
2016-08-24 12:49:21 +05:30
"source_project_id": 2,
"target_project_id": 3,
2018-12-05 23:21:45 +05:30
"labels": [
"Community contribution",
"Manage"
],
2021-09-04 01:27:46 +05:30
"draft": false,
2016-04-02 18:10:28 +05:30
"work_in_progress": false,
"milestone": {
"id": 5,
"iid": 1,
"project_id": 3,
"title": "v2.0",
"description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.",
"state": "closed",
"created_at": "2015-02-02T19:49:26.013Z",
"updated_at": "2015-02-02T19:49:26.013Z",
2018-12-05 23:21:45 +05:30
"due_date": "2018-10-22",
"start_date": "2018-09-08",
"web_url": "gitlab.example.com/my-group/my-project/milestones/1"
2016-04-02 18:10:28 +05:30
},
2017-08-17 22:00:37 +05:30
"merge_when_pipeline_succeeds": true,
2016-06-02 11:05:42 +05:30
"merge_status": "can_be_merged",
2016-09-29 09:46:39 +05:30
"sha": "8888888888888888888888888888888888888888",
"merge_commit_sha": null,
2019-12-26 22:10:19 +05:30
"squash_commit_sha": null,
2016-08-24 12:49:21 +05:30
"user_notes_count": 1,
2018-12-05 23:21:45 +05:30
"discussion_locked": null,
2016-08-24 12:49:21 +05:30
"should_remove_source_branch": true,
2016-09-29 09:46:39 +05:30
"force_remove_source_branch": false,
2018-12-05 23:21:45 +05:30
"web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
2020-03-13 15:44:24 +05:30
"references": {
"short": "!1",
"relative": "my-project!1",
"full": "my-group/my-project!1"
},
2018-03-17 18:26:18 +05:30
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
2018-12-05 23:21:45 +05:30
},
2019-09-04 21:01:54 +05:30
"squash": false,
"task_completion_status":{
"count":0,
"completed_count":0
2019-12-26 22:10:19 +05:30
},
"has_conflicts": false,
"blocking_discussions_resolved": true
2014-09-02 18:07:02 +05:30
}
]
```
2021-03-11 19:13:27 +05:30
Users on GitLab Premium or higher also see
2019-09-30 21:07:59 +05:30
the `approvals_before_merge` parameter:
```json
[
{
"id": 1,
"title": "test1",
"approvals_before_merge": null
...
}
]
```
2014-09-02 18:07:02 +05:30
## Get single MR
Shows information about a single merge request.
2014-09-02 18:07:02 +05:30
2018-11-18 11:00:15 +05:30
**Note**: the `changes_count` value in the response is a string, not an
integer. This is because when an MR has too many changes to display and store,
2021-03-08 18:12:59 +05:30
it is capped at 1,000. In that case, the API returns the string
2018-11-18 11:00:15 +05:30
`"1000+"` for the changes count.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
GET /projects/:id/merge_requests/:merge_request_iid
2014-09-02 18:07:02 +05:30
```
Parameters:
2021-03-08 18:12:59 +05:30
| Attribute | Type | Required | Description |
|----------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
| `render_html` | integer | no | If `true` response includes rendered HTML for title and description. |
| `include_diverged_commits_count` | boolean | no | If `true` response includes the commits behind the target branch. |
| `include_rebase_in_progress` | boolean | no | If `true` response includes whether a rebase operation is in progress. |
2020-03-13 15:44:24 +05:30
2014-09-02 18:07:02 +05:30
```json
{
"id": 1,
"iid": 1,
"project_id": 3,
"title": "test1",
2018-12-05 23:21:45 +05:30
"description": "fixed login page css paddings",
2018-12-13 13:39:08 +05:30
"state": "merged",
2018-03-17 18:26:18 +05:30
"created_at": "2017-04-29T08:46:00Z",
"updated_at": "2017-04-29T08:46:00Z",
2018-12-05 23:21:45 +05:30
"target_branch": "master",
"source_branch": "test1",
2014-09-02 18:07:02 +05:30
"upvotes": 0,
"downvotes": 0,
"author": {
2018-12-05 23:21:45 +05:30
"id": 1,
"name": "Administrator",
"username": "admin",
"state": "active",
"avatar_url": null,
"web_url" : "https://gitlab.example.com/admin"
2014-09-02 18:07:02 +05:30
},
2019-07-07 11:18:12 +05:30
"user" : {
"can_merge" : false
2020-03-13 15:44:24 +05:30
},
2014-09-02 18:07:02 +05:30
"assignee": {
2018-12-05 23:21:45 +05:30
"id": 1,
"name": "Administrator",
"username": "admin",
"state": "active",
"avatar_url": null,
"web_url" : "https://gitlab.example.com/admin"
2014-09-02 18:07:02 +05:30
},
2019-07-31 22:56:46 +05:30
"assignees": [{
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
"web_url": "https://gitlab.example.com/axel.block"
}],
2021-03-08 18:12:59 +05:30
"reviewers": [{
"id": 2,
"name": "Sam Bauch",
"username": "kenyatta_oconnell",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/956c92487c6f6f7616b536927e22c9a0?s=80&d=identicon",
"web_url": "http://gitlab.example.com//kenyatta_oconnell"
}],
2016-08-24 12:49:21 +05:30
"source_project_id": 2,
"target_project_id": 3,
2018-12-05 23:21:45 +05:30
"labels": [
"Community contribution",
"Manage"
],
2021-09-04 01:27:46 +05:30
"draft": false,
2016-04-02 18:10:28 +05:30
"work_in_progress": false,
"milestone": {
"id": 5,
"iid": 1,
"project_id": 3,
"title": "v2.0",
"description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.",
"state": "closed",
"created_at": "2015-02-02T19:49:26.013Z",
"updated_at": "2015-02-02T19:49:26.013Z",
2018-12-05 23:21:45 +05:30
"due_date": "2018-09-22",
"start_date": "2018-08-08",
"web_url": "https://gitlab.example.com/my-group/my-project/milestones/1"
2016-04-02 18:10:28 +05:30
},
2017-08-17 22:00:37 +05:30
"merge_when_pipeline_succeeds": true,
2016-06-02 11:05:42 +05:30
"merge_status": "can_be_merged",
2019-02-15 15:39:39 +05:30
"merge_error": null,
2016-09-29 09:46:39 +05:30
"sha": "8888888888888888888888888888888888888888",
2018-12-05 23:21:45 +05:30
"merge_commit_sha": null,
2019-12-26 22:10:19 +05:30
"squash_commit_sha": null,
2016-08-24 12:49:21 +05:30
"user_notes_count": 1,
2018-12-05 23:21:45 +05:30
"discussion_locked": null,
2016-08-24 12:49:21 +05:30
"should_remove_source_branch": true,
2016-09-29 09:46:39 +05:30
"force_remove_source_branch": false,
2018-12-05 23:21:45 +05:30
"allow_collaboration": false,
"allow_maintainer_to_push": false,
"web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
2020-03-13 15:44:24 +05:30
"references": {
"short": "!1",
"relative": "!1",
"full": "my-group/my-project!1"
},
2018-03-17 18:26:18 +05:30
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
2018-03-27 19:54:05 +05:30
},
2018-12-05 23:21:45 +05:30
"squash": false,
"subscribed": false,
"changes_count": "1",
"merged_by": {
"id": 87854,
"name": "Douwe Maan",
"username": "DouweM",
"state": "active",
"avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png",
"web_url": "https://gitlab.com/DouweM"
},
"merged_at": "2018-09-07T11:16:17.520Z",
"closed_by": null,
"closed_at": null,
"latest_build_started_at": "2018-09-07T07:27:38.472Z",
"latest_build_finished_at": "2018-09-07T08:07:06.012Z",
2018-03-27 19:54:05 +05:30
"first_deployed_to_production_at": null,
"pipeline": {
2018-12-05 23:21:45 +05:30
"id": 29626725,
"sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f",
"ref": "patch-28",
"status": "success",
"web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725"
2018-03-27 19:54:05 +05:30
},
2018-12-05 23:21:45 +05:30
"diff_refs": {
"base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00",
"head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f",
"start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00"
2018-11-20 20:47:30 +05:30
},
2019-02-15 15:39:39 +05:30
"diverged_commits_count": 2,
2019-09-04 21:01:54 +05:30
"rebase_in_progress": false,
2020-04-22 19:07:51 +05:30
"first_contribution": false,
2019-09-04 21:01:54 +05:30
"task_completion_status":{
"count":0,
"completed_count":0
2019-12-26 22:10:19 +05:30
},
"has_conflicts": false,
"blocking_discussions_resolved": true
2014-09-02 18:07:02 +05:30
}
```
2021-03-11 19:13:27 +05:30
Users on GitLab Premium also see
2019-09-30 21:07:59 +05:30
the `approvals_before_merge` parameter:
```json
{
"id": 1,
"title": "test1",
"approvals_before_merge": null
...
}
```
2021-04-29 21:17:54 +05:30
The `diff_refs` in the response correspond to the latest diff version of the merge request.
2018-03-17 18:26:18 +05:30
## Get single MR participants
Get a list of merge request participants.
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
GET /projects/:id/merge_requests/:merge_request_iid/participants
```
Parameters:
2021-03-08 18:12:59 +05:30
| Attribute | Type | Required | Description |
|----------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
2018-03-17 18:26:18 +05:30
```json
[
{
"id": 1,
"name": "John Doe1",
"username": "user1",
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/c922747a93b40d1ea88262bf1aebee62?s=80&d=identicon",
"web_url": "http://localhost/user1"
},
{
"id": 2,
"name": "John Doe2",
"username": "user2",
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/10fc7f102be8de7657fb4d80898bbfe3?s=80&d=identicon",
"web_url": "http://localhost/user2"
2019-09-04 21:01:54 +05:30
}
2018-03-17 18:26:18 +05:30
]
```
2015-12-23 02:04:40 +05:30
## Get single MR commits
Get a list of merge request commits.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
GET /projects/:id/merge_requests/:merge_request_iid/commits
2015-12-23 02:04:40 +05:30
```
Parameters:
2021-03-08 18:12:59 +05:30
| Attribute | Type | Required | Description |
|----------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
2015-12-23 02:04:40 +05:30
```json
[
{
"id": "ed899a2f4b50b4370feeea94676502b42383c746",
"short_id": "ed899a2f4b5",
"title": "Replace sanitize with escape once",
2020-04-08 14:13:33 +05:30
"author_name": "Example User",
"author_email": "user@example.com",
2015-12-23 02:04:40 +05:30
"created_at": "2012-09-20T11:50:22+03:00",
"message": "Replace sanitize with escape once"
},
{
"id": "6104942438c14ec7bd21c6cd5bd995272b3faff6",
"short_id": "6104942438c",
"title": "Sanitize for network graph",
2020-04-08 14:13:33 +05:30
"author_name": "Example User",
"author_email": "user@example.com",
2015-12-23 02:04:40 +05:30
"created_at": "2012-09-20T09:06:12+03:00",
"message": "Sanitize for network graph"
}
]
```
2015-04-26 12:48:37 +05:30
## Get single MR changes
2015-11-26 14:37:03 +05:30
Shows information about the merge request including its files and changes.
2015-04-26 12:48:37 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
GET /projects/:id/merge_requests/:merge_request_iid/changes
2015-04-26 12:48:37 +05:30
```
Parameters:
2021-03-08 18:12:59 +05:30
| Attribute | Type | Required | Description |
|----------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
2021-04-17 20:07:23 +05:30
| `access_raw_diffs` | boolean | no | Retrieve change diffs via Gitaly. |
2015-04-26 12:48:37 +05:30
```json
{
"id": 21,
"iid": 1,
"project_id": 4,
"title": "Blanditiis beatae suscipit hic assumenda et molestias nisi asperiores repellat et.",
"state": "reopened",
"created_at": "2015-02-02T19:49:39.159Z",
"updated_at": "2015-02-02T20:08:49.959Z",
"target_branch": "secret_token",
"source_branch": "version-1-9",
"upvotes": 0,
"downvotes": 0,
"author": {
"name": "Chad Hamill",
"username": "jarrett",
"id": 5,
"state": "active",
2018-11-08 19:23:39 +05:30
"avatar_url": "http://www.gravatar.com/avatar/b95567800f828948baf5f4160ebb2473?s=40&d=identicon",
"web_url" : "https://gitlab.example.com/jarrett"
2015-04-26 12:48:37 +05:30
},
"assignee": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
2018-11-08 19:23:39 +05:30
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40&d=identicon",
"web_url" : "https://gitlab.example.com/root"
2015-04-26 12:48:37 +05:30
},
2019-07-31 22:56:46 +05:30
"assignees": [{
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
"web_url": "https://gitlab.example.com/axel.block"
}],
2021-03-11 19:13:27 +05:30
"reviewers": [{
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
"web_url": "https://gitlab.example.com/axel.block"
}],
2015-04-26 12:48:37 +05:30
"source_project_id": 4,
"target_project_id": 4,
"labels": [ ],
2016-04-02 18:10:28 +05:30
"description": "Qui voluptatibus placeat ipsa alias quasi. Deleniti rem ut sint. Optio velit qui distinctio.",
2021-09-04 01:27:46 +05:30
"draft": false,
2016-04-02 18:10:28 +05:30
"work_in_progress": false,
2015-04-26 12:48:37 +05:30
"milestone": {
"id": 5,
"iid": 1,
"project_id": 4,
"title": "v2.0",
"description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.",
"state": "closed",
"created_at": "2015-02-02T19:49:26.013Z",
"updated_at": "2015-02-02T19:49:26.013Z",
"due_date": null
},
2017-08-17 22:00:37 +05:30
"merge_when_pipeline_succeeds": true,
2016-04-02 18:10:28 +05:30
"merge_status": "can_be_merged",
2016-06-02 11:05:42 +05:30
"subscribed" : true,
2016-09-29 09:46:39 +05:30
"sha": "8888888888888888888888888888888888888888",
"merge_commit_sha": null,
2019-12-26 22:10:19 +05:30
"squash_commit_sha": null,
2016-06-02 11:05:42 +05:30
"user_notes_count": 1,
2018-03-17 18:26:18 +05:30
"changes_count": "1",
2016-08-24 12:49:21 +05:30
"should_remove_source_branch": true,
"force_remove_source_branch": false,
2018-11-08 19:23:39 +05:30
"squash": false,
2020-03-13 15:44:24 +05:30
"web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
"references": {
"short": "!1",
"relative": "!1",
"full": "my-group/my-project!1"
},
2018-03-17 18:26:18 +05:30
"discussion_locked": false,
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
2019-09-04 21:01:54 +05:30
},
"task_completion_status":{
"count":0,
"completed_count":0
},
2015-12-23 02:04:40 +05:30
"changes": [
2015-04-26 12:48:37 +05:30
{
"old_path": "VERSION",
"new_path": "VERSION",
"a_mode": "100644",
"b_mode": "100644",
"diff": "--- a/VERSION\ +++ b/VERSION\ @@ -1 +1 @@\ -1.9.7\ +1.9.8",
"new_file": false,
"renamed_file": false,
"deleted_file": false
}
2021-01-29 00:20:46 +05:30
],
"overflow": false
2015-04-26 12:48:37 +05:30
}
```
2018-03-17 18:26:18 +05:30
## List MR pipelines
2021-03-08 18:12:59 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15454) in GitLab 10.5.
2018-03-27 19:54:05 +05:30
2018-03-17 18:26:18 +05:30
Get a list of merge request pipelines.
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
GET /projects/:id/merge_requests/:merge_request_iid/pipelines
```
Parameters:
2021-03-08 18:12:59 +05:30
| Attribute | Type | Required | Description |
|----------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
2018-03-17 18:26:18 +05:30
```json
[
{
"id": 77,
"sha": "959e04d7c7a30600c894bd3c0cd0e1ce7f42c11d",
"ref": "master",
"status": "success"
}
]
```
2019-12-04 20:38:33 +05:30
## Create MR Pipeline
2020-03-13 15:44:24 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/31722) in GitLab 12.3.
2019-12-04 20:38:33 +05:30
2021-09-30 23:02:18 +05:30
Create a new [pipeline for a merge request](../ci/pipelines/merge_request_pipelines.md).
2021-03-08 18:12:59 +05:30
A pipeline created via this endpoint doesn't run a regular branch/tag pipeline.
It requires `.gitlab-ci.yml` to be configured with `only: [merge_requests]` to create jobs.
2019-12-04 20:38:33 +05:30
The new pipeline can be:
- A detached merge request pipeline.
2021-09-30 23:02:18 +05:30
- A [pipeline for merged results](../ci/pipelines/pipelines_for_merged_results.md)
if the [project setting is enabled](../ci/pipelines/pipelines_for_merged_results.md#enable-pipelines-for-merged-results).
2019-12-04 20:38:33 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2019-12-04 20:38:33 +05:30
POST /projects/:id/merge_requests/:merge_request_iid/pipelines
```
Parameters:
2021-03-08 18:12:59 +05:30
| Attribute | Type | Required | Description |
|----------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
2019-12-04 20:38:33 +05:30
```json
{
"id": 2,
"sha": "b83d6e391c22777fca1ed3012fce84f633d7fed0",
"ref": "refs/merge-requests/1/head",
"status": "pending",
"web_url": "http://localhost/user1/project1/pipelines/2",
"before_sha": "0000000000000000000000000000000000000000",
"tag": false,
"yaml_errors": null,
"user": {
"id": 1,
"name": "John Doe1",
"username": "user1",
"state": "active",
"avatar_url": "https://www.gravatar.com/avatar/c922747a93b40d1ea88262bf1aebee62?s=80&d=identicon",
"web_url": "http://example.com"
},
"created_at": "2019-09-04T19:20:18.267Z",
"updated_at": "2019-09-04T19:20:18.459Z",
"started_at": null,
"finished_at": null,
"committed_at": null,
"duration": null,
"coverage": null,
"detailed_status": {
"icon": "status_pending",
"text": "pending",
"label": "pending",
"group": "pending",
"tooltip": "pending",
"has_details": false,
"details_path": "/user1/project1/pipelines/2",
"illustration": null,
"favicon": "/assets/ci_favicons/favicon_status_pending-5bdf338420e5221ca24353b6bff1c9367189588750632e9a871b7af09ff6a2ae.png"
}
}
```
2014-09-02 18:07:02 +05:30
## Create MR
Creates a new merge request.
2019-09-30 21:07:59 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2014-09-02 18:07:02 +05:30
POST /projects/:id/merge_requests
```
2018-03-27 19:54:05 +05:30
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2021-03-08 18:12:59 +05:30
| `source_branch` | string | yes | The source branch. |
| `target_branch` | string | yes | The target branch. |
| `title` | string | yes | Title of MR. |
| `assignee_id` | integer | no | Assignee user ID. |
2021-03-11 19:13:27 +05:30
| `assignee_ids` | integer array | no | The ID of the user(s) to assign the MR to. Set to `0` or provide an empty value to unassign all assignees. |
2021-04-17 20:07:23 +05:30
| `reviewer_ids` | integer array | no | The ID of the user(s) added as a reviewer to the MR. If set to `0` or left empty, no reviewers are added. |
2019-12-21 20:55:43 +05:30
| `description` | string | no | Description of MR. Limited to 1,048,576 characters. |
2021-03-08 18:12:59 +05:30
| `target_project_id` | integer | no | The target project (numeric ID). |
| `labels` | string | no | Labels for MR as a comma-separated list. |
| `milestone_id` | integer | no | The global ID of a milestone. |
| `remove_source_branch` | boolean | no | Flag indicating if a merge request should remove the source branch when merging. |
| `allow_collaboration` | boolean | no | Allow commits from members who can merge to the target branch. |
| `allow_maintainer_to_push` | boolean | no | Deprecated, see `allow_collaboration`. |
| `squash` | boolean | no | Squash commits into a single commit when merging. |
2019-09-30 21:07:59 +05:30
2014-09-02 18:07:02 +05:30
```json
{
"id": 1,
2016-08-24 12:49:21 +05:30
"iid": 1,
2018-12-05 23:21:45 +05:30
"project_id": 3,
2014-09-02 18:07:02 +05:30
"title": "test1",
2018-12-05 23:21:45 +05:30
"description": "fixed login page css paddings",
2018-12-13 13:39:08 +05:30
"state": "merged",
2018-12-05 23:21:45 +05:30
"created_at": "2017-04-29T08:46:00Z",
"updated_at": "2017-04-29T08:46:00Z",
"target_branch": "master",
"source_branch": "test1",
2014-09-02 18:07:02 +05:30
"upvotes": 0,
"downvotes": 0,
"author": {
"id": 1,
"name": "Administrator",
2018-12-05 23:21:45 +05:30
"username": "admin",
2014-09-02 18:07:02 +05:30
"state": "active",
2018-11-08 19:23:39 +05:30
"avatar_url": null,
"web_url" : "https://gitlab.example.com/admin"
2014-09-02 18:07:02 +05:30
},
"assignee": {
"id": 1,
"name": "Administrator",
2018-12-05 23:21:45 +05:30
"username": "admin",
2014-09-02 18:07:02 +05:30
"state": "active",
2018-11-08 19:23:39 +05:30
"avatar_url": null,
"web_url" : "https://gitlab.example.com/admin"
2014-09-02 18:07:02 +05:30
},
2018-12-05 23:21:45 +05:30
"source_project_id": 2,
"target_project_id": 3,
"labels": [
"Community contribution",
"Manage"
],
2021-09-04 01:27:46 +05:30
"draft": false,
2016-04-02 18:10:28 +05:30
"work_in_progress": false,
"milestone": {
"id": 5,
"iid": 1,
2018-12-05 23:21:45 +05:30
"project_id": 3,
2016-04-02 18:10:28 +05:30
"title": "v2.0",
"description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.",
"state": "closed",
"created_at": "2015-02-02T19:49:26.013Z",
"updated_at": "2015-02-02T19:49:26.013Z",
2018-12-05 23:21:45 +05:30
"due_date": "2018-09-22",
"start_date": "2018-08-08",
"web_url": "https://gitlab.example.com/my-group/my-project/milestones/1"
2016-04-02 18:10:28 +05:30
},
2017-08-17 22:00:37 +05:30
"merge_when_pipeline_succeeds": true,
2016-06-02 11:05:42 +05:30
"merge_status": "can_be_merged",
2019-02-15 15:39:39 +05:30
"merge_error": null,
2016-09-29 09:46:39 +05:30
"sha": "8888888888888888888888888888888888888888",
"merge_commit_sha": null,
2019-12-26 22:10:19 +05:30
"squash_commit_sha": null,
2018-12-05 23:21:45 +05:30
"user_notes_count": 1,
"discussion_locked": null,
2016-08-24 12:49:21 +05:30
"should_remove_source_branch": true,
2016-09-29 09:46:39 +05:30
"force_remove_source_branch": false,
2018-11-08 19:23:39 +05:30
"allow_collaboration": false,
2018-03-27 19:54:05 +05:30
"allow_maintainer_to_push": false,
2018-12-05 23:21:45 +05:30
"web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
2020-03-13 15:44:24 +05:30
"references": {
"short": "!1",
"relative": "!1",
"full": "my-group/my-project!1"
},
2018-03-17 18:26:18 +05:30
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
2018-12-05 23:21:45 +05:30
},
"squash": false,
"subscribed": false,
"changes_count": "1",
"merged_by": {
"id": 87854,
"name": "Douwe Maan",
"username": "DouweM",
"state": "active",
"avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png",
"web_url": "https://gitlab.com/DouweM"
},
"merged_at": "2018-09-07T11:16:17.520Z",
"closed_by": null,
"closed_at": null,
"latest_build_started_at": "2018-09-07T07:27:38.472Z",
"latest_build_finished_at": "2018-09-07T08:07:06.012Z",
"first_deployed_to_production_at": null,
"pipeline": {
"id": 29626725,
"sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f",
"ref": "patch-28",
"status": "success",
"web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725"
},
"diff_refs": {
"base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00",
"head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f",
"start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00"
},
2019-09-04 21:01:54 +05:30
"diverged_commits_count": 2,
"task_completion_status":{
"count":0,
"completed_count":0
}
2014-09-02 18:07:02 +05:30
}
```
2021-03-11 19:13:27 +05:30
Users of [GitLab Premium or higher](https://about.gitlab.com/pricing/) also see
2019-09-30 21:07:59 +05:30
the `approvals_before_merge` parameter:
```json
{
"id": 1,
"title": "test1",
"approvals_before_merge": null
...
}
```
2014-09-02 18:07:02 +05:30
## Update MR
Updates an existing merge request. You can change the target branch, title, or even close the MR.
2014-09-02 18:07:02 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
PUT /projects/:id/merge_requests/:merge_request_iid
2014-09-02 18:07:02 +05:30
```
2018-03-27 19:54:05 +05:30
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The ID of a merge request. |
| `target_branch` | string | no | The target branch. |
| `title` | string | no | Title of MR. |
2018-03-27 19:54:05 +05:30
| `assignee_id` | integer | no | The ID of the user to assign the merge request to. Set to `0` or provide an empty value to unassign all assignees. |
2019-09-30 21:07:59 +05:30
| `assignee_ids` | integer array | no | The ID of the user(s) to assign the MR to. Set to `0` or provide an empty value to unassign all assignees. |
2021-03-11 19:13:27 +05:30
| `reviewer_ids` | integer array | no | The ID of the user(s) set as a reviewer to the MR. Set the value to `0` or provide an empty value to unset all reviewers. |
2018-11-08 19:23:39 +05:30
| `milestone_id` | integer | no | The global ID of a milestone to assign the merge request to. Set to `0` or provide an empty value to unassign a milestone.|
2018-03-27 19:54:05 +05:30
| `labels` | string | no | Comma-separated label names for a merge request. Set to an empty string to unassign all labels. |
2020-05-24 23:13:21 +05:30
| `add_labels` | string | no | Comma-separated label names to add to a merge request. |
| `remove_labels` | string | no | Comma-separated label names to remove from a merge request. |
2019-12-21 20:55:43 +05:30
| `description` | string | no | Description of MR. Limited to 1,048,576 characters. |
2021-03-08 18:12:59 +05:30
| `state_event` | string | no | New state (close/reopen). |
| `remove_source_branch` | boolean | no | Flag indicating if a merge request should remove the source branch when merging. |
| `squash` | boolean | no | Squash commits into a single commit when merging. |
2018-03-27 19:54:05 +05:30
| `discussion_locked` | boolean | no | Flag indicating if the merge request's discussion is locked. If the discussion is locked only project members can add, edit or resolve comments. |
2021-03-08 18:12:59 +05:30
| `allow_collaboration` | boolean | no | Allow commits from members who can merge to the target branch. |
| `allow_maintainer_to_push` | boolean | no | Deprecated, see `allow_collaboration`. |
2017-08-17 22:00:37 +05:30
Must include at least one non-required attribute from above.
2014-09-02 18:07:02 +05:30
```json
{
"id": 1,
2016-08-24 12:49:21 +05:30
"iid": 1,
2018-12-05 23:21:45 +05:30
"project_id": 3,
2014-09-02 18:07:02 +05:30
"title": "test1",
2018-12-05 23:21:45 +05:30
"description": "fixed login page css paddings",
2018-12-13 13:39:08 +05:30
"state": "merged",
2018-12-05 23:21:45 +05:30
"created_at": "2017-04-29T08:46:00Z",
"updated_at": "2017-04-29T08:46:00Z",
"target_branch": "master",
"source_branch": "test1",
2014-09-02 18:07:02 +05:30
"upvotes": 0,
"downvotes": 0,
"author": {
"id": 1,
"name": "Administrator",
2018-12-05 23:21:45 +05:30
"username": "admin",
2014-09-02 18:07:02 +05:30
"state": "active",
2018-11-08 19:23:39 +05:30
"avatar_url": null,
"web_url" : "https://gitlab.example.com/admin"
2014-09-02 18:07:02 +05:30
},
"assignee": {
"id": 1,
"name": "Administrator",
2018-12-05 23:21:45 +05:30
"username": "admin",
2014-09-02 18:07:02 +05:30
"state": "active",
2018-11-08 19:23:39 +05:30
"avatar_url": null,
"web_url" : "https://gitlab.example.com/admin"
2016-04-02 18:10:28 +05:30
},
2019-07-31 22:56:46 +05:30
"assignees": [{
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
"web_url": "https://gitlab.example.com/axel.block"
}],
2021-03-11 19:13:27 +05:30
"reviewers": [{
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
"web_url": "https://gitlab.example.com/axel.block"
}],
2018-12-05 23:21:45 +05:30
"source_project_id": 2,
"target_project_id": 3,
"labels": [
"Community contribution",
"Manage"
],
2021-09-04 01:27:46 +05:30
"draft": false,
2016-04-02 18:10:28 +05:30
"work_in_progress": false,
"milestone": {
"id": 5,
"iid": 1,
2018-12-05 23:21:45 +05:30
"project_id": 3,
2016-04-02 18:10:28 +05:30
"title": "v2.0",
"description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.",
"state": "closed",
"created_at": "2015-02-02T19:49:26.013Z",
"updated_at": "2015-02-02T19:49:26.013Z",
2018-12-05 23:21:45 +05:30
"due_date": "2018-09-22",
"start_date": "2018-08-08",
"web_url": "https://gitlab.example.com/my-group/my-project/milestones/1"
2016-04-02 18:10:28 +05:30
},
2017-08-17 22:00:37 +05:30
"merge_when_pipeline_succeeds": true,
2016-06-02 11:05:42 +05:30
"merge_status": "can_be_merged",
2019-02-15 15:39:39 +05:30
"merge_error": null,
2016-09-29 09:46:39 +05:30
"sha": "8888888888888888888888888888888888888888",
"merge_commit_sha": null,
2019-12-26 22:10:19 +05:30
"squash_commit_sha": null,
2016-08-24 12:49:21 +05:30
"user_notes_count": 1,
2018-12-05 23:21:45 +05:30
"discussion_locked": null,
2016-08-24 12:49:21 +05:30
"should_remove_source_branch": true,
2016-09-29 09:46:39 +05:30
"force_remove_source_branch": false,
2018-11-08 19:23:39 +05:30
"allow_collaboration": false,
2018-03-27 19:54:05 +05:30
"allow_maintainer_to_push": false,
2018-12-05 23:21:45 +05:30
"web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
2020-03-13 15:44:24 +05:30
"references": {
"short": "!1",
"relative": "!1",
"full": "my-group/my-project!1"
},
2018-03-17 18:26:18 +05:30
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
2018-12-05 23:21:45 +05:30
},
"squash": false,
"subscribed": false,
"changes_count": "1",
"merged_by": {
"id": 87854,
"name": "Douwe Maan",
"username": "DouweM",
"state": "active",
"avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png",
"web_url": "https://gitlab.com/DouweM"
},
"merged_at": "2018-09-07T11:16:17.520Z",
"closed_by": null,
"closed_at": null,
"latest_build_started_at": "2018-09-07T07:27:38.472Z",
"latest_build_finished_at": "2018-09-07T08:07:06.012Z",
"first_deployed_to_production_at": null,
"pipeline": {
"id": 29626725,
"sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f",
"ref": "patch-28",
"status": "success",
"web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725"
},
"diff_refs": {
"base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00",
"head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f",
"start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00"
},
2019-09-04 21:01:54 +05:30
"diverged_commits_count": 2,
"task_completion_status":{
"count":0,
"completed_count":0
}
2014-09-02 18:07:02 +05:30
}
```
2021-03-11 19:13:27 +05:30
Users on GitLab Premium or higher also see
2019-09-30 21:07:59 +05:30
the `approvals_before_merge` parameter:
```json
{
"id": 1,
"title": "test1",
"approvals_before_merge": null
...
}
```
2016-06-02 11:05:42 +05:30
## Delete a merge request
2021-03-08 18:12:59 +05:30
Only for administrators and project owners. Deletes the merge request in question.
2016-06-02 11:05:42 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
DELETE /projects/:id/merge_requests/:merge_request_iid
2016-06-02 11:05:42 +05:30
```
2017-08-17 22:00:37 +05:30
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
2016-06-02 11:05:42 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/merge_requests/85"
2016-06-02 11:05:42 +05:30
```
2014-09-02 18:07:02 +05:30
## Accept MR
Merge changes submitted with MR using this API.
2014-09-02 18:07:02 +05:30
2021-03-08 18:12:59 +05:30
If a merge request is unable to be accepted (such as Draft, Closed, Pipeline Pending Completion, or Failed while requiring Success) - you receive a `405` and the error message 'Method Not Allowed'
2014-09-02 18:07:02 +05:30
2021-03-08 18:12:59 +05:30
If it has some conflicts and can not be merged - you receive a `406` and the error message 'Branch cannot be merged'
2021-03-08 18:12:59 +05:30
If the `sha` parameter is passed and does not match the HEAD of the source - you receive a `409` and the error message 'SHA does not match HEAD of source branch'
2014-09-02 18:07:02 +05:30
2021-03-08 18:12:59 +05:30
If you don't have permissions to accept this merge request - you receive a `401`
2014-09-02 18:07:02 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
PUT /projects/:id/merge_requests/:merge_request_iid/merge
2014-09-02 18:07:02 +05:30
```
Parameters:
2021-03-08 18:12:59 +05:30
| Attribute | Type | Required | Description |
|--------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
| `merge_commit_message` | string | no | Custom merge commit message. |
| `squash_commit_message` | string | no | Custom squash commit message. |
2021-03-11 19:13:27 +05:30
| `squash` | boolean | no | If `true` the commits are squashed into a single commit on merge. |
2021-03-08 18:12:59 +05:30
| `should_remove_source_branch` | boolean | no | If `true` removes the source branch. |
| `merge_when_pipeline_succeeds` | boolean | no | If `true` the MR is merged when the pipeline succeeds. |
| `sha` | string | no | If present, then this SHA must match the HEAD of the source branch, otherwise the merge fails. |
2015-12-23 02:04:40 +05:30
```json
{
"id": 1,
2016-08-24 12:49:21 +05:30
"iid": 1,
2015-12-23 02:04:40 +05:30
"project_id": 3,
"title": "test1",
2018-12-05 23:21:45 +05:30
"description": "fixed login page css paddings",
2018-12-13 13:39:08 +05:30
"state": "merged",
2018-12-05 23:21:45 +05:30
"created_at": "2017-04-29T08:46:00Z",
"updated_at": "2017-04-29T08:46:00Z",
"target_branch": "master",
"source_branch": "test1",
2015-12-23 02:04:40 +05:30
"upvotes": 0,
"downvotes": 0,
"author": {
"id": 1,
"name": "Administrator",
2018-12-05 23:21:45 +05:30
"username": "admin",
2015-12-23 02:04:40 +05:30
"state": "active",
2018-11-08 19:23:39 +05:30
"avatar_url": null,
"web_url" : "https://gitlab.example.com/admin"
2015-12-23 02:04:40 +05:30
},
"assignee": {
"id": 1,
"name": "Administrator",
2018-12-05 23:21:45 +05:30
"username": "admin",
2015-12-23 02:04:40 +05:30
"state": "active",
2018-11-08 19:23:39 +05:30
"avatar_url": null,
"web_url" : "https://gitlab.example.com/admin"
2016-04-02 18:10:28 +05:30
},
2019-07-31 22:56:46 +05:30
"assignees": [{
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
"web_url": "https://gitlab.example.com/axel.block"
}],
2021-03-11 19:13:27 +05:30
"reviewers": [{
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
"web_url": "https://gitlab.example.com/axel.block"
}],
2018-12-05 23:21:45 +05:30
"source_project_id": 2,
"target_project_id": 3,
"labels": [
"Community contribution",
"Manage"
],
2021-09-04 01:27:46 +05:30
"draft": false,
2016-04-02 18:10:28 +05:30
"work_in_progress": false,
"milestone": {
"id": 5,
"iid": 1,
2018-12-05 23:21:45 +05:30
"project_id": 3,
2016-04-02 18:10:28 +05:30
"title": "v2.0",
"description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.",
"state": "closed",
"created_at": "2015-02-02T19:49:26.013Z",
"updated_at": "2015-02-02T19:49:26.013Z",
2018-12-05 23:21:45 +05:30
"due_date": "2018-09-22",
"start_date": "2018-08-08",
"web_url": "https://gitlab.example.com/my-group/my-project/milestones/1"
2016-04-02 18:10:28 +05:30
},
2017-08-17 22:00:37 +05:30
"merge_when_pipeline_succeeds": true,
2016-06-02 11:05:42 +05:30
"merge_status": "can_be_merged",
2019-02-15 15:39:39 +05:30
"merge_error": null,
2016-09-29 09:46:39 +05:30
"sha": "8888888888888888888888888888888888888888",
2018-12-05 23:21:45 +05:30
"merge_commit_sha": null,
2019-12-26 22:10:19 +05:30
"squash_commit_sha": null,
2016-08-24 12:49:21 +05:30
"user_notes_count": 1,
2018-12-05 23:21:45 +05:30
"discussion_locked": null,
2016-08-24 12:49:21 +05:30
"should_remove_source_branch": true,
2016-09-29 09:46:39 +05:30
"force_remove_source_branch": false,
2018-12-05 23:21:45 +05:30
"allow_collaboration": false,
"allow_maintainer_to_push": false,
"web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
2020-03-13 15:44:24 +05:30
"references": {
"short": "!1",
"relative": "!1",
"full": "my-group/my-project!1"
},
2018-03-17 18:26:18 +05:30
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
2018-12-05 23:21:45 +05:30
},
"squash": false,
"subscribed": false,
"changes_count": "1",
"merged_by": {
"id": 87854,
"name": "Douwe Maan",
"username": "DouweM",
"state": "active",
"avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png",
"web_url": "https://gitlab.com/DouweM"
},
"merged_at": "2018-09-07T11:16:17.520Z",
"closed_by": null,
"closed_at": null,
"latest_build_started_at": "2018-09-07T07:27:38.472Z",
"latest_build_finished_at": "2018-09-07T08:07:06.012Z",
"first_deployed_to_production_at": null,
"pipeline": {
"id": 29626725,
"sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f",
"ref": "patch-28",
"status": "success",
"web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725"
},
"diff_refs": {
"base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00",
"head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f",
"start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00"
},
2019-09-04 21:01:54 +05:30
"diverged_commits_count": 2,
"task_completion_status":{
"count":0,
"completed_count":0
}
2015-12-23 02:04:40 +05:30
}
```
2021-03-11 19:13:27 +05:30
Users on GitLab Premium also see
2019-09-30 21:07:59 +05:30
the `approvals_before_merge` parameter:
```json
{
"id": 1,
"title": "test1",
"approvals_before_merge": null
...
}
```
2019-07-07 11:18:12 +05:30
## Merge to default merge ref path
2019-09-30 21:07:59 +05:30
Merge the changes between the merge request source and target branches into `refs/merge-requests/:iid/merge`
2021-03-08 18:12:59 +05:30
ref, of the target project repository, if possible. This ref has the state the target branch would have if
2019-07-07 11:18:12 +05:30
a regular merge action was taken.
2019-09-30 21:07:59 +05:30
This is not a regular merge action given it doesn't change the merge request target branch state in any manner.
2019-07-07 11:18:12 +05:30
2019-09-30 21:07:59 +05:30
This ref (`refs/merge-requests/:iid/merge`) isn't necessarily overwritten when submitting
2021-03-08 18:12:59 +05:30
requests to this API, though it makes sure the ref has the latest possible state.
2019-07-07 11:18:12 +05:30
2021-03-08 18:12:59 +05:30
If the merge request has conflicts, is empty or already merged, you receive a `400` and a descriptive error message.
2019-07-07 11:18:12 +05:30
2019-09-30 21:07:59 +05:30
It returns the HEAD commit of `refs/merge-requests/:iid/merge` in the response body in case of `200`.
2019-07-07 11:18:12 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2019-09-30 21:07:59 +05:30
GET /projects/:id/merge_requests/:merge_request_iid/merge_ref
2019-07-07 11:18:12 +05:30
```
Parameters:
2021-03-08 18:12:59 +05:30
| Attribute | Type | Required | Description |
|--------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
2019-07-07 11:18:12 +05:30
```json
{
"commit_id": "854a3a7a17acbcc0bbbea170986df1eb60435f34"
}
```
2017-08-17 22:00:37 +05:30
## Cancel Merge When Pipeline Succeeds
2015-12-23 02:04:40 +05:30
2021-03-08 18:12:59 +05:30
- If you don't have permissions to accept this merge request - you receive a `HTTP 401 Unauthorized`.
- If the merge request is already merged or closed - you receive a `HTTP 405 Method Not Allowed` and the error message 'Method Not Allowed'.
- In case the merge request is not set to be merged when the pipeline succeeds, you also receive a `HTTP 406 Not Acceptable` error.
2019-09-30 21:07:59 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2020-01-01 13:55:28 +05:30
POST /projects/:id/merge_requests/:merge_request_iid/cancel_merge_when_pipeline_succeeds
2015-12-23 02:04:40 +05:30
```
2019-09-30 21:07:59 +05:30
2015-12-23 02:04:40 +05:30
Parameters:
2021-03-08 18:12:59 +05:30
| Attribute | Type | Required | Description |
|--------------------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------|
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
2014-09-02 18:07:02 +05:30
```json
{
"id": 1,
2016-08-24 12:49:21 +05:30
"iid": 1,
2014-09-02 18:07:02 +05:30
"project_id": 3,
"title": "test1",
2018-12-05 23:21:45 +05:30
"description": "fixed login page css paddings",
2018-12-13 13:39:08 +05:30
"state": "merged",
2018-12-05 23:21:45 +05:30
"created_at": "2017-04-29T08:46:00Z",
"updated_at": "2017-04-29T08:46:00Z",
"target_branch": "master",
"source_branch": "test1",
2014-09-02 18:07:02 +05:30
"upvotes": 0,
"downvotes": 0,
"author": {
"id": 1,
"name": "Administrator",
2018-12-05 23:21:45 +05:30
"username": "admin",
2014-09-02 18:07:02 +05:30
"state": "active",
2018-11-08 19:23:39 +05:30
"avatar_url": null,
"web_url" : "https://gitlab.example.com/admin"
2014-09-02 18:07:02 +05:30
},
"assignee": {
"id": 1,
"name": "Administrator",
2018-12-05 23:21:45 +05:30
"username": "admin",
2014-09-02 18:07:02 +05:30
"state": "active",
2018-11-08 19:23:39 +05:30
"avatar_url": null,
"web_url" : "https://gitlab.example.com/admin"
2016-04-02 18:10:28 +05:30
},
2019-07-31 22:56:46 +05:30
"assignees": [{
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
"web_url": "https://gitlab.example.com/axel.block"
}],
2021-03-11 19:13:27 +05:30
"reviewers": [{
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
"web_url": "https://gitlab.example.com/axel.block"
}],
2018-12-05 23:21:45 +05:30
"source_project_id": 2,
"target_project_id": 3,
"labels": [
"Community contribution",
"Manage"
],
2021-09-04 01:27:46 +05:30
"draft": false,
2016-04-02 18:10:28 +05:30
"work_in_progress": false,
"milestone": {
"id": 5,
"iid": 1,
2018-12-05 23:21:45 +05:30
"project_id": 3,
2016-04-02 18:10:28 +05:30
"title": "v2.0",
"description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.",
"state": "closed",
"created_at": "2015-02-02T19:49:26.013Z",
"updated_at": "2015-02-02T19:49:26.013Z",
2018-12-05 23:21:45 +05:30
"due_date": "2018-09-22",
"start_date": "2018-08-08",
"web_url": "https://gitlab.example.com/my-group/my-project/milestones/1"
2016-04-02 18:10:28 +05:30
},
2018-12-05 23:21:45 +05:30
"merge_when_pipeline_succeeds": false,
2016-06-02 11:05:42 +05:30
"merge_status": "can_be_merged",
2019-02-15 15:39:39 +05:30
"merge_error": null,
2016-09-29 09:46:39 +05:30
"sha": "8888888888888888888888888888888888888888",
"merge_commit_sha": null,
2019-12-26 22:10:19 +05:30
"squash_commit_sha": null,
2016-08-24 12:49:21 +05:30
"user_notes_count": 1,
2018-12-05 23:21:45 +05:30
"discussion_locked": null,
2016-08-24 12:49:21 +05:30
"should_remove_source_branch": true,
2016-09-29 09:46:39 +05:30
"force_remove_source_branch": false,
2018-12-05 23:21:45 +05:30
"allow_collaboration": false,
"allow_maintainer_to_push": false,
"web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
2020-03-13 15:44:24 +05:30
"references": {
"short": "!1",
"relative": "!1",
"full": "my-group/my-project!1"
},
2018-03-17 18:26:18 +05:30
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
2018-12-05 23:21:45 +05:30
},
"squash": false,
"subscribed": false,
"changes_count": "1",
"merged_by": {
"id": 87854,
"name": "Douwe Maan",
"username": "DouweM",
"state": "active",
"avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png",
"web_url": "https://gitlab.com/DouweM"
},
"merged_at": "2018-09-07T11:16:17.520Z",
"closed_by": null,
"closed_at": null,
"latest_build_started_at": "2018-09-07T07:27:38.472Z",
"latest_build_finished_at": "2018-09-07T08:07:06.012Z",
"first_deployed_to_production_at": null,
"pipeline": {
"id": 29626725,
"sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f",
"ref": "patch-28",
"status": "success",
"web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725"
},
"diff_refs": {
"base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00",
"head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f",
"start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00"
},
2019-09-04 21:01:54 +05:30
"diverged_commits_count": 2,
"task_completion_status":{
"count":0,
"completed_count":0
}
2014-09-02 18:07:02 +05:30
}
```
2021-03-11 19:13:27 +05:30
Users on GitLab Premium or higher also see
2019-09-30 21:07:59 +05:30
the `approvals_before_merge` parameter:
```json
{
"id": 1,
"title": "test1",
"approvals_before_merge": null
...
}
```
2019-02-15 15:39:39 +05:30
## Rebase a merge request
Automatically rebase the `source_branch` of the merge request against its
`target_branch`.
If you don't have permissions to push to the merge request's source branch -
2021-03-08 18:12:59 +05:30
you receive a `403 Forbidden` response.
2019-02-15 15:39:39 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2019-02-15 15:39:39 +05:30
PUT /projects/:id/merge_requests/:merge_request_iid/rebase
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
| `skip_ci` | boolean | no | Set to `true` to skip creating a CI pipeline. |
2019-02-15 15:39:39 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/76/merge_requests/1/rebase"
2019-02-15 15:39:39 +05:30
```
2021-03-08 18:12:59 +05:30
This is an asynchronous request. The API returns a `HTTP 202 Accepted` response
2019-09-30 21:07:59 +05:30
if the request is enqueued successfully, with a response containing:
```json
{
"rebase_in_progress": true
}
```
2019-02-15 15:39:39 +05:30
You can poll the [Get single MR](#get-single-mr) endpoint with the
`include_rebase_in_progress` parameter to check the status of the
asynchronous request.
2021-03-08 18:12:59 +05:30
If the rebase operation is ongoing, the response includes the following:
2019-02-15 15:39:39 +05:30
```json
{
2019-09-04 21:01:54 +05:30
"rebase_in_progress": true,
2019-02-15 15:39:39 +05:30
"merge_error": null
}
```
2021-03-08 18:12:59 +05:30
After the rebase operation has completed successfully, the response includes
2019-02-15 15:39:39 +05:30
the following:
```json
{
"rebase_in_progress": false,
2019-09-04 21:01:54 +05:30
"merge_error": null
2019-02-15 15:39:39 +05:30
}
```
2021-03-08 18:12:59 +05:30
If the rebase operation fails, the response includes the following:
2019-02-15 15:39:39 +05:30
```json
{
"rebase_in_progress": false,
2019-09-04 21:01:54 +05:30
"merge_error": "Rebase failed. Please rebase locally"
2019-02-15 15:39:39 +05:30
}
```
2016-06-02 11:05:42 +05:30
## Comments on merge requests
2014-09-02 18:07:02 +05:30
2016-04-02 18:10:28 +05:30
Comments are done via the [notes](notes.md) resource.
2014-09-02 18:07:02 +05:30
2021-03-08 18:12:59 +05:30
## List issues that close on merge
2014-09-02 18:07:02 +05:30
2016-04-02 18:10:28 +05:30
Get all the issues that would be closed by merging the provided merge request.
2014-09-02 18:07:02 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
GET /projects/:id/merge_requests/:merge_request_iid/closes_issues
2014-09-02 18:07:02 +05:30
```
2017-08-17 22:00:37 +05:30
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
2014-09-02 18:07:02 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/76/merge_requests/1/closes_issues"
2014-09-02 18:07:02 +05:30
```
Example response when the GitLab issue tracker is used:
2014-09-02 18:07:02 +05:30
```json
[
2016-04-02 18:10:28 +05:30
{
"state" : "opened",
"description" : "Ratione dolores corrupti mollitia soluta quia.",
"author" : {
"state" : "active",
"id" : 18,
2016-11-03 12:29:30 +05:30
"web_url" : "https://gitlab.example.com/eileen.lowe",
2016-04-02 18:10:28 +05:30
"name" : "Alexandra Bashirian",
"avatar_url" : null,
"username" : "eileen.lowe"
},
"milestone" : {
"project_id" : 1,
"description" : "Ducimus nam enim ex consequatur cumque ratione.",
"state" : "closed",
"due_date" : null,
"iid" : 2,
"created_at" : "2016-01-04T15:31:39.996Z",
"title" : "v4.0",
"id" : 17,
"updated_at" : "2016-01-04T15:31:39.996Z"
},
"project_id" : 1,
"assignee" : {
"state" : "active",
"id" : 1,
"name" : "Administrator",
2016-11-03 12:29:30 +05:30
"web_url" : "https://gitlab.example.com/root",
2016-04-02 18:10:28 +05:30
"avatar_url" : null,
"username" : "root"
},
"updated_at" : "2016-01-04T15:31:51.081Z",
"id" : 76,
"title" : "Consequatur vero maxime deserunt laboriosam est voluptas dolorem.",
"created_at" : "2016-01-04T15:31:51.081Z",
"iid" : 6,
2016-06-02 11:05:42 +05:30
"labels" : [],
2018-03-17 18:26:18 +05:30
"user_notes_count": 1,
"changes_count": "1"
2018-12-05 23:21:45 +05:30
}
2014-09-02 18:07:02 +05:30
]
```
2016-06-02 11:05:42 +05:30
2021-03-08 18:12:59 +05:30
Example response when an external issue tracker (for example, Jira) is used:
```json
[
{
"id" : "PROJECT-123",
"title" : "Title of this issue"
}
]
```
2016-06-02 11:05:42 +05:30
## Subscribe to a merge request
2017-08-17 22:00:37 +05:30
Subscribes the authenticated user to a merge request to receive notification. If the user is already subscribed to the merge request, the
2021-03-08 18:12:59 +05:30
status code `HTTP 304 Not Modified` is returned.
2016-06-02 11:05:42 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
POST /projects/:id/merge_requests/:merge_request_iid/subscribe
2016-06-02 11:05:42 +05:30
```
2017-08-17 22:00:37 +05:30
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
2016-06-02 11:05:42 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/17/subscribe"
2016-06-02 11:05:42 +05:30
```
Example response:
```json
{
2018-12-05 23:21:45 +05:30
"id": 1,
2016-06-02 11:05:42 +05:30
"iid": 1,
2018-12-05 23:21:45 +05:30
"project_id": 3,
"title": "test1",
"description": "fixed login page css paddings",
2018-12-13 13:39:08 +05:30
"state": "merged",
2018-12-05 23:21:45 +05:30
"created_at": "2017-04-29T08:46:00Z",
"updated_at": "2017-04-29T08:46:00Z",
"target_branch": "master",
"source_branch": "test1",
2016-06-02 11:05:42 +05:30
"upvotes": 0,
"downvotes": 0,
"author": {
2018-12-05 23:21:45 +05:30
"id": 1,
"name": "Administrator",
"username": "admin",
2016-06-02 11:05:42 +05:30
"state": "active",
2018-12-05 23:21:45 +05:30
"avatar_url": null,
"web_url" : "https://gitlab.example.com/admin"
2016-06-02 11:05:42 +05:30
},
"assignee": {
2018-12-05 23:21:45 +05:30
"id": 1,
"name": "Administrator",
"username": "admin",
2016-06-02 11:05:42 +05:30
"state": "active",
2018-12-05 23:21:45 +05:30
"avatar_url": null,
"web_url" : "https://gitlab.example.com/admin"
2016-06-02 11:05:42 +05:30
},
2019-07-31 22:56:46 +05:30
"assignees": [{
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
"web_url": "https://gitlab.example.com/axel.block"
}],
2021-03-11 19:13:27 +05:30
"reviewers": [{
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
"web_url": "https://gitlab.example.com/axel.block"
}],
2018-12-05 23:21:45 +05:30
"source_project_id": 2,
"target_project_id": 3,
"labels": [
"Community contribution",
"Manage"
],
2021-09-04 01:27:46 +05:30
"draft": false,
2016-06-02 11:05:42 +05:30
"work_in_progress": false,
"milestone": {
2018-12-05 23:21:45 +05:30
"id": 5,
2016-06-02 11:05:42 +05:30
"iid": 1,
2018-12-05 23:21:45 +05:30
"project_id": 3,
2016-06-02 11:05:42 +05:30
"title": "v2.0",
2018-12-05 23:21:45 +05:30
"description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.",
2016-06-02 11:05:42 +05:30
"state": "closed",
2018-12-05 23:21:45 +05:30
"created_at": "2015-02-02T19:49:26.013Z",
"updated_at": "2015-02-02T19:49:26.013Z",
"due_date": "2018-09-22",
"start_date": "2018-08-08",
"web_url": "https://gitlab.example.com/my-group/my-project/milestones/1"
2016-06-02 11:05:42 +05:30
},
2018-12-05 23:21:45 +05:30
"merge_when_pipeline_succeeds": true,
"merge_status": "can_be_merged",
2016-09-29 09:46:39 +05:30
"sha": "8888888888888888888888888888888888888888",
2018-12-05 23:21:45 +05:30
"merge_commit_sha": null,
2019-12-26 22:10:19 +05:30
"squash_commit_sha": null,
2018-12-05 23:21:45 +05:30
"user_notes_count": 1,
"discussion_locked": null,
"should_remove_source_branch": true,
"force_remove_source_branch": false,
"allow_collaboration": false,
"allow_maintainer_to_push": false,
"web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
2020-03-13 15:44:24 +05:30
"references": {
"short": "!1",
"relative": "!1",
"full": "my-group/my-project!1"
},
2018-12-05 23:21:45 +05:30
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"squash": false,
"subscribed": false,
"changes_count": "1",
"merged_by": {
"id": 87854,
"name": "Douwe Maan",
"username": "DouweM",
"state": "active",
"avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png",
"web_url": "https://gitlab.com/DouweM"
},
"merged_at": "2018-09-07T11:16:17.520Z",
"closed_by": null,
"closed_at": null,
"latest_build_started_at": "2018-09-07T07:27:38.472Z",
"latest_build_finished_at": "2018-09-07T08:07:06.012Z",
"first_deployed_to_production_at": null,
"pipeline": {
"id": 29626725,
"sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f",
"ref": "patch-28",
"status": "success",
"web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725"
},
"diff_refs": {
"base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00",
"head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f",
"start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00"
},
2019-09-04 21:01:54 +05:30
"diverged_commits_count": 2,
"task_completion_status":{
"count":0,
"completed_count":0
}
2016-06-02 11:05:42 +05:30
}
```
2021-03-11 19:13:27 +05:30
Users on GitLab Premium also see
2019-09-30 21:07:59 +05:30
the `approvals_before_merge` parameter:
```json
{
"id": 1,
"title": "test1",
"approvals_before_merge": null
...
}
```
2016-06-02 11:05:42 +05:30
## Unsubscribe from a merge request
Unsubscribes the authenticated user from a merge request to not receive
2017-08-17 22:00:37 +05:30
notifications from that merge request. If the user is
2021-03-08 18:12:59 +05:30
not subscribed to the merge request, the status code `HTTP 304 Not Modified` is returned.
2016-06-02 11:05:42 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
POST /projects/:id/merge_requests/:merge_request_iid/unsubscribe
2016-06-02 11:05:42 +05:30
```
2017-08-17 22:00:37 +05:30
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
2016-06-02 11:05:42 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/17/unsubscribe"
2016-06-02 11:05:42 +05:30
```
Example response:
```json
{
2018-12-05 23:21:45 +05:30
"id": 1,
2016-06-02 11:05:42 +05:30
"iid": 1,
2018-12-05 23:21:45 +05:30
"project_id": 3,
"title": "test1",
"description": "fixed login page css paddings",
2018-12-13 13:39:08 +05:30
"state": "merged",
2018-12-05 23:21:45 +05:30
"created_at": "2017-04-29T08:46:00Z",
"updated_at": "2017-04-29T08:46:00Z",
"target_branch": "master",
"source_branch": "test1",
2016-06-02 11:05:42 +05:30
"upvotes": 0,
"downvotes": 0,
"author": {
2018-12-05 23:21:45 +05:30
"id": 1,
"name": "Administrator",
"username": "admin",
2016-06-02 11:05:42 +05:30
"state": "active",
2018-12-05 23:21:45 +05:30
"avatar_url": null,
"web_url" : "https://gitlab.example.com/admin"
2016-06-02 11:05:42 +05:30
},
"assignee": {
2018-12-05 23:21:45 +05:30
"id": 1,
"name": "Administrator",
"username": "admin",
2016-06-02 11:05:42 +05:30
"state": "active",
2018-12-05 23:21:45 +05:30
"avatar_url": null,
"web_url" : "https://gitlab.example.com/admin"
2016-06-02 11:05:42 +05:30
},
2019-07-31 22:56:46 +05:30
"assignees": [{
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
"web_url": "https://gitlab.example.com/axel.block"
}],
2021-03-11 19:13:27 +05:30
"reviewers": [{
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
"web_url": "https://gitlab.example.com/axel.block"
}],
2018-12-05 23:21:45 +05:30
"source_project_id": 2,
"target_project_id": 3,
"labels": [
"Community contribution",
"Manage"
],
2021-09-04 01:27:46 +05:30
"draft": false,
2016-06-02 11:05:42 +05:30
"work_in_progress": false,
"milestone": {
2018-12-05 23:21:45 +05:30
"id": 5,
2016-06-02 11:05:42 +05:30
"iid": 1,
2018-12-05 23:21:45 +05:30
"project_id": 3,
2016-06-02 11:05:42 +05:30
"title": "v2.0",
2018-12-05 23:21:45 +05:30
"description": "Assumenda aut placeat expedita exercitationem labore sunt enim earum.",
2016-06-02 11:05:42 +05:30
"state": "closed",
2018-12-05 23:21:45 +05:30
"created_at": "2015-02-02T19:49:26.013Z",
"updated_at": "2015-02-02T19:49:26.013Z",
"due_date": "2018-09-22",
"start_date": "2018-08-08",
"web_url": "https://gitlab.example.com/my-group/my-project/milestones/1"
2016-06-02 11:05:42 +05:30
},
2018-12-05 23:21:45 +05:30
"merge_when_pipeline_succeeds": true,
"merge_status": "can_be_merged",
2016-09-29 09:46:39 +05:30
"sha": "8888888888888888888888888888888888888888",
2018-12-05 23:21:45 +05:30
"merge_commit_sha": null,
2019-12-26 22:10:19 +05:30
"squash_commit_sha": null,
2018-12-05 23:21:45 +05:30
"user_notes_count": 1,
"discussion_locked": null,
"should_remove_source_branch": true,
"force_remove_source_branch": false,
"allow_collaboration": false,
"allow_maintainer_to_push": false,
"web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1",
2020-03-13 15:44:24 +05:30
"references": {
"short": "!1",
"relative": "!1",
"full": "my-group/my-project!1"
},
2018-12-05 23:21:45 +05:30
"time_stats": {
"time_estimate": 0,
"total_time_spent": 0,
"human_time_estimate": null,
"human_total_time_spent": null
},
"squash": false,
"subscribed": false,
"changes_count": "1",
"merged_by": {
"id": 87854,
"name": "Douwe Maan",
"username": "DouweM",
"state": "active",
"avatar_url": "https://gitlab.example.com/uploads/-/system/user/avatar/87854/avatar.png",
"web_url": "https://gitlab.com/DouweM"
},
"merged_at": "2018-09-07T11:16:17.520Z",
"closed_by": null,
"closed_at": null,
"latest_build_started_at": "2018-09-07T07:27:38.472Z",
"latest_build_finished_at": "2018-09-07T08:07:06.012Z",
"first_deployed_to_production_at": null,
"pipeline": {
"id": 29626725,
"sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f",
"ref": "patch-28",
"status": "success",
"web_url": "https://gitlab.example.com/my-group/my-project/pipelines/29626725"
},
"diff_refs": {
"base_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00",
"head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f",
"start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00"
},
2019-09-04 21:01:54 +05:30
"diverged_commits_count": 2,
"task_completion_status":{
"count":0,
"completed_count":0
}
2016-06-02 11:05:42 +05:30
}
```
2016-08-24 12:49:21 +05:30
2021-03-11 19:13:27 +05:30
Users on GitLab Premium or higher also see
2019-09-30 21:07:59 +05:30
the `approvals_before_merge` parameter:
```json
{
"id": 1,
"title": "test1",
"approvals_before_merge": null
...
}
```
2021-01-29 00:20:46 +05:30
## Create a to-do item
2016-08-24 12:49:21 +05:30
2021-01-29 00:20:46 +05:30
Manually creates a to-do item for the current user on a merge request.
If there already exists a to-do item for the user on that merge request,
2021-03-08 18:12:59 +05:30
status code `HTTP 304 Not Modified` is returned.
2016-08-24 12:49:21 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
POST /projects/:id/merge_requests/:merge_request_iid/todo
2016-08-24 12:49:21 +05:30
```
2017-08-17 22:00:37 +05:30
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
2016-08-24 12:49:21 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/27/todo"
2016-08-24 12:49:21 +05:30
```
Example response:
```json
{
"id": 113,
"project": {
"id": 3,
2020-04-22 19:07:51 +05:30
"name": "GitLab CI/CD",
"name_with_namespace": "GitLab Org / GitLab CI/CD",
2016-08-24 12:49:21 +05:30
"path": "gitlab-ci",
"path_with_namespace": "gitlab-org/gitlab-ci"
},
"author": {
"name": "Administrator",
"username": "root",
"id": 1,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
2016-11-03 12:29:30 +05:30
"web_url": "https://gitlab.example.com/root"
2016-08-24 12:49:21 +05:30
},
"action_name": "marked",
"target_type": "MergeRequest",
"target": {
"id": 27,
"iid": 7,
"project_id": 3,
"title": "Et voluptas laudantium minus nihil recusandae ut accusamus earum aut non.",
"description": "Veniam sunt nihil modi earum cumque illum delectus. Nihil ad quis distinctio quia. Autem eligendi at quibusdam repellendus.",
2018-12-13 13:39:08 +05:30
"state": "merged",
2016-08-24 12:49:21 +05:30
"created_at": "2016-06-17T07:48:04.330Z",
"updated_at": "2016-07-01T11:14:15.537Z",
"target_branch": "allow_regex_for_project_skip_ref",
"source_branch": "backup",
"upvotes": 0,
"downvotes": 0,
"author": {
"name": "Jarret O'Keefe",
"username": "francisca",
"id": 14,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/a7fa515d53450023c83d62986d0658a8?s=80&d=identicon",
2018-03-17 18:26:18 +05:30
"web_url": "https://gitlab.example.com/francisca",
"discussion_locked": false
2016-08-24 12:49:21 +05:30
},
"assignee": {
"name": "Dr. Gabrielle Strosin",
"username": "barrett.krajcik",
"id": 4,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/733005fcd7e6df12d2d8580171ccb966?s=80&d=identicon",
2016-11-03 12:29:30 +05:30
"web_url": "https://gitlab.example.com/barrett.krajcik"
2016-08-24 12:49:21 +05:30
},
2019-07-31 22:56:46 +05:30
"assignees": [{
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
"web_url": "https://gitlab.example.com/axel.block"
}],
2021-03-11 19:13:27 +05:30
"reviewers": [{
"name": "Miss Monserrate Beier",
"username": "axel.block",
"id": 12,
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon",
"web_url": "https://gitlab.example.com/axel.block"
}],
2016-08-24 12:49:21 +05:30
"source_project_id": 3,
"target_project_id": 3,
"labels": [],
2021-09-04 01:27:46 +05:30
"draft": false,
2016-08-24 12:49:21 +05:30
"work_in_progress": false,
"milestone": {
"id": 27,
"iid": 2,
"project_id": 3,
"title": "v1.0",
"description": "Quis ea accusantium animi hic fuga assumenda.",
"state": "active",
"created_at": "2016-06-17T07:47:33.840Z",
"updated_at": "2016-06-17T07:47:33.840Z",
"due_date": null
},
2017-08-17 22:00:37 +05:30
"merge_when_pipeline_succeeds": false,
2016-08-24 12:49:21 +05:30
"merge_status": "unchecked",
"subscribed": true,
2016-09-29 09:46:39 +05:30
"sha": "8888888888888888888888888888888888888888",
"merge_commit_sha": null,
2019-12-26 22:10:19 +05:30
"squash_commit_sha": null,
2016-08-24 12:49:21 +05:30
"user_notes_count": 7,
2018-03-17 18:26:18 +05:30
"changes_count": "1",
2016-08-24 12:49:21 +05:30
"should_remove_source_branch": true,
2016-09-29 09:46:39 +05:30
"force_remove_source_branch": false,
2018-11-08 19:23:39 +05:30
"squash": false,
2020-03-13 15:44:24 +05:30
"web_url": "http://example.com/my-group/my-project/merge_requests/1",
"references": {
"short": "!1",
"relative": "!1",
"full": "my-group/my-project!1"
2021-06-08 01:23:25 +05:30
}
2016-08-24 12:49:21 +05:30
},
"target_url": "https://gitlab.example.com/gitlab-org/gitlab-ci/merge_requests/7",
"body": "Et voluptas laudantium minus nihil recusandae ut accusamus earum aut non.",
"state": "pending",
"created_at": "2016-07-01T11:14:15.530Z"
}
```
2016-09-29 09:46:39 +05:30
## Get MR diff versions
2021-04-29 21:17:54 +05:30
Get a list of merge request diff versions. For an explanation of the SHAs in the response,
read [SHAs in the API response](#shas-in-the-api-response).
2016-09-29 09:46:39 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
GET /projects/:id/merge_requests/:merge_request_iid/versions
2016-09-29 09:46:39 +05:30
```
2017-08-17 22:00:37 +05:30
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
2021-03-08 18:12:59 +05:30
| `id` | String | yes | The ID of the project. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
2016-09-29 09:46:39 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/merge_requests/1/versions"
2016-09-29 09:46:39 +05:30
```
Example response:
```json
[{
"id": 110,
"head_commit_sha": "33e2ee8579fda5bc36accc9c6fbd0b4fefda9e30",
"base_commit_sha": "eeb57dffe83deb686a60a71c16c32f71046868fd",
"start_commit_sha": "eeb57dffe83deb686a60a71c16c32f71046868fd",
"created_at": "2016-07-26T14:44:48.926Z",
"merge_request_id": 105,
"state": "collected",
"real_size": "1"
}, {
"id": 108,
"head_commit_sha": "3eed087b29835c48015768f839d76e5ea8f07a24",
"base_commit_sha": "eeb57dffe83deb686a60a71c16c32f71046868fd",
"start_commit_sha": "eeb57dffe83deb686a60a71c16c32f71046868fd",
"created_at": "2016-07-25T14:21:33.028Z",
"merge_request_id": 105,
"state": "collected",
"real_size": "1"
}]
```
2021-04-29 21:17:54 +05:30
### SHAs in the API response
- `head_commit_sha`: The HEAD commit of the source branch.
- `base_commit_sha`: The merge-base commit SHA between the source branch and the target branches.
- `start_commit_sha`: The HEAD commit SHA of the target branch when this version of the diff was created.
2016-09-29 09:46:39 +05:30
## Get a single MR diff version
2021-04-29 21:17:54 +05:30
Get a single merge request diff version. For an explanation of the SHAs in the response,
read [SHAs in the API response](#shas-in-the-api-response).
2016-09-29 09:46:39 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
GET /projects/:id/merge_requests/:merge_request_iid/versions/:version_id
2016-09-29 09:46:39 +05:30
```
2017-08-17 22:00:37 +05:30
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
2021-03-08 18:12:59 +05:30
| `id` | String | yes | The ID of the project. |
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
| `version_id` | integer | yes | The ID of the merge request diff version. |
2016-09-29 09:46:39 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/merge_requests/1/versions/1"
2016-09-29 09:46:39 +05:30
```
Example response:
```json
{
"id": 110,
"head_commit_sha": "33e2ee8579fda5bc36accc9c6fbd0b4fefda9e30",
"base_commit_sha": "eeb57dffe83deb686a60a71c16c32f71046868fd",
"start_commit_sha": "eeb57dffe83deb686a60a71c16c32f71046868fd",
"created_at": "2016-07-26T14:44:48.926Z",
"merge_request_id": 105,
"state": "collected",
"real_size": "1",
"commits": [{
"id": "33e2ee8579fda5bc36accc9c6fbd0b4fefda9e30",
"short_id": "33e2ee85",
"title": "Change year to 2018",
"author_name": "Administrator",
"author_email": "admin@example.com",
"created_at": "2016-07-26T17:44:29.000+03:00",
"message": "Change year to 2018"
}, {
"id": "aa24655de48b36335556ac8a3cd8bb521f977cbd",
"short_id": "aa24655d",
"title": "Update LICENSE",
"author_name": "Administrator",
"author_email": "admin@example.com",
"created_at": "2016-07-25T17:21:53.000+03:00",
"message": "Update LICENSE"
}, {
"id": "3eed087b29835c48015768f839d76e5ea8f07a24",
"short_id": "3eed087b",
"title": "Add license",
"author_name": "Administrator",
"author_email": "admin@example.com",
"created_at": "2016-07-25T17:21:20.000+03:00",
"message": "Add license"
}],
"diffs": [{
"old_path": "LICENSE",
"new_path": "LICENSE",
"a_mode": "0",
"b_mode": "100644",
"diff": "--- /dev/null\n+++ b/LICENSE\n@@ -0,0 +1,21 @@\n+The MIT License (MIT)\n+\n+Copyright (c) 2018 Administrator\n+\n+Permission is hereby granted, free of charge, to any person obtaining a copy\n+of this software and associated documentation files (the \"Software\"), to deal\n+in the Software without restriction, including without limitation the rights\n+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n+copies of the Software, and to permit persons to whom the Software is\n+furnished to do so, subject to the following conditions:\n+\n+The above copyright notice and this permission notice shall be included in all\n+copies or substantial portions of the Software.\n+\n+THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n+SOFTWARE.\n",
"new_file": true,
"renamed_file": false,
"deleted_file": false
}]
}
```
2019-09-30 21:07:59 +05:30
2017-08-17 22:00:37 +05:30
## Set a time estimate for a merge request
Sets an estimated time of work for this merge request.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
POST /projects/:id/merge_requests/:merge_request_iid/time_estimate
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
| `duration` | string | yes | The duration in human format, such as `3h30m`. |
2017-08-17 22:00:37 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/93/time_estimate?duration=3h30m"
2017-08-17 22:00:37 +05:30
```
Example response:
```json
{
"human_time_estimate": "3h 30m",
"human_total_time_spent": null,
"time_estimate": 12600,
"total_time_spent": 0
}
```
## Reset the time estimate for a merge request
Resets the estimated time for this merge request to 0 seconds.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
POST /projects/:id/merge_requests/:merge_request_iid/reset_time_estimate
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The internal ID of a project's merge_request. |
2017-08-17 22:00:37 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/93/reset_time_estimate"
2017-08-17 22:00:37 +05:30
```
Example response:
```json
{
"human_time_estimate": null,
"human_total_time_spent": null,
"time_estimate": 0,
"total_time_spent": 0
}
```
## Add spent time for a merge request
2021-03-08 18:12:59 +05:30
Adds spent time for this merge request.
2017-08-17 22:00:37 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
POST /projects/:id/merge_requests/:merge_request_iid/add_spent_time
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
| `duration` | string | yes | The duration in human format, such as `3h30m` |
2017-08-17 22:00:37 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/93/add_spent_time?duration=1h"
2017-08-17 22:00:37 +05:30
```
Example response:
```json
{
"human_time_estimate": null,
"human_total_time_spent": "1h",
"time_estimate": 0,
"total_time_spent": 3600
}
```
## Reset spent time for a merge request
Resets the total spent time for this merge request to 0 seconds.
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
POST /projects/:id/merge_requests/:merge_request_iid/reset_spent_time
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The internal ID of a project's merge_request. |
2017-08-17 22:00:37 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/93/reset_spent_time"
2017-08-17 22:00:37 +05:30
```
Example response:
```json
{
"human_time_estimate": null,
"human_total_time_spent": null,
"time_estimate": 0,
"total_time_spent": 0
}
```
## Get time tracking stats
2020-04-08 14:13:33 +05:30
```plaintext
2017-08-17 22:00:37 +05:30
GET /projects/:id/merge_requests/:merge_request_iid/time_stats
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
2021-03-08 18:12:59 +05:30
| `merge_request_iid` | integer | yes | The internal ID of the merge request. |
2017-08-17 22:00:37 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/93/time_stats"
2017-08-17 22:00:37 +05:30
```
Example response:
```json
{
"human_time_estimate": "2h",
"human_total_time_spent": "1h",
"time_estimate": 7200,
"total_time_spent": 3600
}
```
2017-09-10 17:25:29 +05:30
2021-03-11 19:13:27 +05:30
## Approvals
2019-09-30 21:07:59 +05:30
For approvals, please see [Merge Request Approvals](merge_request_approvals.md)
2020-10-24 23:57:45 +05:30
## List merge request state events
To track which state was set, who did it, and when it happened, check out
2021-01-29 00:20:46 +05:30
[Resource state events API](resource_state_events.md#merge-requests).