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.

Step 1 - Create a playground project

Create a test repository that will serve as a playground for experimenting.

We will install our GitHub App in this repository.

Step 2 - Register the application

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 Settings > Developer Settings > GitHub Apps > New GitHub App.

Fill in the following information.

Application name

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.

Homepage URL

The homepage URL could be, for instance, the URL of your app’s repository.

Identifying and authorizing users

You can skip this section for now: it’s not useful for a minimal app.

Post installation

You can skip this section for now: it’s not useful for a minimal app.

Webhook URL

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.

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.

You can also use services like ngrok.

If you do, make sure you use a named domain.

Webhook secret

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:

pwgen -N 1 -s 40

This webhook secret will be required later so keep it around.

Permissions

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.

Subscribe to events

If you don’t subscribe to any event, your webhook URL will never be called.

For experimenting, subscribe to Issues, Issue comment and Pull request.

Now, you can click on Create GitHub App.

Step 3 - Create a private key

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.

Step 4 - Install your app

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 Edit and Install App).

That’s it

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.