Register a GitHub App
The first step when working on a new GitHub App is to register it on GitHub.
That is one of our main differences with Probot: we don’t perform the magic to register your application when initializing it.
For now, we think it is better that you understand what you are doing when registering your application, especially since you will need to do it again when pushing your app to production.
We might revisit this decision at a later stage depending on your feedback.
Create a test repository that will serve as a playground for experimenting.
We will install our GitHub App in this repository.
To register a new application, go to GitHub Apps and click
New GitHub App.
You can access this page by clicking on your profile picture at the top and then
Developer Settings >
GitHub Apps >
New GitHub App.
Fill in the following information.
When you are going to push your app to production, you will register a new GitHub App.
So you might want to make it clear in the name that this app is for development/test.
You can skip this section for now: it’s not useful for a minimal app.
There is a good chance your development box is not directly accessible from the Internet.
To solve this issue, GitHub provides the Smee.io service which uses Server Side Events to distribute the events to your locally running app.
Go to https://smee.io/ and click on
Start a new channel.
The URL in the
Webhook Proxy URL field at the top will be your webhook URL.
Keep it around, we will need it later.
For now, you don’t need to set up a webhook secret: secret signature checking is disabled when using Smee.io as it modifies the original payload.
No need to start a Smee.io client: Quarkus GitHub App connects to Smee.io automatically when a webhook proxy url is defined in your configuration.
When running in dev mode, we don’t enforce signature checking (one big reason for this is that Smee.io doesn’t pass the payloads as is).
However it is good practice to define a webhook secret as it is enforced in production mode.
To generate a webhook secret, you can use the method recommended by GitHub:
ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'
You can also use
pwgen -N 1 -s 40
This webhook secret will be required later so keep it around.
Depending on what your application will do, you will need to set up the appropriate permissions.
Just start with enabling the Issues and Pull requests
Read & write Repository permissions.
That is a good starting point to experiment.
You can add more permissions later but each installation of your GitHub App will need to validate the added permissions.
That is not really a problem when developing your app so don’t overthink it.
The GitHub documentation contains a good reference of the permissions required by each REST API call.
Now that you have registered your first GitHub App, there is one more thing you need to do: generate a private key.
Scroll down, and in the
Private keys section, click on
Generate a private key.
You will be asked to download the key, keep it around, we will need it later.
Install the GitHub App in your playground project.
This can be done from the
Install App tab of the application’s page (https://github.com/settings/apps then
OK, there is a lot more you can do in there and we will discuss more things in details later, but for now, you are done: you have registered your first GitHub App and you can start experimenting with it.