kotovalexarian-likes-gitlab/gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity
gitlab-org--gitlab-foss/doc/api/merge_requests.md
Dmitriy Zaporozhets c366e81da7
Improve docs 
Signed-off-by: Dmitriy Zaporozhets <dmitriy.zaporozhets@gmail.com>
2015-12-04 11:26:35 +01:00

11 KiB
Raw Blame History

Merge requests

List merge requests

Get all merge requests for this project. The state parameter can be used to get only merge requests with a given state (opened, closed, or merged) or all of them (all). The pagination parameters page and per_page can be used to restrict the list of merge requests. With GitLab 8.2 the return fields upvotes and downvotes are deprecated and always return 0.

GET /projects/:id/merge_requests
GET /projects/:id/merge_requests?state=opened
GET /projects/:id/merge_requests?state=all
GET /projects/:id/merge_requests?iid=42

Parameters:

  • id (required) - The ID of a project
  • iid (optional) - Return the request having the given iid
  • state (optional) - Return all requests or just those that are merged, opened or closed
  • order_by (optional) - Return requests ordered by created_at or updated_at fields. Default is created_at
  • sort (optional) - Return requests sorted in asc or desc order. Default is desc
[
  {
    "id": 1,
    "iid": 1,
    "target_branch": "master",
    "source_branch": "test1",
    "project_id": 3,
    "title": "test1",
    "state": "opened",
    "upvotes": 0,
    "downvotes": 0,
    "author": {
      "id": 1,
      "username": "admin",
      "email": "admin@example.com",
      "name": "Administrator",
      "state": "active",
      "created_at": "2012-04-29T08:46:00Z"
    },
    "assignee": {
      "id": 1,
      "username": "admin",
      "email": "admin@example.com",
      "name": "Administrator",
      "state": "active",
      "created_at": "2012-04-29T08:46:00Z"
    },
    "description":"fixed login page css paddings",
    "work_in_progress": false
  }
]

Get single MR

Shows information about a single merge request. With GitLab 8.2 the return fields upvotes and downvotes are deprecated and always return 0.

GET /projects/:id/merge_request/:merge_request_id

Parameters:

  • id (required) - The ID of a project
  • merge_request_id (required) - The ID of MR
{
  "id": 1,
  "iid": 1,
  "target_branch": "master",
  "source_branch": "test1",
  "project_id": 3,
  "title": "test1",
  "state": "merged",
  "upvotes": 0,
  "downvotes": 0,
  "author": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  },
  "assignee": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  },
  "description":"fixed login page css paddings",
  "work_in_progress": false
}

Get single MR commits

Get a list of merge request commits.

GET /projects/:id/merge_request/:merge_request_id/commits

Parameters:

  • id (required) - The ID of a project
  • merge_request_id (required) - The ID of MR
[
  {
    "id": "ed899a2f4b50b4370feeea94676502b42383c746",
    "short_id": "ed899a2f4b5",
    "title": "Replace sanitize with escape once",
    "author_name": "Dmitriy Zaporozhets",
    "author_email": "dzaporozhets@sphereconsultinginc.com",
    "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",
    "author_name": "randx",
    "author_email": "dmitriy.zaporozhets@gmail.com",
    "created_at": "2012-09-20T09:06:12+03:00",
    "message": "Sanitize for network graph"
  }
]

Get single MR changes

Shows information about the merge request including its files and changes. With GitLab 8.2 the return fields upvotes and downvotes are deprecated and always return 0.

GET /projects/:id/merge_request/:merge_request_id/changes

Parameters:

  • id (required) - The ID of a project
  • merge_request_id (required) - The ID of MR
{
  "id": 21,
  "iid": 1,
  "project_id": 4,
  "title": "Blanditiis beatae suscipit hic assumenda et molestias nisi asperiores repellat et.",
  "description": "Qui voluptatibus placeat ipsa alias quasi. Deleniti rem ut sint. Optio velit qui distinctio.",
  "work_in_progress": false,
  "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",
    "avatar_url": "http://www.gravatar.com/avatar/b95567800f828948baf5f4160ebb2473?s=40&d=identicon"
  },
  "assignee": {
    "name": "Administrator",
    "username": "root",
    "id": 1,
    "state": "active",
    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40&d=identicon"
  },
  "source_project_id": 4,
  "target_project_id": 4,
  "labels": [ ],
  "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
  },
  "changes": [
    {
    "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
    }
  ]
}

Create MR

Creates a new merge request. With GitLab 8.2 the return fields upvotes and downvotes are deprecated and always return 0.

POST /projects/:id/merge_requests

Parameters:

  • id (required) - The ID of a project
  • source_branch (required) - The source branch
  • target_branch (required) - The target branch
  • assignee_id (optional) - Assignee user ID
  • title (required) - Title of MR
  • description (optional) - Description of MR
  • target_project_id (optional) - The target project (numeric id)
  • labels (optional) - Labels for MR as a comma-separated list
{
  "id": 1,
  "target_branch": "master",
  "source_branch": "test1",
  "project_id": 3,
  "title": "test1",
  "state": "opened",
  "upvotes": 0,
  "downvotes": 0,
  "author": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  },
  "assignee": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  },
  "description":"fixed login page css paddings"
}

If the operation is successful, 200 and the newly created merge request is returned. If an error occurs, an error number and a message explaining the reason is returned.

Update MR

Updates an existing merge request. You can change the target branch, title, or even close the MR. With GitLab 8.2 the return fields upvotes and downvotes are deprecated and always return 0.

PUT /projects/:id/merge_request/:merge_request_id

Parameters:

  • id (required) - The ID of a project
  • merge_request_id (required) - ID of MR
  • target_branch - The target branch
  • assignee_id - Assignee user ID
  • title - Title of MR
  • description - Description of MR
  • state_event - New state (close|reopen|merge)
  • labels (optional) - Labels for MR as a comma-separated list
{
  "id": 1,
  "target_branch": "master",
  "project_id": 3,
  "title": "test1",
  "description": "description1",
  "state": "opened",
  "upvotes": 0,
  "downvotes": 0,
  "author": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  },
  "assignee": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  }
}

If the operation is successful, 200 and the updated merge request is returned. If an error occurs, an error number and a message explaining the reason is returned.

Accept MR

Merge changes submitted with MR using this API. With GitLab 8.2 the return fields upvotes and downvotes are deprecated and always return 0.

If merge success you get 200 OK.

If it has some conflicts and can not be merged - you get 405 and error message 'Branch cannot be merged'

If merge request is already merged or closed - you get 405 and error message 'Method Not Allowed'

If you don't have permissions to accept this merge request - you'll get a 401

PUT /projects/:id/merge_request/:merge_request_id/merge

Parameters:

  • id (required) - The ID of a project
  • merge_request_id (required) - ID of MR
  • merge_commit_message (optional) - Custom merge commit message
{
  "id": 1,
  "target_branch": "master",
  "source_branch": "test1",
  "project_id": 3,
  "title": "test1",
  "state": "merged",
  "upvotes": 0,
  "downvotes": 0,
  "author": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  },
  "assignee": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "name": "Administrator",
    "state": "active",
    "created_at": "2012-04-29T08:46:00Z"
  }
}

Post comment to MR

Adds a comment to a merge request.

POST /projects/:id/merge_request/:merge_request_id/comments

Parameters:

  • id (required) - The ID of a project
  • merge_request_id (required) - ID of merge request
  • note (required) - Text of comment
{
  "note": "text1"
}

Get the comments on a MR

Gets all the comments associated with a merge request.

GET /projects/:id/merge_request/:merge_request_id/comments

Parameters:

  • id (required) - The ID of a project
  • merge_request_id (required) - ID of merge request
[
  {
    "note": "this is the 1st comment on the 2merge merge request",
    "author": {
      "id": 11,
      "username": "admin",
      "email": "admin@example.com",
      "name": "Administrator",
      "state": "active",
      "created_at": "2014-03-06T08:17:35.000Z"
    }
  },
  {
    "note": "Status changed to closed",
    "author": {
      "id": 11,
      "username": "admin",
      "email": "admin@example.com",
      "name": "Administrator",
      "state": "active",
      "created_at": "2014-03-06T08:17:35.000Z"
    }
  }
]

Comments on merge requets

Comments are done via the notes resource.