GitHub pull request API

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.

Prerequisites

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."

Authentication

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

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.

1. Create a pull request

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

Endpoint:

POST /repos/:owner/:repo/pulls

Example:

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.

2. Get all pull requests

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

Endpoint:

GET /repos/:owner/:repo/pulls

Example:

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.

3. Get a specific pull request

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

Endpoint:

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

Example:

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.

4. Add a comment to a pull request

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:

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

Example:

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.

5. Add labels to a pull request

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

Endpoint:

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

Example:

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.

6. Approve a pull request

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:

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

Example:

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.