Skip to content
This repository was archived by the owner on Nov 1, 2017. It is now read-only.

pulls.md

Latest commit

 

History

History
258 lines (175 loc) · 8.88 KB

pulls.md

File metadata and controls

258 lines (175 loc) · 8.88 KB
title Pull Requests

Pull Requests

{:toc}

The Pull Request API allows you to list, view, edit, create, and even merge pull requests. Comments on pull requests can be managed via the Issue Comments API.

Pull Requests use these custom media types. You can read more about the use of media types in the API here.

Link Relations

Pull Requests have these possible link relations:

Name Description
self The API location of this Pull Request.
html The HTML location of this Pull Request.
issue The API location of this Pull Request's Issue.
comments The API location of this Pull Request's Issue comments.
review_comments The API location of this Pull Request's Review comments.
review_comment The URL template to construct the API location for a Review comment in this Pull Request's repository.
commits The API location of this Pull Request's commits.
statuses The API location of this Pull Request's commit statuses, which are the statuses of its head branch.

List pull requests

GET /repos/:owner/:repo/pulls

Parameters

Name Type Description
state string Either open, closed, or all to filter by state. Default: open
head string Filter pulls by head user and branch name in the format of user:ref-name. Example: github:new-script-format.
base string Filter pulls by base branch name. Example: gh-pages.
sort string What to sort results by. Can be either created, updated, popularity (comment count) or long-running (age, filtering by pulls updated in the last month). Default: created
direction string The direction of the sort. Can be either asc or desc. Default: desc when sort is created or sort is not specified, otherwise asc.

Response

<%= headers 200, :pagination => default_pagination_rels %> <%= json(:pull) { |h| [h] } %>

Get a single pull request

GET /repos/:owner/:repo/pulls/:number

Response

{{#tip}}

Each time the pull request receives new commits, {{ site.data.variables.product.product_name }} creates a merge commit to test whether the pull request can be automatically merged into the base branch. (This test commit is not added to the base branch or the head branch.) The merge_commit_sha attribute holds the SHA of the test merge commit; however, this attribute is deprecated and is scheduled for removal in the next version of the API. The Boolean mergeable attribute will remain to indicate whether the pull request can be automatically merged.

The value of the mergeable attribute can be true, false, or null. If the value is null, this means that the mergeability hasn't been computed yet, and a background job was started to compute it. Give the job a few moments to complete, and then submit the request again. When the job is complete, the response will include a non-null value for the mergeable attribute.

{{/tip}}

Pass the appropriate media type to fetch diff and patch formats.

<%= headers 200 %> <%= json :full_pull %>

Create a pull request

POST /repos/:owner/:repo/pulls

Input

Name Type Description
title string Required. The title of the pull request.
head string Required. The name of the branch where your changes are implemented. For cross-repository pull requests in the same network, namespace head with a user like this: username:branch.
base string Required. The name of the branch you want the changes pulled into. This should be an existing branch on the current repository. You cannot submit a pull request to one repository that requests a merge to a base of another repository.
body string The contents of the pull request.

Example

<%= json
:title => "Amazing new feature", :body => "Please pull this in!", :head => "octocat:new-feature", :base => "master" %>

Alternative Input

You can also create a Pull Request from an existing Issue by passing an Issue number instead of title and body.

Name Type Description
issue integer Required. The issue number in this repository to turn into a Pull Request.

Example

<%= json
:issue => 5, :head => "octocat:new-feature", :base => "master" %>

Response

<%= headers 201, :Location => get_resource(:pull)['url'] %> <%= json :pull %>

Update a pull request

PATCH /repos/:owner/:repo/pulls/:number

Input

Name Type Description
title string The title of the pull request.
body string The contents of the pull request.
state string State of this Pull Request. Either open or closed.{% if page.version == 'dotcom' or page.version >= 2.8 %}
base string The name of the branch you want your changes pulled into. This should be an existing branch on the current repository. You cannot update the base branch on a pull request to point to another repository.
{% endif %}

Example

<%= json
:title => "new title", :body => "updated body", :state => "open"{% if page.version == 'dotcom' or page.version >= 2.8 %}, :base => "master" {% endif %} %>

Response

<%= headers 200 %> <%= json :pull %>

List commits on a pull request

GET /repos/:owner/:repo/pulls/:number/commits

Response

<%= headers 200, :pagination => default_pagination_rels %> <%= json(:commit) { |h| [h] } %>

Note: The response includes a maximum of 250 commits. If you are working with a pull request larger than that, you can use the Commit List API to enumerate all commits in the pull request.

List pull requests files

GET /repos/:owner/:repo/pulls/:number/files

Response

<%= headers 200, :pagination => default_pagination_rels %> <%= json(:file) { |h| [h] } %>

Get if a pull request has been merged

GET /repos/:owner/:repo/pulls/:number/merge

Response if pull request has been merged

<%= headers 204 %>

Response if pull request has not been merged

<%= headers 404 %>

Merge a pull request (Merge Button)

PUT /repos/:owner/:repo/pulls/:number/merge

Input

Name Type Description
{% if page.version == 'dotcom' or page.version >= 2.6 %}commit_title string Title for the automatic commit message.{% endif %}
commit_message string Extra detail to append to automatic commit message.
sha string SHA that pull request head must match to allow merge
{% if page.version == 'dotcom' or page.version >= 2.6 %}squash boolean Commit a single commit to the head branch.{% endif %}

{% if page.version == 'dotcom' or page.version >= 2.6 %}

{{#tip}}

The commit_title and squash parameters are currently available for developers to preview. During the preview period, the API may change without advance notice. Please see the blog post for full details.

To access the API during the preview period, you must provide a custom media type in the Accept header:

application/vnd.github.polaris-preview+json

{{/tip}}

{% endif %}

Response if merge was successful

<%= headers 200 %> <%= json
:sha => '6dcb09b5b57875f334f61aebed695e2e4193db5e', :merged => true, :message => 'Pull Request successfully merged' %>

Response if merge cannot be performed

<%= headers 405 %> <%= json
:message => "Pull Request is not mergeable", :documentation_url => "https://developer.github.com/v3/pulls/#merge-a-pull-request-merge-button" %>

Response if sha was provided and pull request head did not match

<%= headers 409 %> <%= json
:message => "Head branch was modified. Review and try the merge again.", :documentation_url => "https://developer.github.com/v3/pulls/#merge-a-pull-request-merge-button" %>

Labels, assignees, and milestones

Every pull request is an issue, but not every issue is a pull request. For this reason, "shared" actions for both features, like manipulating assignees, labels and milestones, are provided within the Issues API.

Custom media types

These are the supported media types for pull requests. You can read more about the use of media types in the API here.

application/vnd.github.VERSION.raw+json
application/vnd.github.VERSION.text+json
application/vnd.github.VERSION.html+json
application/vnd.github.VERSION.full+json
application/vnd.github.VERSION.diff
application/vnd.github.VERSION.patch

If a diff is corrupt, contact {{ site.data.variables.contact.contact_support }} to receive help. Be sure to include the repository name and pull request ID.