Create a GitHub App

Initialize your Quarkus application

A Quarkus GitHub App is a standard Quarkus application.

You can create one including the Quarkus GitHub App extension using the following Quarkus CLI command:

Make sure you use the 📋 button to copy the command. 
quarkus create app \
    -x quarkus-github-app \ (1)
    org.acme:my-github-app (2)
1 The Quarkus GitHub App extension.
2 The GA of your Maven project.

On Windows and macOS, it is recommended to concatenate all the options on one line (without \), as the \ might not be correctly interpreted.

We highly recommend the usage of the Quarkus CLI but if you cannot install it or prefer using Maven, you can create a Quarkus GitHub Action project using the following Maven command:

Make sure you use the 📋 button to copy the command. 
mvn io.quarkus:quarkus-maven-plugin:3.15.2:create \
    -DplatformVersion=3.15.2 \
    -DprojectGroupId=org.acme \ (1)
    -DprojectArtifactId=my-github-app \ (2)
    -Dextensions="io.quarkiverse.githubapp:quarkus-github-app:2.8.2" (3)
1 The groupId of your Maven project.
2 The artifactId of your Maven project.
3 The Quarkus GitHub App extension.

On Windows and macOS, it is recommended to concatenate all the options on one line (without \), as the \ might not be correctly interpreted.

This command creates a regular Quarkus Maven project. You can add additional Quarkus extensions or Java dependencies.

Once the project is created, go to the my-github-app directory.

Initialize the configuration

As the configuration is environment-specific and you probably don’t want to commit it in your repository, the best is to create a .env file.

The content of your .env file should be as follows:

QUARKUS_GITHUB_APP_APP_ID=<the numeric app id>
QUARKUS_GITHUB_APP_APP_NAME=<the name of your app>
QUARKUS_GITHUB_APP_WEBHOOK_PROXY_URL=<your Smee.io channel URL>
QUARKUS_GITHUB_APP_WEBHOOK_SECRET=<your webhook secret>
QUARKUS_GITHUB_APP_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\
                  <your private key>                          \
-----END RSA PRIVATE KEY-----
QUARKUS_GITHUB_APP_APP_ID

The numeric app id appearing in the App ID field.

QUARKUS_GITHUB_APP_APP_NAME

The name of your app is the one appearing in the GitHub URL. It is only used to improve usability in dev mode.

QUARKUS_GITHUB_APP_WEBHOOK_PROXY_URL

The URL you obtained when you created your Smee.io channel. If you are using services like ngrok, you don’t need to set it.

QUARKUS_GITHUB_APP_WEBHOOK_SECRET

The webhook secret you created at the previous step.

QUARKUS_GITHUB_APP_PRIVATE_KEY

The content of the private key you generated and downloaded. Open the key file with a text editor as key viewers usually only show fingerprints.

Don’t forget to add backslashes at the end of the lines of your private key (except the last one). In a property file, that is how a multi-line value is considered one value.

Once you have created your .env, you are all set.

Start dev mode and enjoy

If you are familiar with Quarkus, you already know the dev mode which improves productivity a lot. If you are not, the principle is that you start your application once and code: Quarkus will take care of reloading the application when it receives a request.

Just execute the following command to start Quarkus in dev mode:

quarkus dev

If you have a configuration error, it’s probably because you did something wrong with the .env file. Check the instructions above carefully.

Time to code

That’s it! You are done with the setup and you can code your GitHub App. Sky is the limit.

Your newly created GitHub App comes with a small example:

package org.acme;

import java.io.IOException;

import org.kohsuke.github.GHEventPayload;

import io.quarkiverse.githubapp.event.Issue;

class MyGitHubApp {

    void onOpen(@Issue.Opened GHEventPayload.Issue issuePayload) throws IOException {
        issuePayload.getIssue().comment(":wave: Hello from my GitHub App");
    }
}

Every time you create an issue in your GitHub project, a comment will be posted by your GitHub App.

In details:

  • No need for the public modifier, your classes and methods can be package protected.

  • We listen to the @Issue.Opened event i.e. this method will be called for each issue opened.

  • A payload of type GHEventPayload.Issue will be injected in our method automatically. This class is provided by the Hub4j GitHub API.

That’s all folks!

You are done developing your first Quarkus GitHub App.

Obviously, the code from MyGitHubApp is not very useful in real life, but it is a good start and by using this framework:

  • You can listen to all the events currently supported by the Hub4j GitHub API.

  • You have the full power of Quarkus with live coding, easy configuration, dependency injection, native executables and more.

  • You can write automated tests that simulate GitHub events and assert the behavior of your application.

  • You have at your disposal the full ecosystem of Quarkus extensions and the broader Java ecosystem.

Our Replay UI will come handy while developing your GitHub App.

You can learn more about all the events you can listen to in our Developer Reference.

When you are done developing your application, please refer to Push to Production.