GitHub Apps in Golang
This is the written form of one of my presentations, which can be found here.
First, what is a GitHub App?
According to GitHub documentation, GitHub applications are the officially recommended way to integrate with GitHub, which essentially means that it is the way GitHub prefers you to write code around GitHub events.
Not sure what I mean?
Check out the GitHub docs for available endpoints. You can write code that responds to different GitHub events, like when a pull request opens or closes, someone comments on a pull request, or a status check passes or fails.
Why would I want to respond to GitHub events?
Automation is our friend. We want to automate as many, if not all, of our mundane, daily developer activities as possible. Computers are really great at repeatable tasks, so adding scripts to our continuous integration systems allows humans to spend less time on things that computers are great at and instead spend time doing other things, like making features. One example that many developers will already be familiar with are services like Jenkins or Travis CI that will receive a webhook event from GitHub when a pull request is opened or a new commit is pushed to kick off testing or other scripts. You can also write code that responds to events like these using GitHub apps.
GitHub applications have two parts:
- A GitHub application created on github.com on a GitHub organization that subscribes to certain events and has certain permissions for repositories that the application is installed on.
- An API that receives events for the configured GitHub application in part 1 and responds to those events in some way, however you like. The API authenticates each incoming request with the webhook secret token generated in part 1. The API can be created in any language; programmer’s choice.
This quickstart guide goes through all of the essentials for setting up a GitHub App in github.com and a development environment, including using a proxy service like smee.io to develop against before the API is deployed.
What about Golang?
Golang is a statically-typed language that was created at Google in 2007, made publicly available in 2009, and focuses on speed and performance, among other features.
According to the Go designers:
Every language contains novel features and omits someone's favorite feature. Go was designed with an eye on felicity of programming, speed of compilation, orthogonality of concepts, and the need to support features such as concurrency and garbage collection. Your favorite feature may be missing because it doesn't fit, because it affects compilation speed or clarity of design, or because it would make the fundamental system model too difficult.I wanted to learn Golang this year and therefore decided to write two GitHub apps in go for work purposes. I extracted the code needed to generate one of these apps into a boilerplate repository found here so anyone can get started writing a GitHub application in Golang easily.
This Golang GitHub App boilerplate repository is a simple Golang API setup with the middleware GitHub requires to validate incoming webhook requests against secrets generated in github.com. This should be a given, but never store secrets in GitHub, ever. Secrets are not to be stored in source control, they should be stored in a valid secrets manager and only securely available on deployed environments for the applications. A private key (also a secret) is also generated in github.com for the GitHub app and this is used to create a github client for the GitHub app in order to make GitHub API calls from inside of the API. This key has permission for only the actions specified in github.com for the app. Don’t worry! Here is a step-by-step guide for setting up a GitHub App in github.com.
Below is a diagram of the repo code structure, which is the structure recommended by Golang documentation. I used the dependency manager tool dep for go dependencies, but eventually I want to convert this to use go modules to not have to include all of the dependencies in the repository. For now this works fine. The repository README.md file includes steps to get the application running and information for storing your secrets in an s3 bucket if you are using AWS deployment services.
The two main golang libraries used for working with GitHub are:
google/go-github — all the functionality for interacting with the GitHub API
bradleyfalzon/ghinstallation — authentication as a GitHub App
I hope this short guide gives you the urge to try out writing a GitHub Application in Go and get all the automation running in your GitHub repositories!
Happy Go GitHub App coding!
Helpful documentation:
