Merge requests API

Version history
  • reference was deprecated in GitLab 12.10 in favour of references.
  • reviewer_username and reviewer_id were introduced in GitLab 13.8.
  • draft was introduced as a replacement for work_in_progress in GitLab 14.0.
  • merge_user was introduced as an eventual replacement for merged_by in GitLab 14.7.

Every API call to merge requests must be authenticated.

List merge requests

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 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. The pagination parameters page and per_page can be used to restrict the list of merge requests.

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
GET /merge_requests?author_username=gitlab-bot
GET /merge_requests?my_reaction_emoji=star
GET /merge_requests?scope=assigned_to_me
GET /merge_requests?search=foo&in=title

Parameters:

Attribute Type Required Description
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, title, or updated_at fields. Default is created_at. Introduced in GitLab 14.8.
sort string no Return requests sorted in asc or desc order. Default is desc.
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.
view string no If simple, returns the iid, URL, title, description, and basic state of merge request.
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. Predefined names are case-insensitive.
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.
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.
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. Defaults to created_by_me.
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. Introduced 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.
approver_ids integer array no Returns merge requests which have specified all the users with the given ids as individual approvers. None returns merge requests without approvers. Any returns merge requests with an approver.
approved_by_ids integer array no Returns merge requests which have been approved by all the users with the given ids (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 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 with the given username. None returns merge requests with no reviewers. Any returns merge requests with any reviewer. Mutually exclusive with reviewer_id. Introduced in GitLab 13.8.
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.
wip string no Filter merge requests against their wip status. yes to return only draft merge requests, no to return non-draft merge requests.
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.
environment string no Returns merge requests deployed to the given environment.
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) 
[
  {
    "id": 1,
    "iid": 1,
    "project_id": 3,
    "title": "test1",
    "description": "fixed login page css paddings",
    "state": "merged",
    "merged_by": { // Deprecated and will be removed in API v5, use `merge_user` instead
      "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"
    },
    "merge_user": {
      "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,
    "created_at"<