Open a Pull Request via the GitHub API
Introduction
When working on new features or bug fixes within your app, using the GitHub UI to open pull requests can quickly become tedious. You have to navigate to the GitHub repo in question, select the branch you are trying to submit a pull request to, and then go through the further steps related to creating your pull request. The GitHub developer API aims to abstract all of this away into one simple HTTP call. This API can save you tons of time over the long term.
This guide will demonstrate how you can use the GitHub API to create your pull request for you by creating your own command line or UI in order to take away a bunch of the manual steps needed in this process.
Let's dive in!
API Overview and Setup
The GitHub API is split into two big sections: REST and GraphQL. This guide will use the REST API, although the GraphQL API is a great alternative if you are used to working with GraphQL.
The first thing you need to do is install the @octokit/core NPM dependency. This is GitHub's core developer toolkit, and is the NPM package this guide will use to interact with GitHub's REST API. To install this dependency, navigate to your top-level project directory and run:
1npm install --save-dev @octokit/coreWith this dependency installed, your next step will be to generate a personal access token so that your program can successfully authenticate with GitHub's REST API. To do this, navigate to the token settings portion of your GitHub account and follow the onscreen steps.
With your dependencies downloaded and your personal access token ready to go, it's time to start interacting with the GitHub API.
Programmatically Creating a Pull Request
The GitHub API provides a number of options for creating a pull request. You can view these options and the available configuration here.
Now that you'r in your JavaScript code, it's time to see what this API can do!
Note: Don't forget to keep your authorization token a secret! Don't check your token into source control!
1import { Octokit } from "@octokit/core";
2
3const octokit = new Octokit({ auth: 'your-token!' }),
4 owner = 'test-user',
5 repo = 'test-repo',
6 title = 'My Test Pull Request',
7 body = 'This pull request is a test!',
8 head = 'my-feature-branch',
9 base = 'develop-branch';
10
11const response = await octokit.request(
12 `POST /repos/{owner}/{repo}/pulls`, { owner, repo, title, body, head, base }
13);Wow, that was really simple! As you can see, first you need to import the Octokit class from GitHub's developer API project. Once you instantiate an instance of the Octokit class with your personal access token, you can then use the request method to open a new pull request. The above example uses a lot of the options that are available for this particular API request. The following list is a breakdown of the most common options to use:
- owner: A required option that specifies the username of the owner of the repo
- repo: A required option, this is the repo name in question
- head: A required option that gives the API the name of the branch that contains your changes
- base: A required option that gives the API the name of the branch that you are attempting to alter
- title: This option is not required. This is the title of your pull request.
- body: This option is not required. This is the pull request description.
After running the above code, you can now navigate to the GitHub repo in your browser and see your submitted pull request!
Conclusion
The GitHub developer API provides a rich layer of capabilities for interacting programmatically with your GitHub codebase. There's much more available to you then just simply creating a pull request too! I encourage you to check out the GitHub REST API documentation to see the plethora of options you have available.