Skip to content
forgit api docs

Create a merge request

POST
/api/v4/projects/{id}/merge_requests

Creates a merge request for a project.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
id
required
One of:
string

The ID or URL-encoded path of the project.

Request Body required

Section titled “ Request Body required ”
Media type application/json
object
title
required

The title of the merge request.

string
nullable
source_branch
required

The source branch.

string
nullable
target_branch
required

The target branch.

string
nullable
target_project_id

The target project of the merge request defaults to the :id of the project.

integer
nullable
assignee_id

Assignee user ID.

integer
nullable
assignee_ids

The IDs of the users to assign the merge request to, as a comma-separated list. Set to 0 or provide an empty value to unassign all assignees.

Array<integer>
nullable
reviewer_ids

The IDs of the users to review the merge request, as a comma-separated list. Set to 0 or provide an empty value to unassign all reviewers.

Array<integer>
nullable
description

Description of the merge request. Limited to 1,048,576 characters.

string
nullable
labels

Comma-separated label names for a merge request. Set to an empty string to unassign all labels.

Array<string>
nullable
add_labels

Comma-separated label names to add to a merge request.

Array<string>
nullable
remove_labels

Comma-separated label names to remove from a merge request.

Array<string>
nullable
milestone_id

The global ID of a milestone to assign the merge request to.

integer
nullable
milestone

The title of a project or ancestor-group milestone to assign the merge request to. Mutually exclusive with milestone_id.

string
nullable <= 255 characters
remove_source_branch

Flag indicating if a merge request should remove the source branch when merging.

boolean
nullable
allow_collaboration

Allow commits from members who can merge to the target branch.

boolean
nullable
allow_maintainer_to_push

[deprecated] See allow_collaboration

boolean
nullable
squash

Squash commits into a single commit when merging.

boolean
nullable
merge_after

Date after which the merge request can be merged.

string
nullable
approvals_before_merge

Number of approvals required before this can be merged

integer
nullable
approval_rules_attributes
Array<object>
nullable
object
id

The ID of a rule

integer
nullable
approvals_required

Total number of approvals required

integer
nullable
Example generated 
{
  "title": "example",
  "source_branch": "example",
  "target_branch": "example",
  "target_project_id": 1,
  "assignee_id": 1,
  "assignee_ids": [
    1
  ],
  "reviewer_ids": [
    1
  ],
  "description": "example",
  "labels": [
    "example"
  ],
  "add_labels": [
    "example"
  ],
  "remove_labels": [
    "example"
  ],
  "milestone_id": 1,
  "milestone": "example",
  "remove_source_branch": true,
  "allow_collaboration": true,
  "allow_maintainer_to_push": true,
  "squash": true,
  "merge_after": "example",
  "approvals_before_merge": 1,
  "approval_rules_attributes": [
    {
      "id": 1,
      "approvals_required": 1
    }
  ]
}

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

Created

Media type application/json
object
id
integer format: int64
iid
integer
project_id
integer format: int64
title
string
description
string
state
string
created_at
string format: date-time
updated_at
string format: date-time
merged_by
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
merge_user
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
merged_at
string format: date-time
closed_by
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
closed_at
string format: date-time
title_html
string
description_html
string
target_branch
string
source_branch
string
user_notes_count
integer
upvotes
integer
downvotes
integer
author
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
assignees
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
assignee
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
reviewers
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
source_project_id
integer format: int64
target_project_id
integer format: int64
labels
Array<string>
draft
boolean
imported
boolean
imported_from
string
work_in_progress
boolean
milestone
object
id
integer format: int64
iid
integer format: int64
project_id
integer format: int64
group_id
string
title
string
description
string
state
string
created_at
string
updated_at
string
due_date
string
start_date
string
expired
boolean
web_url
string
merge_when_pipeline_succeeds
boolean
merge_status
string
detailed_merge_status
string
merge_after
string format: date-time
sha
string
merge_commit_sha
string
squash_commit_sha
string
discussion_locked
boolean
should_remove_source_branch
boolean
force_remove_source_branch
boolean
prepared_at
string format: date-time
allow_collaboration
boolean
allow_maintainer_to_push
boolean
reference
string
references
object
short
string
relative
string
full
string
web_url
string
time_stats
object
time_estimate
integer
total_time_spent
integer
human_time_estimate
string
human_total_time_spent
string
squash
boolean
squash_on_merge
boolean
task_completion_status
object
count
integer
completed_count
integer
has_conflicts
boolean
blocking_discussions_resolved
boolean
approvals_before_merge
integer
subscribed
boolean
changes_count
string
latest_build_started_at
string format: date-time
latest_build_finished_at
string format: date-time
first_deployed_to_production_at
string format: date-time
pipeline
object
id
integer format: int64
iid
integer
project_id
integer format: int64
sha
string
ref
string
status
string
source
string
created_at
string format: date-time
updated_at
string format: date-time
web_url
string
head_pipeline
object
id
integer format: int64
iid
integer
project_id
integer format: int64
sha
string
ref
string
status
string
source
string
created_at
string format: date-time
updated_at
string format: date-time
web_url
string
before_sha
string
tag
boolean
yaml_errors
string
user
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
started_at
string format: date-time
finished_at
string format: date-time
committed_at
string format: date-time
duration

Time spent running in seconds

integer
queued_duration

Time spent enqueued in seconds

integer
coverage
number format: float
detailed_status
object
icon
string
text
string
label
string
group
string
tooltip
string
has_details
boolean
details_path
string
illustration
object
favicon
string
action
string
archived
boolean
diff_refs
object
base_sha
string
head_sha
string
start_sha
string
merge_error
string
rebase_in_progress
boolean
diverged_commits_count
integer
first_contribution
boolean
user
object
Example 
{
  "id": 84,
  "iid": 14,
  "project_id": 4,
  "title": "Impedit et ut et dolores vero provident ullam est",
  "description": "Repellendus impedit et vel velit dignissimos.",
  "state": "closed",
  "created_at": "2022-08-17T12:46:35.053Z",
  "updated_at": "2022-11-14T17:22:01.470Z",
  "merged_by": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "merge_user": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "merged_at": "2022-01-31T15:10:45.080Z",
  "closed_by": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "closed_at": "2022-01-31T15:10:45.080Z",
  "author": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "assignees": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "assignee": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "reviewers": {
    "id": 1,
    "username": "admin",
    "public_email": "john@example.com",
    "name": "Administrator",
    "state": "active",
    "avatar_url": "https://gravatar.com/avatar/1",
    "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
    "custom_attributes": [
      {
        "key": "foo",
        "value": "bar"
      }
    ],
    "web_url": "https://gitlab.example.com/root"
  },
  "imported_from": "bitbucket",
  "merge_status": "unchecked",
  "detailed_merge_status": "mergeable",
  "merge_after": "2022-01-31T15:10:45.080Z",
  "sha": "1234abcd",
  "merge_commit_sha": "1234abcd",
  "squash_commit_sha": "1234abcd",
  "prepared_at": "2022-01-31T15:10:45.080Z",
  "reference": "!1",
  "references": {
    "short": "&6",
    "relative": "&6",
    "full": "test&6"
  },
  "web_url": "https://gitlab.example.com/my-group/my-project/-/merge_requests/1",
  "time_stats": {
    "time_estimate": 12600,
    "total_time_spent": 3600,
    "human_time_estimate": "3h 30m",
    "human_total_time_spent": "1h"
  },
  "task_completion_status": {
    "count": 5,
    "completed_count": 3
  },
  "approvals_before_merge": 2,
  "changes_count": "1",
  "latest_build_started_at": "2022-01-31T15:10:45.080Z",
  "latest_build_finished_at": "2022-01-31T15:10:45.080Z",
  "first_deployed_to_production_at": "2022-01-31T15:10:45.080Z",
  "pipeline": {
    "id": 1,
    "iid": 2,
    "project_id": 3,
    "sha": "0ec9e58fdfca6cdd6652c083c9edb53abc0bad52",
    "ref": "feature-branch",
    "status": "success",
    "source": "push",
    "created_at": "2022-10-21T16:49:48.000+02:00",
    "updated_at": "2022-10-21T16:49:48.000+02:00",
    "web_url": "https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61"
  },
  "head_pipeline": {
    "id": 1,
    "iid": 2,
    "project_id": 3,
    "sha": "0ec9e58fdfca6cdd6652c083c9edb53abc0bad52",
    "ref": "feature-branch",
    "status": "success",
    "source": "push",
    "created_at": "2015-12-24T15:51:21.880Z",
    "updated_at": "2015-12-24T17:54:31.198Z",
    "web_url": "https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61",
    "before_sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
    "tag": false,
    "yaml_errors": "widgets:build: needs 'widgets:test'",
    "user": {
      "id": 1,
      "username": "admin",
      "public_email": "john@example.com",
      "name": "Administrator",
      "state": "active",
      "avatar_url": "https://gravatar.com/avatar/1",
      "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
      "custom_attributes": [
        {
          "key": "foo",
          "value": "bar"
        }
      ],
      "web_url": "https://gitlab.example.com/root"
    },
    "started_at": "2015-12-24T17:54:30.733Z",
    "finished_at": "2015-12-24T17:54:31.198Z",
    "committed_at": "2015-12-24T15:51:21.880Z",
    "duration": 127,
    "queued_duration": 63,
    "coverage": 98.29,
    "detailed_status": {
      "icon": "status_success",
      "text": "passed",
      "label": "passed",
      "group": "success",
      "tooltip": "passed",
      "has_details": true,
      "details_path": "/test-group/test-project/-/pipelines/287",
      "illustration": {
        "image": "illustrations/empty-state/empty-job-not-triggered-md.svg",
        "size": "",
        "title": "This job has not been triggered yet",
        "content": "This job depends on upstream jobs that need to succeed in order for this job to be triggered"
      },
      "favicon": "/assets/ci_favicons/favicon_status_success.png"
    },
    "archived": false
  },
  "diff_refs": {
    "base_sha": "b83d6e391c22777fca1ed3012fce84f633d7fed0",
    "head_sha": "b83d6e391c22777fca1ed3012fce84f633d7fed0",
    "start_sha": "b83d6e391c22777fca1ed3012fce84f633d7fed0"
  },
  "merge_error": "Merge error",
  "diverged_commits_count": 0
}

400

Section titled “ 400 ”

Bad request

401

Section titled “ 401 ”

Unauthorized

404

Section titled “ 404 ”

Not found

409

Section titled “ 409 ”

Conflict

422

Section titled “ 422 ”

Unprocessable entity