GitHub pull request API

Kenny DuMez
Kenny DuMez
Graphite software engineer

In this guide, we'll explore how to use the GitHub pull request API to manage pull requests effectively. This includes creating pull requests, retrieving them, adding comments, labeling, and approving pull requests.

Before you can use the GitHub API, you need:

  • A GitHub account.
  • A repository to work with.
  • A personal access token with the appropriate permissions (like repo for private repositories) for authentication. You can generate this token in your GitHub account settings under "Developer settings."

To interact with the GitHub API, you must include your personal access token in the request headers:

Terminal
curl -H "Authorization: token YOUR_ACCESS_TOKEN" https://api.github.com

For more details on personal access tokens see this guide on configuring GitHub personal access tokens.

To create a pull request using the GitHub API, you need to POST data to the repository's pull requests endpoint.

Endpoint:

Terminal
POST /repos/:owner/:repo/pulls

Example:

Terminal
curl -X POST -H "Authorization: token YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "Amazing new feature",
"head": "feature-branch",
"base": "main",
"body": "Please pull this in!"
}' \
https://api.github.com/repos/username/repository/pulls

This request creates a new pull request from feature-branch into the main branch of the repository. The JSON body includes the title, head branch, base branch, and a description of the pull request.

To retrieve all pull requests from a repository, you can use the GET method on the pull requests endpoint.

Endpoint:

Terminal
GET /repos/:owner/:repo/pulls

Example:

Terminal
curl -H "Authorization: token YOUR_ACCESS_TOKEN" \
https://api.github.com/repos/username/repository/pulls

This will return a JSON array of all pull requests for the specified repository, including details like the PR number, state, title, and more.

To fetch details about a specific pull request, you need to specify the pull request number in the endpoint.

Endpoint:

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

Example:

Terminal
curl -H "Authorization: token YOUR_ACCESS_TOKEN" \
https://api.github.com/repos/username/repository/pulls/42

This retrieves the details of the specified pull request such as branch information, commit details, merge status, labels, and comments.

To add a comment to a pull request, use the POST method on the issue comments endpoint. Pull requests are considered as issues in the API, so they share the same numbering.

Endpoint:

Terminal
POST /repos/:owner/:repo/issues/:number/comments

Example:

Terminal
curl -X POST -H "Authorization: token YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"body": "Looks great!"}' \
https://api.github.com/repos/username/repository/issues/42/comments

This adds a comment "Looks great!" to the pull request #42.

To add labels to a pull request, you need to send a PUT request with the labels you want to apply.

Endpoint:

Terminal
PUT /repos/:owner/:repo/issues/:number/labels

Example:

Terminal
curl -X PUT -H "Authorization: token YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '["bugfix", "enhancement"]' \
https://api.github.com/repos/username/repository/issues/42/labels

This applies the "bugfix" and "enhancement" labels to pull request #42.

Approving a pull request via the API isn't directly supported, but you can simulate an approval by posting a review comment with an approval state.

Endpoint:

Terminal
POST /repos/:owner/:repo/pulls/:number/reviews

Example:

Terminal
curl -X POST -H "Authorization: token YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"event": "APPROVE", "body": "This is ready to merge!"}' \
https://api.github.com/repos/username/repository/pulls/42/reviews

This submits an approval review for pull request #42 with the comment "This is ready to merge!"

For more information on managing pull requests with the GitHub API, see the official documentation.

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2