Automate Project Workflows with a GitHub App

Create a GitHub App

Github Apps are a great way to improve our workflow. They allow us to automate our project workflows and improve the code quality. Github marketplace serves more than 100,000 users and offers almost 50 tools. There are numerous apps already present in the Github marketplace. Github apps are also a secure and safe 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 Pre-Requisites

  • Node JS (>= 8.3.0) — to build our app
  • Probot — Node JS framework for building Github apps
  • Heroku — for hosting the app (there is no restriction on which hosting provider to use.

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 its command-line tool to create and register the app on Github.

Create Github App Using Probot

  • 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 wanted 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 a 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 the following command:
  • npm start
  • Now go to your 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 your GitHub account’s credentials.
  • Now a new page will open up. Enter your 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 a 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.
Create a Github App — Code
Create a Github App — Code

Managing Webhooks

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

  • 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 lets us perform an action whenever an issue is created in the repository.

Similarly, 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

  • 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 set up properly and we can start building the workflow of our choice.

Managing the Permissions

As we build and test the app, we would keep on recognising 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 the 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 Event’ to edit the permissions.
Permissions — Create a Github App
Permissions — Create a Github App

Here is the list of all the permissions.

Configuring the app

  • 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>

Configure — Create a Github App
Configure — Create a Github App

Hosting

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:

  • 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

Publishing the app requires us to fill 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:

  • 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.

Publish — Create a Github App
Publish — Create a Github App

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

Summary

Our team at Systango has already built a number of applications on Github from the ground up and helped improve workflows drastically. We are a UK based digital product development agency that can help you not just with Github apps but tech consulting, web & app development on various technologies. With an experience of working on 300+ projects, we are equipped & excited for our next one with you.

If you wish to ease up your productivity and scale up your workflows with Github Apps hire tech experts at Systango. Contact us to know more.

This blog was originally published on Systango.

London’s leading digital agency Systango offers full service from strategy, scoping to launch & maintenance, innovative campaigns to enterprise infrastructure.