A new form of app that works with GitHub: How to make GitHub Apps

GitHub Apps is a new form of application that works with GitHub. This format is an application marketplace, [announced with the release of the GitHub Marketplace](https://github.com/blog/2359-introducing-github-marketplace-and-more-tools-to-customize- your-workflow). In other words, we have a solid ecosystem of creating GitHub Apps, publishing them on the marketplace, and making money from them.

In this article, I will introduce how to make GitHub Apps that spreads such dreams.

Application format that works with GitHub

First, organize the formats of applications that work with GitHub, including GitHub Apps.

Webhooks

Webhooks is a format that triggers a specific event (such as pushing) in the repository and notifies the update information to the server etc. of the setting destination. .. Make the settings in the following locations. Here, you can also set the event to be notified.

In addition, Webhooks can be set in units of Organization [https://developer.github.com/v3/orgs/hooks/), in which case it is possible to receive events of all repositories under Organization. Become.

However, since Webhooks are "just receive", you cannot do anything to the GitHub repository side (such as commenting on Issue). If you need to take any action on the GitHub repository side, you need to use the following OAuth Apps together or use GitHub Apps.

OAuth Apps

As the name (OAuth) suggests, OAuth Apps is a format that uses the authentication information of the GitHub user account to operate on the GitHub repository. Therefore, when creating OAuth Apps, you need to register from Settings> Developer settings of the user account.

This is used not only for apps that work with GitHub, but also for developing sites that simply use GitHub user accounts as authentication information (login information). For OAuth authentication, Authenticate with page transitions in between -options-for-oauth-apps / # web-application-flow) is a service that works with the backend. Since there is no screen in the first place, [Offline authentication flow is also supported](https://developer. github.com/v3/oauth_authorizations/#get-or-create-an-authorization-for-a-specific-app).

Due to the characteristic of OAuth Apps that uses "GitHub user account credentials", if the user loses access privileges or closes the account, the cooperation will naturally end. This is rather natural for personal use, but it is not preferable when developing a team (such as a person who withdrew from a project member set up cooperation!). In addition, it is possible that you may not know who is working with OAuth.

In other words, OAuth Apps are suitable for apps / sites that "GitHub users" use personally, but they are a little problematic as apps for "GitHub repositories" managed by teams.

GitHub Apps

GitHub Apps is a format suitable for developing apps for the "GitHub repository" as opposed to the OAuth Apps mentioned above. This is because the installation unit is the repository unit held by the user / Organization.

Since it can receive not only access to the repository but also the occurrence of events in the repository (with webhooks), it is useful for developing applications that "react to specific events in the repository and do something with the repository". This is the optimal method. Since OAuth authentication can also be performed, in addition to using it for login authentication, on behalf of the user (with the user's access token) instead of as GitHub Apps -integrations / setting-up-and-registering-github-apps / identifying-users-for-github-apps /) It is also possible to process the repository. This can be used when creating a repository-based site like Gitter (I think there will be many ideas for chat, task management, etc.).

The detailed differences in authentication methods are described below.

About choosing an integration type

This time, we will look at the development of this GitHub Apps.

Development of GitHub Apps

From here, we will look at the procedure for actually developing GitHub Apps.

Register for GitHub Apps

First, register the GitHub Apps to be developed. This registration is possible for each user or organization. Follow the steps below to register.

Registering GitHub Apps

The GitHub Apps registered here will be installed and used by your users in the repository. The Permissions registered here are required for GitHub Apps to be developed, and are the permissions granted by the user who installs them.

GitHub Apps Authentication

If you use OAuth authentication with GitHub Apps, it will be the same as OAuth. In this case, the API is used by using the user's access token, so it is not possible to perform operations that the authenticated user cannot perform.

When authenticating as GitHub Apps, you can use the access token obtained there to operate the privileges granted by Permissions. This time we will look at the authentication process.

About authentication options for GitHub Apps

To authenticate as GitHub Apps, you will need the Private key (pem file) obtained when you registered for GitHub Apps. Using this, authentication is performed by the method JSON Web Tokens (JWT). The flow is as follows.

image.png

The package that creates JWT is developed in each language, and you can use the one that matches the implementation language (note that you have to encrypt with RS256 for authentication on the GitHub side. please).

Libraries for Token Signing/Verification

In addition, this certification was quite successful. I need to specify the validity period of the access token (up to 10 minutes), but sometimes this date and time check worked or failed. This point [although everyone was addicted](https://platform.github.community/t/issued-at-claim-iat-must-be-an-integer-representing-the-time-that-the- assertion-was-issued / 1549), I made the issue date and time a little earlier so that the authentication can be passed stably.

The code that authenticates with the recently created GitHub Apps is the following part, so please refer to it when implementing it.

chakki-works/typot/env.py

Implementation of processing for GitHub repository

After authentication, you can use the GitHub API to perform various operations on the GitHub repository.

In addition, GitHub plans to make the API based on GraphQL, so I used this when creating it in the future I think it's better.

Testing GitHub Apps

Due to the format of GitHub Apps, a test repository is indispensable for testing. Install the created GitHub Apps in this test repository and check if the process is triggered for a given event and if the process for the repository works properly. Global access is required for testing webhooks and authentication, but deploying to some server one by one is a bone, so it is convenient to use ngrok.

However, you still have to register an issue to actually trigger the event. Fortunately, from the "Advanced" tab on the registration page of GitHub Apps, "Redeliver" that resends previously published events is possible, so it is recommended to use this.

image.png

After that, I personally saved the JSON actually issued for local testing in a test file and used it.

As you can see, the test is quite a pain, but once this is done, it will be open to the public!

Release of GitHub Apps

The developed app is now available on the market! You might think, but I have to tell you a sad fact.

Requirements for listing an app on GitHub Marketplace

There are other requirements in terms of security, but I think the above two points are the most difficult to meet. It means that the new-born app is not.

The number of installed repositories cannot be confirmed on the screen at this time, and it is necessary to confirm by hitting the following API.

GitHub Apps/Find installations

Please refer to the GitHub Apps created the other day for a script that counts.

chakki-works/typot/get_installations.py

Then, isn't there a place to publish it? There is a light version of the site called Works with GitHub.

Works with GitHub

You can apply for this if it conforms to the terms of service of GitHub (Click here for details](https://developer.github.com/apps/adding-integrations/adding-integrations-to-works-with- See github / requirements-for-adding-an-integration-to-works-with-github /)). Please note that once you apply, you cannot modify the Description, etc., and after approval, you must contact the counter to modify it. [It seems that they are reviewing every Friday](https://developer.github.com/apps/adding-integrations/adding-integrations-to-works-with-github/adding-an-integration-to-works -with-github /), it's a good idea to apply before Friday.

However, although I have been using GitHub for a long time, this is the first time I have learned about the existence of this site, and the googleability of "Works with GitHub" is abnormally low, so I can not get caught in the search (as a bonus) There is no link from the GitHub portal). Therefore, the benefits listed here may be small.

Finally, I would like to introduce the GitHub Apps repository I created. I hope it will be helpful for your implementation.

chakki-works/typot (If you find it useful, I would be encouraged if you could give me a Star m (_ _) m)

Please refer to the following article for the function.

Bot that automatically detects typos hidden in Pull Request and acts on behalf of correction

Let's do our best to take the world on the GitHub Marketplace!

Recommended Posts

A new form of app that works with GitHub: How to make GitHub Apps
How to develop a cart app with Django
How to make a dictionary with a hierarchical structure.
How to create a multi-platform app with kivy
How to make a Raspberry Pi that speaks the tweets of the specified user
How to make a shooting game with toio (Part 1)
Basics of PyTorch (2) -How to make a neural network-
How to deploy a web app made with Flask to Heroku
How to make a Cisco Webex Teams BOT with Flask
[Python] How to make a list of character strings character by character
How to make a simple Flappy Bird game with pygame
How to display a list of installable versions with pyenv
How to make a Japanese-English translation
How to make a slack bot
How to make a crawler --Advanced
How to make a recursive function
How to make a deadman's switch
How to make a crawler --Basic
How to make a surveillance camera (Security Camera) with Opencv and Python
Here's a brief summary of how to get started with Django
Slack --APIGateway --Lambda (Python) --How to make a RedShift interactive app
Node.js: How to kill offspring of a process started with child_process.fork ()
[Python] How to make a matrix of repeating patterns (repmat / tile)
I tried to make a mechanism of exclusive control with Go
How to create a clone from Github
How to call a POST request that supports Japanese (Shift-JIS) with requests
[EC2] How to take a screen capture of your smartphone with selenium
I tried to implement a blockchain that actually works with about 170 lines
How to add a package with PyCharm
[Python] How to make a class iterable
Try to make a kernel of Jupyter
How to make a rock-paper-scissors bot that can be easily moved (commentary)
[Introduction to Python] How to sort the contents of a list efficiently with list sort
A memorandum of how to write pandas that I tend to forget personally
How to draw a bar graph that summarizes multiple series with matplotlib
How to make a Backtrader custom indicator
How to make a Pelican site map
Summary of how to build a LAMP + Wordpress environment with Sakura VPS
I tried to make a simple mail sending application with tkinter of Python
Find out how to divide a file with a certain number of lines evenly
I tried to make a translation BOT that works on Discord using googletrans
[Introduction to Python] How to get the index of data with a for statement
How to make a dialogue system dedicated to beginners
How to read a CSV file with Python 2/3
A simple example of how to use ArgumentParser
How to send a message to LINE with curl
A memorandum to make WebDAV only with nginx
How to draw a 2-axis graph with pyplot
Try to make a "cryptanalysis" cipher with Python
How to specify attributes with Mock of python
How to implement "named_scope" of RubyOnRails with Django
Try to make a dihedral group with Python
How to Implement a new CPUFreq Processor Driver
Make a LINE WORKS bot with Amazon Lex
How to make Linux compatible with Japanese keyboard
I made a twitter app that decodes the characters of Pricone with heroku (failure)
Convert images from FlyCapture SDK to a form that can be used with openCV
How to use a library that is not originally included in Google App Engine
[Mac] I want to make a simple HTTP server that runs CGI with Python
How to publish GitHub Pages with Pelican, a static HTML generator made by Python
The theory that the key to controlling infection with the new coronavirus is hyperdispersion of susceptibility