Operations related to merge requests
swagger: '2.0'
info:
title: GitLab access_requests merge_requests API
version: v4
description: Operations related to access requests
host: gitlab.com
produces:
- application/json
tags:
- name: merge_requests
description: Operations related to merge requests
paths:
/api/v4/groups/{id}/merge_requests:
get:
summary: List group merge requests
description: Get all merge requests for this group and its subgroups.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the group owned by the authenticated user.
type: string
required: true
- in: query
name: author_id
description: Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`.
type: integer
format: int32
required: false
- in: query
name: author_username
description: Returns merge requests created by the given `username`. Mutually exclusive with `author_id`.
type: string
required: false
- in: query
name: assignee_id
description: Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee.
type: integer
format: int32
required: false
- in: query
name: assignee_username
description: Returns merge requests created by the given `username`. Mutually exclusive with `author_id`.
type: array
items:
type: string
required: false
- in: query
name: reviewer_username
description: 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.
type: string
required: false
- in: query
name: labels
description: Returns 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.
type: array
items:
type: string
required: false
- in: query
name: milestone
description: Returns merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone.
type: string
required: false
- in: query
name: my_reaction_emoji
description: Returns 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.
type: string
required: false
- in: query
name: reviewer_id
description: 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`.
type: integer
format: int32
required: false
- in: query
name: state
description: Returns `all` merge requests or just those that are `opened`, `closed`, `locked`, or `merged`.
type: string
default: all
enum:
- opened
- closed
- locked
- merged
- all
required: false
- in: query
name: order_by
description: Returns merge requests ordered by `created_at`, `label_priority`, `milestone_due`, `popularity`, `priority`, `title`, `updated_at` or `merged_at` fields. Introduced in GitLab 14.8.
type: string
default: created_at
enum:
- created_at
- label_priority
- milestone_due
- popularity
- priority
- title
- updated_at
- merged_at
required: false
- in: query
name: sort
description: Returns merge requests sorted in `asc` or `desc` order.
type: string
default: desc
enum:
- asc
- desc
required: false
- in: query
name: with_labels_details
description: 'If `true`, response returns more details for each label in labels field: `:name`,`:color`, `:description`, `:description_html`, `:text_color`'
type: boolean
default: false
required: false
- in: query
name: with_merge_status_recheck
description: If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Introduced in GitLab 13.0.
type: boolean
default: false
required: false
- in: query
name: created_after
description: Returns merge requests created on or after the given time. Expected in ISO 8601 format.
type: string
format: date-time
required: false
example: '2019-03-15T08:00:00Z'
- in: query
name: created_before
description: Returns merge requests created on or before the given time. Expected in ISO 8601 format.
type: string
format: date-time
required: false
example: '2019-03-15T08:00:00Z'
- in: query
name: updated_after
description: Returns merge requests updated on or after the given time. Expected in ISO 8601 format.
type: string
format: date-time
required: false
example: '2019-03-15T08:00:00Z'
- in: query
name: updated_before
description: Returns merge requests updated on or before the given time. Expected in ISO 8601 format.
type: string
format: date-time
required: false
example: '2019-03-15T08:00:00Z'
- in: query
name: view
description: If simple, returns the `iid`, URL, title, description, and basic state of merge request
type: string
enum:
- simple
required: false
- in: query
name: scope
description: 'Returns merge requests for the given scope: `created_by_me`, `assigned_to_me`, `reviews_for_me` or `all`'
type: string
enum:
- created-by-me
- assigned-to-me
- created_by_me
- assigned_to_me
- reviews_for_me
- all
required: false
- in: query
name: source_branch
description: Returns merge requests with the given source branch
type: string
required: false
- in: query
name: source_project_id
description: Returns merge requests with the given source project id
type: integer
format: int32
required: false
- in: query
name: target_branch
description: Returns merge requests with the given target branch
type: string
required: false
- in: query
name: search
description: Search merge requests against their `title` and `description`.
type: string
required: false
- in: query
name: in
description: Modify the scope of the search attribute. `title`, `description`, or a string joining them with comma.
type: string
required: false
example: title,description
- in: query
name: wip
description: Deprecated. Use `draft` instead. Filter merge requests against their `wip` status. `yes` to return only draft merge requests, `no` to return non-draft merge requests.
type: string
enum:
- 'yes'
- 'no'
required: false
- in: query
name: draft
description: Filter merge requests against their `draft` status. `true` to return only draft merge requests, `false` to return non-draft merge requests.
type: boolean
required: false
- in: query
name: not[author_id]
description: '`<Negated>` Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`.'
type: integer
format: int32
required: false
- in: query
name: not[author_username]
description: '`<Negated>` Returns merge requests created by the given `username`. Mutually exclusive with `author_id`.'
type: string
required: false
- in: query
name: not[assignee_id]
description: '`<Negated>` Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee.'
type: integer
format: int32
required: false
- in: query
name: not[assignee_username]
description: '`<Negated>` Returns merge requests created by the given `username`. Mutually exclusive with `author_id`.'
type: array
items:
type: string
required: false
- in: query
name: not[reviewer_username]
description: '`<Negated>` 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.'
type: string
required: false
- in: query
name: not[labels]
description: '`<Negated>` Returns 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.'
type: array
items:
type: string
required: false
- in: query
name: not[milestone]
description: '`<Negated>` Returns merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone.'
type: string
required: false
- in: query
name: not[my_reaction_emoji]
description: '`<Negated>` Returns 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.'
type: string
required: false
- in: query
name: not[reviewer_id]
description: '`<Negated>` 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`.'
type: integer
format: int32
required: false
- in: query
name: deployed_before
description: Returns merge requests deployed before the given date/time. Expected in ISO 8601 format.
type: string
required: false
example: '2019-03-15T08:00:00Z'
- in: query
name: deployed_after
description: Returns merge requests deployed after the given date/time. Expected in ISO 8601 format
type: string
required: false
example: '2019-03-15T08:00:00Z'
- in: query
name: environment
description: Returns merge requests deployed to the given environment
type: string
required: false
example: '2019-03-15T08:00:00Z'
- in: query
name: approved
description: Filters merge requests by their `approved` status. `yes` returns only approved merge requests. `no` returns only non-approved merge requests.
type: string
enum:
- 'yes'
- 'no'
required: false
- in: query
name: merge_user_id
description: Returns merge requests which have been merged by the user with the given user `id`. Mutually exclusive with `merge_user_username`.
type: integer
format: int32
required: false
- in: query
name: merge_user_username
description: Returns merge requests which have been merged by the user with the given `username`. Mutually exclusive with `merge_user_id`.
type: string
required: false
- in: query
name: approver_ids
description: Return merge requests which have specified the users with the given IDs as an individual approver
type: string
required: false
- in: query
name: approved_by_ids
description: Return merge requests which have been approved by the specified users with the given IDs
type: string
required: false
- in: query
name: approved_by_usernames
description: "Return merge requests which have been approved by the specified users with the given\n usernames"
type: string
required: false
- in: query
name: page
description: Current page number
type: integer
format: int32
default: 1
required: false
example: 1
- in: query
name: per_page
description: Number of items per page
type: integer
format: int32
default: 20
required: false
example: 20
- in: query
name: non_archived
description: Returns merge requests from non archived projects only.
type: boolean
default: true
required: false
responses:
'200':
description: List group merge requests
schema:
type: array
items:
$ref: '#/definitions/API_Entities_MergeRequestBasic'
'401':
description: Unauthorized
'404':
description: Not found
'422':
description: Unprocessable entity
tags:
- merge_requests
operationId: getApiV4GroupsIdMergeRequests
/api/v4/projects/{id}/create_ci_config:
post:
summary: Create merge request for missing ci config in project
description: Creates a merge request to add missing CI configuration
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
type: integer
format: int32
required: true
responses:
'201':
description: Create merge request for missing ci config in project
tags:
- merge_requests
operationId: postApiV4ProjectsIdCreateCiConfig
/api/v4/projects/{id}/merge_requests/{merge_request_iid}/time_estimate:
post:
summary: Set a time estimate for a merge_request
description: Sets an estimated time of work for this merge_request.
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project.
type: string
required: true
- in: path
name: merge_request_iid
description: The internal ID of the merge_request.
type: integer
format: int32
required: true
- name: postApiV4ProjectsIdMergeRequestsMergeRequestIidTimeEstimate
in: body
required: true
schema:
$ref: '#/definitions/postApiV4ProjectsIdMergeRequestsMergeRequestIidTimeEstimate'
responses:
'201':
description: Set a time estimate for a merge_request
schema:
$ref: '#/definitions/API_Entities_IssuableTimeStats'
'401':
description: Unauthorized
'400':
description: Bad request
'404':
description: Not found
tags:
- merge_requests
operationId: postApiV4ProjectsIdMergeRequestsMergeRequestIidTimeEstimate
/api/v4/projects/{id}/merge_requests/{merge_request_iid}/reset_time_estimate:
post:
summary: Reset the time estimate for a project merge_request
description: Resets the estimated time for this merge_request to 0 seconds.
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project.
type: string
required: true
- in: path
name: merge_request_iid
description: The internal ID of the merge_request.
type: integer
format: int32
required: true
responses:
'201':
description: Reset the time estimate for a project merge_request
schema:
$ref: '#/definitions/API_Entities_IssuableTimeStats'
'401':
description: Unauthorized
'404':
description: Not found
tags:
- merge_requests
operationId: postApiV4ProjectsIdMergeRequestsMergeRequestIidResetTimeEstimate
/api/v4/projects/{id}/merge_requests/{merge_request_iid}/add_spent_time:
post:
summary: Add spent time for a merge_request
description: Adds spent time for this merge_request.
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project.
type: string
required: true
- in: path
name: merge_request_iid
description: The internal ID of the merge_request.
type: integer
format: int32
required: true
- name: postApiV4ProjectsIdMergeRequestsMergeRequestIidAddSpentTime
in: body
required: true
schema:
$ref: '#/definitions/postApiV4ProjectsIdMergeRequestsMergeRequestIidAddSpentTime'
responses:
'201':
description: Add spent time for a merge_request
schema:
$ref: '#/definitions/API_Entities_IssuableTimeStats'
'401':
description: Unauthorized
'404':
description: Not found
tags:
- merge_requests
operationId: postApiV4ProjectsIdMergeRequestsMergeRequestIidAddSpentTime
/api/v4/projects/{id}/merge_requests/{merge_request_iid}/reset_spent_time:
post:
summary: Reset spent time for a merge_request
description: Resets the total spent time for this merge_request to 0 seconds.
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project.
type: string
required: true
- in: path
name: merge_request_iid
description: The internal ID of the merge_request
type: integer
format: int32
required: true
responses:
'201':
description: Reset spent time for a merge_request
schema:
$ref: '#/definitions/API_Entities_IssuableTimeStats'
'401':
description: Unauthorized
'404':
description: Not found
tags:
- merge_requests
operationId: postApiV4ProjectsIdMergeRequestsMergeRequestIidResetSpentTime
/api/v4/projects/{id}/merge_requests/{merge_request_iid}/time_stats:
get:
summary: Get time tracking stats
description: Get time tracking stats
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project.
type: string
required: true
- in: path
name: merge_request_iid
description: The internal ID of the merge_request
type: integer
format: int32
required: true
responses:
'200':
description: Get time tracking stats
schema:
$ref: '#/definitions/API_Entities_IssuableTimeStats'
'401':
description: Unauthorized
'404':
description: Not found
tags:
- merge_requests
operationId: getApiV4ProjectsIdMergeRequestsMergeRequestIidTimeStats
/api/v4/projects/{id}/merge_requests:
get:
summary: List project merge requests
description: Get all merge requests for this project.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project.
type: string
required: true
- in: query
name: author_id
description: Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`.
type: integer
format: int32
required: false
- in: query
name: author_username
description: Returns merge requests created by the given `username`. Mutually exclusive with `author_id`.
type: string
required: false
- in: query
name: assignee_id
description: Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee.
type: integer
format: int32
required: false
- in: query
name: assignee_username
description: Returns merge requests created by the given `username`. Mutually exclusive with `author_id`.
type: array
items:
type: string
required: false
- in: query
name: reviewer_username
description: 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.
type: string
required: false
- in: query
name: labels
description: Returns 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.
type: array
items:
type: string
required: false
- in: query
name: milestone
description: Returns merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone.
type: string
required: false
- in: query
name: my_reaction_emoji
description: Returns 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.
type: string
required: false
- in: query
name: reviewer_id
description: 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`.
type: integer
format: int32
required: false
- in: query
name: state
description: Returns `all` merge requests or just those that are `opened`, `closed`, `locked`, or `merged`.
type: string
default: all
enum:
- opened
- closed
- locked
- merged
- all
required: false
- in: query
name: order_by
description: Returns merge requests ordered by `created_at`, `label_priority`, `milestone_due`, `popularity`, `priority`, `title`, `updated_at` or `merged_at` fields. Introduced in GitLab 14.8.
type: string
default: created_at
enum:
- created_at
- label_priority
- milestone_due
- popularity
- priority
- title
- updated_at
- merged_at
required: false
- in: query
name: sort
description: Returns merge requests sorted in `asc` or `desc` order.
type: string
default: desc
enum:
- asc
- desc
required: false
- in: query
name: with_labels_details
description: 'If `true`, response returns more details for each label in labels field: `:name`,`:color`, `:description`, `:description_html`, `:text_color`'
type: boolean
default: false
required: false
- in: query
name: with_merge_status_recheck
description: If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Introduced in GitLab 13.0.
type: boolean
default: false
required: false
- in: query
name: created_after
description: Returns merge requests created on or after the given time. Expected in ISO 8601 format.
type: string
format: date-time
required: false
example: '2019-03-15T08:00:00Z'
- in: query
name: created_before
description: Returns merge requests created on or before the given time. Expected in ISO 8601 format.
type: string
format: date-time
required: false
example: '2019-03-15T08:00:00Z'
- in: query
name: updated_after
description: Returns merge requests updated on or after the given time. Expected in ISO 8601 format.
type: string
format: date-time
required: false
example: '2019-03-15T08:00:00Z'
- in: query
name: updated_before
description: Returns merge requests updated on or before the given time. Expected in ISO 8601 format.
type: string
format: date-time
required: false
example: '2019-03-15T08:00:00Z'
- in: query
name: view
description: If simple, returns the `iid`, URL, title, description, and basic state of merge request
type: string
enum:
- simple
required: false
- in: query
name: scope
description: 'Returns merge requests for the given scope: `created_by_me`, `assigned_to_me`, `reviews_for_me` or `all`'
type: string
enum:
- created-by-me
- assigned-to-me
- created_by_me
- assigned_to_me
- reviews_for_me
- all
required: false
- in: query
name: source_branch
description: Returns merge requests with the given source branch
type: string
required: false
- in: query
name: source_project_id
description: Returns merge requests with the given source project id
type: integer
format: int32
required: false
- in: query
name: target_branch
description: Returns merge requests with the given target branch
type: string
required: false
- in: query
name: search
description: Search merge requests against their `title` and `description`.
type: string
required: false
- in: query
name: in
description: Modify the scope of the search attribute. `title`, `description`, or a string joining them with comma.
type: string
required: false
example: title,description
- in: query
name: wip
description: Deprecated. Use `draft` instead. Filter merge requests against their `wip` status. `yes` to return only draft merge requests, `no` to return non-draft merge requests.
type: string
enum:
- 'yes'
- 'no'
required: false
- in: query
name: draft
description: Filter merge requests against their `draft` status. `true` to return only draft merge requests, `false` to return non-draft merge requests.
type: boolean
required: false
- in: query
name: not[author_id]
description: '`<Negated>` Returns merge requests created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`.'
type: integer
format: int32
required: false
- in: query
name: not[author_username]
description: '`<Negated>` Returns merge requests created by the given `username`. Mutually exclusive with `author_id`.'
type: string
required: false
- in: query
name: not[assignee_id]
description: '`<Negated>` Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee.'
type: integer
format: int32
required: false
- in: query
name: not[assignee_username]
description: '`<Negated>` Returns merge requests created by the given `username`. Mutually exclusive with `author_id`.'
type: array
items:
type: string
required: false
- in: query
name: not[reviewer_username]
description: '`<Negated>` 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.'
type: string
required: false
- in: query
name: not[labels]
description: '`<Negated>` Returns 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.'
type: array
items:
type: string
required: false
- in: query
name: not[milestone]
description: '`<Negated>` Returns merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone.'
type: string
required: false
- in: query
name: not[my_reaction_emoji]
description: '`<Negated>` Returns 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.'
type: string
required: false
- in: query
name: not[reviewer_id]
description: '`<Negated>` 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`.'
type: integer
format: int32
required: false
- in: query
name: deployed_before
description: Returns merge requests deployed before the given date/time. Expected in ISO 8601 format.
type: string
required: false
example: '2019-03-15T08:00:00Z'
- in: query
name: deployed_after
description: Returns merge requests deployed after the given date/time. Expected in ISO 8601 format
type: string
required: false
example: '2019-03-15T08:00:00Z'
- in: query
name: environment
description: Returns merge requests deployed to the given environment
type: string
required: false
example: '2019-03-15T08:00:00Z'
- in: query
name: approved
description: Filters merge requests by their `approved` status. `yes` returns only approved merge requests. `no` returns only non-approved merge requests.
type: string
enum:
- 'yes'
- 'no'
required: false
- in: query
name: merge_user_id
description: Returns merge requests which have been merged by the user with the given user `id`. Mutually exclusive with `merge_user_username`.
type: integer
format: int32
required: false
- in: query
name: merge_user_username
description: Returns merge requests which have been merged by the user with the given `username`. Mutually exclusive with `merge_user_id`.
type: string
required: false
- in: query
name: approver_ids
description: Return merge requests which have specified the users with the given IDs as an individual approver
type: string
required: false
- in: query
name: approved_by_ids
description: Return merge requests which have been approved by the specified users with the given IDs
type: string
required: false
- in: query
name: approved_by_usernames
description: "Return merge requests which have been approved by the specified users wi
# --- truncated at 32 KB (110 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gitlab-ci/refs/heads/main/openapi/gitlab-ci-merge-requests-api-openapi.yml