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.
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.
- Create a JWT containing Private Key, include it in the Authorization header and send it
- Check this JWT on GitHub side, and if ok, issue an access token that allows access to the installed repository
- Use this access token to execute the API
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.
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.
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
- For OAuth Apps, there must be at least 1000 registered users
- For GitHub Apps, there must be at least 250 installations
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.
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