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.
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 https://github.com/settings/tokens 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
admin: 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
cURL, 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
GitHub 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
state as body parameter and token as
Authorization 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
labels 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
public or not, next you need to populate list of
files that will be part of said Gist, where each key is a file name and its
content contains actual string content of the file. The code above uses
json.dumps() 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
push function, we create new branch originating from commit specified using
source.commit.sha. Based on the
if 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 (
author 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.
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
views object contains
views 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
View objects that contain view
count for each day and respective
timestamp which we extract into list of tuples. We then find tuple with maximum
count and print its date and actual view count on last line. This gives us output shown below:
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
text body parameter together with mode set to
markdown. The example
text above includes,
code 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 —
success - in this example I chose
success. Next, the
target_url is the URL to which the Details link points. And as you probably noticed, the
context are the other values shown in dialog box shown below.
To be able to verify that status change actually went through, we receive
CommitStatus 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
-1 to somebodies comment. Maybe just throw in some celebratory
hooray 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
repo name and this
comment_id in the URL and emoji name (e.g.
hooray) in the
content body parameter. Additionally we need to also include
Accept header, as this endpoint is part of developer preview.
The expected response here is either
201 which means that reaction was created or
200 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!