• TOC {: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.

Pull Requests have these possible link relations:

self : The API location of this Pull Request.

html : The HTML location of this Pull Request.

comments : The API location of this Pull Request's Issue comments.

review_comments : The API location of this Pull Request's Review comments.

GET /repos/:owner/:repo/pulls

state : Optional string - open or closed to filter by state. Default is open.

head : Optional string - Filter pulls by head user and branch name in the format of: user:ref-name. Example: github:new-script-format.

base : Optional string - Filter pulls by base branch name. Example: gh-pages.

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

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

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

Each time the pull request receives new commits, GitHub 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.

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

POST /repos/:owner/:repo/pulls

title : Required string

body : Optional string

base : Required string - The branch (or git ref) you want your changes pulled into. This should be an existing branch on the current repository. You cannot submit a pull request to one repo that requests a merge to a base of another repo.

head : Required string - The branch (or git ref) where your changes are implemented.

NOTE: head and base can be either a sha or a branch name. Typically you would namespace head with a user like this: username:branch.

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

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

issue : Required number - Issue number in this repository to turn into a Pull Request.

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

<%= headers 201, :Location => "https://api.github.com/user/repo/pulls/1" %> <%= json :pull %>

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

title : Optional string

body : Optional string

state : Optional string - State of this Pull Request. Valid values are open and closed.

<%= json
:title => "new title", :body => "updated body", :state => "open" %>

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

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

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

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

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

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

<%= headers 204 %>

<%= headers 404 %>

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

commit_message : Optional string - The message that will be used for the merge commit

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

<%= headers 405 %> <%= json
:sha => nil, :merged => false, :message => 'Failure reason' %>

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