Building our first GitHub App

Published in

The Startup

8 min readAug 31, 2019

A step-by-step guide to build GitHub Apps and automate our workflow

GitHub Apps are a great way to improve and automate our workflow. They allow us to automate our project workflows and improve the code quality. There are numerous apps already present in the GitHub marketplace. They are also the secure and safer way to allow access to our repository. These apps allow us to add actions in our CI/CD flows like code reviews, PR action, format checks etc.

In this article, we’ll take a look at how we can build our own GitHub app, allowing us to integrate custom actions into our workflow. We’ll build our app using Node JS as the platform.

Tech Stack and Prerequisite

GitHub Account — to register the app
Node JS (>= 8.3.0) — to build our app
Probot — Node JS framework for building GitHub apps
Heroku — for hosting the app (you are free to choose other providers)

Creating and setting up the App

Before we can start implementing our workflow, we need to create an app on GitHub. This app will enable us to acquire different permissions, receive webhooks for event (actions) happening on a repository and perform some actions on them among other things.

The simplest way to create a GitHub app is to go to GitHub itself:

Go to the Settings page of our profile.
Go to Developer Setting from the left menu.
Click on the New GitHub App button.

But since we are using Probot as our framework for building the app, we’ll use it’s command line tool to create and register the app on GitHub.

Create GitHub App Using Probot

The following steps assume that we have node js installed and the version is 8.3.0 or later.

Run the following command in the command prompt:

npx create-probot-app <App name>

Please note that the app name should be unique across the GitHub, so you might not get the name you want at first!

Above command will walk you through the details required for the app, like app description.
The result of this command would be a node js project with structured code and dependencies in place.
The project also contains skeleton code to capture one event. The event is for issue creation on GitHub repository (more on events later). And as part of the action on that event, a comment gets added.
Now that we have the project ready, let’s register this app on GitHub.
Run the project using following command:

npm start

Now go to the web browser and open the link : http://localhost:3000
Click on the Register GitHub App button on this page. This will show a new page.
Enter GitHub account’s credentials.
Now a new page will open up. Enter the GitHub app name and click on the create GitHub app button.
Next up is selecting the repository to install the app into. On the next page there will be the list of repositories. Select one to test the app.
Make a note of .env file generated in the application code. This would be needed when we host the application.

Here is the probot documentation for further reference.

Managing Webhooks

One important aspect of GitHub Apps is webhooks. We need to setup the webhook to receive the events from our repository. We need two things for our webhook to work:

Webhook URL — where our app is running
Webhook secret — for security reasons

When we created our app in the previous step, Probot created and added a public webhook URL and secret to our repository. This webhook allows us to test our before we procure a cloud instance and host our app.

To update these values, we can go to the settings page (detailed below). The URL would be

https://github.com/settings/apps/<App Name>

Managing the Events via Webhooks

Once our app is created and registered on GitHub, we are eligible to receive events, in the form of webhooks, for certain actions happening on any repository. As we saw in the steps above, while registering the app itself, we can install it into our repositories. But if we want to test the app in additional or other repositories, we can do so using the app’s public link. Let’s take a look at the steps:

Go to app’s GitHub page:
The URL would be of the format:

https://GitHub.com/apps/<App Name>

There would be an option to install/configure the app.
Once we start the process, we could see a list of repositories to select from.

The app we generated using Probot would have built a skeleton webhook for capturing one event and the actions to be taken on this event. This sample would help us to understand the flow and build our own.

To go through the sample, open index.js file at the root of the project. Here, we see the code for handling the event issues.opened. This event let’s us perform an action whenever an issue is created in the repository.

In the similar manner, we can capture as many events as we need. These events also bring some context with them, which can be used to extract data related to the event. For example, for issues.opened event, we can get the issue id. These details help us to perform our action, like commenting on the issue in this case.

Here is the full list of events we can capture.

Testing the App

Now that we have our app setup and we have an understanding of the events, let’s test our app locally. Since we already have one event captured in our app, we will use the same to test the app.

Make sure the app is running locally
Go to the repository which has the app installed
Create an issue
Once we create the issue, the event should be triggered and captured by our app.
As per the implementation, a comment should be added to the issue saying — Thanks for opening this issue!

If you see the comment, the app is setup properly and we can start building the workflow of our choice.

Managing the Permissions

There would be some actions for which we would need to ask for certain permissions from the repository owner. For example, if our workflow requires us to check the code for linting, we would need appropriate permission, like read/write access to code.

As we build and test the app, we would keep on recognizing these permissions. But how do we get those permissions into our app?

There is a settings page for our apps where GitHub allows us to set the permissions required by the app. Whenever a user would install our app, they would be asked to grant these permissions to the app.

To access this settings page:

Go to settings page of the profile
Look for Developer Settings option.
Under this, there is a GitHub Apps link.
This link will show all the apps that belong to us.
Click on Edit in front of the app name.
Go to Permissions and Events to edit the permissions.

Here is the list of all the permissions.

Configuring the app

We just saw how to configure the permissions required by the app. But this is not the only configuration required by the app. The other settings include things like:

App name (yes, we can still change the name if we need to)
App description
App’s public home page
App’s setup URL

There are a few other settings. Check these at:

https://GitHub.com/settings/apps/<App Name>

Hosting

We have looked at developing the app, registering on GitHub, configuring the app and the permissions required. Now we need to host our app, so that we can go live with it and offer it to other people for use.

Remember that the app works on the basis of events generated from the GitHub repository. These are to be captured by our webhook. And to do that, we need to host our app. For this article, we’ll host the app on Heroku. It provides us an easy way to deploy and host our Node JS application. And since we don’t need any database (yet), we can try the hosting for free.

Look at this tutorial on how to deploy a Node JS app on Heorku if you have not done this before.

Once the app is up and running on Heroku:

Update the environment variables.
Generate a webhook secret and add it to environment variables.
Update webhook URL and secret in GitHub app configuration.
The webhook URL should be the base URL of the newly deployed Heroku app.

Installation

Once we have hosted our app, we can distribute the app or use it in our project repositories. Please note, that we have not published the app yet, which means that we would have to distribute the app manually. To distribute the app, provide the URL of the app which would look like:

https://GitHub.com/apps/<App Name>

Once a user visits this page, with GitHub logged in, they would be given an option to install the app. Just click on that button and follow along to configure the app for the repositories.

Listing on GitHub Marketplace and Review

We are now ready to publish our app on GitHub Marketplace. It’s important to publish the app to distribute it amongst the GitHub users. Once the app is available on the marketplace, users can just search the app and install it into their repositories.

Publishing the app requires us to fill a certain details about the app, like the description (short and detailed), app logo, contact page etc. Just follow through the marketplace publish link present on the settings page of the app.

There are two ways to publish:

With GitHub review
Without GitHub review

If we go with GitHub review, the first thing we need to achieve is 100 installations. These could be through manual distribution, or by publishing the app without review. Post that, we would be able to ask GitHub for review of our app. Read these guides to make sure GitHub rules are followed and review goes smoothly.

Once published, you can search the app on the marketplace.

Conclusion

Creating and publishing an app of GitHub requires a number of steps. These steps have to be performed in their specific required order. And this might seem a complex task at first. But when we start doing it, we realize that it’s as simple (or complex) as any other Node JS backend app. We need to capture the events with the webhooks, which are similar to writing the APIs. We then need to register the app with some simple steps and that’s it.

I hope that this article would help you to build your own and improve the development to deployment workflows for your project. And probably you would publish the apps to help others improve their workflows!!

Check out the GitHub app, Commit Message Lint, developed by our team at Systango.

This article was originally published on Systango