All the Things You Can Do With GitHub API and Python

By Martin Heinz

Martin Heinz

Most of us use GitHub every day either using CLI or its website. Sometimes however, you need to automate these same tasks like, for example creating Gist, querying repository analytics or just pulling, modifying and pushing new file. All these things and more can be done easily using GitHub API, and Python is here to help with that and make it even easier.

Original Photo by BAILEY MAHON on Unsplash

What We Will Need

Before we start using GitHub API, we first need to generate a personal access token that will allow us to authenticate against the API. We can get one at by clicking on Generate new token. You will be asked to select scopes for the token. Which scopes you choose will determine what information and actions you will be able to perform against the API. You should be careful with the ones prefixed with , and as these might be quite destructive. You can find description of each scope in docs here.

Now that we have the token, let’s test whether it actually works:

And here is the expected (trimmed) response showing list of my public Gists:

Doing It With Python

We have the personal token and we tested it with , so now we can switch to doing the same thing in Python. We have two options here though. We can use raw requests or we can use .

PyGitHub exposes some of the GitHub API endpoints for most common operations like repository, issue or branch management. It can’t be used for every single feature exposed through the GitHub API, so in the following sections, I will show mixture of PyGitHub and Requests calls depending on whether it can be done with PyGitHub or not.

First things first though — let’s install both libraries ( PyGitHub and Requests) and see a simple example for both:

Example using PyGitHub:

Example using Requests:

Both snippets above use the same API endpoint to retrieve all open issues for specified repository.

In both cases we start by taking GitHub token from environment variable. Next, in the example with using PyGitHub we use the token to create instance of class, which is then used to get repository and query its issues in open state. The result is paginated list of issues, of which we print the first page.

In the example that uses raw HTTP request, we achieve the same result by building API URL from username and repository name and sending GET request to it containing as body parameter and token as header. Only difference is that result is not paginated. Here is the result for both examples:

First one being PyGitHub output:

Second, raw Python list of dictionaries (JSON):

Create an Issue

While on topic of issues, let’s create one too, shall we?

This is one of the use cases, where PyGitHub is very handy. We just need to get the repository, create issues against it and specify bunch of parameters. In the snippet above we use , , and parameters, but you could also add milestone or more labels which are queried using their name.

Create a Gist

Another things we can create is GitHub Gist, this time using Requests:

The request for creating Gists is pretty simple. In the POST request you need to specify whether the Gist should be or not, next you need to populate list of that will be part of said Gist, where each key is a file name and its contains actual string content of the file. The code above uses to convert Python dictionary to JSON string to create request body and the usual Authorization header.

Below you can see the relevant parts of the expected response:

After creating a Gist you might want to do other things with it like update it, list commits, fork it or just fetch it. For all these operations there’s a API endpoint listed in these docs.

Programmatically Update File

One very practical, but quite complicated use case for using GitHub API, is programmatically fetching, modifying, committing and finally pushing some file to repository. Let’s break this down and see an example:

Starting from the top, we get contents of a file using the usual repository reference, decode it to plain string and modify it. Next, in the function, we create new branch originating from commit specified using . Based on the statement, we have 2 options update existing file or create new one. In case we're doing update, we first retrieve existing file to get its hash and path and then we perform the update using previously modified data ( ), supplied , and object. If on the other hand we want to create a new file in the repository, then we just omit passing in the SHA of existing file and we're done.

Analyzing Traffic

If you are more into data science and analytics you might find useful possibility of querying views/clones statistics from your repositories:

The code needed to retrieve the data from GiHub is really just one line for clones and one line for views. Both the and object contains , and attributes. We use the first 2 in the print statements to show actual and unique clones and views respectively.

The disgusting (beautiful) one liner after that iterates over list of objects that contain view for each day and respective which we extract into list of tuples. We then find tuple with maximum and print its date and actual view count on last line. This gives us output shown below:

Rendering Markdown

This example uses GitHub API, but can be used for non-GitHub purposes. I’m talking about GitHub APIs ability to generate HTML from markdown text. This could be useful if you have website that can’t render markdown directly, but rather you could use GitHub API to create HTML for you.

Once again the query is quite simple. All we need to do is send the text to be rendered in body parameter together with mode set to . The example above includes, snippet, italics and bold text and that's exactly what we get back in form of HTML:


Update Commit Status

You know these nice green check marks, yellow circles and ugly red crosses next to your commits that are added by CI tools? Do you want to change them (maybe just for fun, maybe as part of your own CI solution)? Of course you do. And there is API for that:

Surprisingly (for me) this obscure API endpoint is part of PyGitHub library. To use it, we retrieve repo and its commit using commit hash. After that we create status for said commit, by describing its current state using parameters.

There are 4 states we can specify, namely — , , , or - in this example I chose . Next, the is the URL to which the Details link points. And as you probably noticed, the and are the other values shown in dialog box shown below.

To be able to verify that status change actually went through, we receive response which is representation of current status of commit. In this case looks like this:

Adding Reactions to Issue Comments

GitHub issue comments allow you to add various reactions to them. So, maybe you want to add / to somebodies comment. Maybe just throw in some celebratory emoji. If that's the case, then here's how you could do that in Python:

To be able to create response, we will need the comment ID. It can be retrieved from API shown here in docs or by clicking on the three dots icon in upper right corner of issue comment and clicking Copy Link:

With that we can insert username, name and this in the URL and emoji name (e.g. ) in the body parameter. Additionally we need to also include header, as this endpoint is part of developer preview.

The expected response here is either which means that reaction was created or in which case the reaction was already added previously.

And here is (trimmed) JSON response body, that we get back:


Playing with public APIs is great way to start a new project (e.g. CI tools, Repository traffic analytics, GitHub Bots) and GitHub API has a lot of data/content for such a thing. What I showed here is just a small sample. To explore full API see docs here or if you don’t feel like messing with the REST API, then check out PyGitHub Examples.

If you liked this article you should check you other of my Python articles below!