Pull Requests

Learn and practice the functionalities of pull requests in the GitHub API.

We'll cover the following

Overview

Being a distributed version control manager, GitHub allows the feature of creating pull requests through which we can share our changes committed to a branch with the contributors. These contributors can then review and add comments for any feedback or changes. The changes can be addressed by adding follow-up commits to that branch. We can also add descriptions of the proposed changes, add labels, add reviewers and assignees, and mention people. Additionally, we can review comments or commits made in that branch in chronological order. Once finalized, the reviewers then approve these changes and then that branch is merged into the base branch.

Create a pull request

Creating a pull request requires granting write access to the head branch. There should be commits between the head and base branches to create a pull request.

Note: The following code extracts the pull number of the pull request to be used later in the lesson.

Press + to interact
headers = {
    'Authorization': 'token {{ACCESS_TOKEN}}',
    'Accept': 'application/vnd.github.v3+json'
}
data = json.dumps({
    'title': '<title>',
    'head': '<head-name>',
    'base': '<base-name>'
})
url='https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}/pulls'
response = requests.post(url, headers=headers, data=data)
print(json.dumps(response.json(), indent=4))

The table below shows the parameters in the body of creating a pull request.

Parameters for creating a pull request

Name

Type

Present In

Description

title

string

body

This is the new pull request title.

head

string

body

This is the name of the branch in which changes are made. If the changes are made in the user’s cross-repository in the same network, the branch is referred to as username:branch.

base

string

body

This is the name of the branch in which the changes are to be merged. This branch should be present in the current repository.

body

string

body

These are the pull request’s contents.

maintainer_can_modify

boolean

body

This is true if the maintainer can modify the pull request. Otherwise, it is false.

draft

boolean

body

This is true if the pull request is a draft. Otherwise, it is false.

issues

integer

body

This is the number of the pull requests.

Get a pull request

To get a particular pull request, we pass the pull number in the URL as done in the code below:

Press + to interact
headers = {
    'Authorization': 'token {{ACCESS_TOKEN}}',
    'Accept': 'application/vnd.github.v3+json'
}
url='https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}/pulls/{{PULL_NUMBER}}'
response = requests.get(url, headers=headers)
print(json.dumps(response.json(), indent=4))

List pull requests

This endpoint lists all the pull requests made in a repository.

Press + to interact
headers = {
    'Authorization': 'token {{ACCESS_TOKEN}}',
    'Accept': 'application/vnd.github.v3+json'
}
url= 'https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}/pulls'
response = requests.get(url, headers=headers)
print(json.dumps(response.json(), indent=4))

List commits on a pull request

The commits on a pull request can be listed through this pull request endpoint. However, a maximum of 250 commits can be listed through this. If we want to retrieve all the commits, we should do it through the “list commits” endpoint.

Press + to interact
headers = {
    'Authorization': 'token {{ACCESS_TOKEN}}',
    'Accept': 'application/vnd.github.v3+json'
}
url= 'https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}/pulls/{{PULL_NUMBER}}/commits'
response = requests.get(url, headers=headers)
print(json.dumps(response.json(), indent=4))

Merge a pull request

When we make a pull request in the head branch, it gets approved and is then merged back into the main branch known as the base.

Press + to interact
headers = {
    'Authorization': 'token {{ACCESS_TOKEN}}',
    'Accept': 'application/vnd.github.v3+json'
}
data = json.dumps({
    'commit_title': '<title>'
})
url= 'https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}/pulls/{{PULL_NUMBER}}/merge'
response = requests.put(url, headers=headers, data=data)
print(json.dumps(response.json(), indent=4))

Check if a pull request has been merged

Now that we’ve merged a pull request, let’s check whether or not the pull request was merged by providing its ID in the path.

Note: This endpoint only outputs the pull request once it is merged.

Press + to interact
headers = {
    'Authorization': 'token {{ACCESS_TOKEN}}',
    'Accept': 'application/vnd.github.v3+json'
}
url='https://api.github.com/repos/{{USERNAME}}/{{REPOSITORY}}/pulls/{{PULL_NUMBER}}/merge'
response = requests.get(url, headers=headers)
print(response)

If the status of the above code returns 204, it means that the pull request is successfully merged. Otherwise, the status will be 404.