Developer Reference
Events
Listening to events
To listen to an event, you need to create a method with one of the event annotations:
class CreateComment {
void onOpen(@Issue.Opened GHEventPayload.Issue issuePayload) throws IOException {
issuePayload.getIssue().comment("Hello from my GitHub App");
}
}A few observations:
-
The method may either be package-protected or public.
-
Most of the GitHub API methods throw
IOExceptions so your methods need to propagate it. We have some nice error handling. -
The payload type needs to be consistent with the event type.
A method may listen to several events as long as they share the same payload type:
class IssueListener {
void onOpenOrEdit(@Issue.Opened @Issue.Edited GHEventPayload.Issue issuePayload) {
// do something
}
}Several methods can listen to the same event types but you cannot control the order of their execution. We use CDI events under the hood and the execution of event observer methods cannot be ordered. If you need ordering for several steps, use a single method to control the execution of these steps. They can be split in smaller private methods if need be.
Event types
Here are all the events currently supported, together with the type of the payload that will be injected.
| GitHub Event Type | Events | Payload |
|---|---|---|
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
If you want to access the low level JSON payload, you can use the raw GitHubEvent, either by substituting it to the API payload:
class TriageIssue {
void triageIssue(@Issue.Opened GitHubEvent gitHubEvent) {
// do something
}
}Or by adding it as an additional parameter:
class TriageIssue {
void triageIssue(@Issue.Opened GHEventPayload.Issue issuePayload, GitHubEvent gitHubEvent) {
// do something
}
}The GitHubEvent exposes the raw JSON either as a string (via GitHubEvent#getPayload()) or as a Vert.x JsonObject (via GitHubEvent#getParsedPayload()),
together with some additional information like the installation id, the event or the action.
If you miss an event type, it is also possible to listen to events by using the @RawEvent annotation.
The @RawEvent annotation allows you to listen to all events/actions, and you may also specify the event and the action you want to listen to.
When using the @RawEvent annotation, the only allowed payload parameter type is GitHubEvent.
class ActOnDeploymentProtectionRule {
void onDeploymentProtectionRule(@RawEvent(event = "deployment_protection_rule", action = "requested") GitHubEvent gitHubEvent) {
// do something
}
}Both event and action are optional and you can listen to all events by using the following code:
class CatchAll {
void catchAll(@RawEvent GitHubEvent gitHubEvent) {
// do something
}
}|
If you miss an event type, please report it by creating an issue. We try to add to contribute to the Hub4j GitHub API all the event types that are useful. When missing an event type, there are two options:
|
Configuration file
For some usage, you might need to include a configuration file that is repository-specific and versioned.
The Quarkus GitHub App extension supports the following features:
-
Automatic injection of config files into your methods.
-
YAML, JSON or text config files.
-
Automatic deserialization of your YAML or JSON config files into Java POJOs using Jackson.
Injecting a configuration file in your method is as simple as:
class TriageIssue {
void triageIssue(@Issue.Opened GHEventPayload.Issue issuePayload,
@ConfigFile("quarkus-bot-java.yml") QuarkusBotConfigFile quarkusBotConfigFile) {
// do something
}
}The configuration file .github/quarkus-bot-java.yml present in the default branch of the repository
for which the event has been triggered
is parsed and deserialized to a QuarkusBotConfigFile instance using Jackson.
If the file does not exist in the repository, quarkusBotConfigFile will be null.
If you want to get the content of the configuration file as is, use a String.
Note that @ConfigFile injection supports using Optional<YourConfigType>.
|
If your repository is private, reading configuration files requires your GitHub App to have the |
|
By default, the config file path is relative to the You can reference a file outside this directory by using an |
Error handler
The Quarkus GitHub App extension provides an error handler that will log errors with as many details as possible.
You can customize the error handler by creating a CDI bean implementing io.quarkiverse.githubapp.error.ErrorHandler:
|
Some errors may be triggered before the payload has been parsed.
In this case, the |
Injecting a GitHub instance
When you need to access the authenticated GitHub instance, for instance to call GitHub#getMyself(),
simply inject it into your method:
class TriageIssue {
void triageIssue(@Issue.Opened GHEventPayload.Issue issuePayload, GitHub gitHub) {
gitHub.getMyself();
}
}The injected GitHub instance is authenticated as an installation.
Injecting a GraphQL client
For some purposes, using the GitHub GraphQL API might get handy (typically to access the Discussions API that is only available in the GraphQL API).
In the same way you can inject an authenticated GitHub instance, you can inject an authenticated DynamicGraphQLClient as follows:
class TriageIssue {
void triageIssue(@Issue.Opened GHEventPayload.Issue issuePayload, DynamicGraphQLClient gitHubGraphQLClient) {
// do something GraphQLy with gitHubGraphQLClient
}
}The injected DynamicGraphQLClient instance is authenticated as an installation.
Configuration Reference
The Quarkus GitHub App extension exposes the following configuration properties:
Configuration property fixed at build time - All other configuration properties are overridable at runtime
Type |
Default |
|
|---|---|---|
The numeric application id provided by GitHub. Optional for tests, but mandatory in production and dev mode. Environment variable: |
string |
|
The GitHub name of the application. Optional, only used for improving the user experience. Environment variable: |
string |
|
Read the configuration files from the source repository in case of a fork. Environment variable: |
boolean |
|
The RSA private key. Optional for tests, but mandatory in production and dev mode. Environment variable: |
||
The webhook secret if defined in the GitHub UI. Environment variable: |
string |
|
The credentials provider name. This is the name of the "keyring" containing the GitHub App secrets. Key names are defined in Environment variable: |
string |
|
The credentials provider bean name. This is a bean name (as in For Vault, the credentials provider bean name is Environment variable: |
string |
|
The Smee.io proxy URL used when testing locally. Environment variable: |
string |
|
The GitHub instance endpoint. Defaults to the public github.com instance. Environment variable: |
string |
|
The REST API endpoint. Defaults to the public github.com instance REST API endpoint. Environment variable: |
string |
|
The GraphQL API endpoint. Defaults to the public github.com instance GraphQL endpoint. Environment variable: |
string |
|
A directory in which the payloads are saved. Environment variable: |
path |
Credentials provider
Quarkus GitHub App supports the usage of a CredentialsProvider to provide some of the configuration properties
that you might not want to appear in a configuration file.
You can find all the information you need about CredentialsProviders in the dedicated guide.
The basic principle is that you provide a CDI bean that will implement the CredentialsProvider and will provide the values for the supported configuration properties.
It can either be provided by the Vault extension if you are using HashiCorp Vault or you can provide you own custom CredentialsProvider implementation.
Using a CredentialsProvider is easy:
-
Make sure you have an implementation of
CredentialsProviderand that it is a@Singletonor@ApplicationScopedCDI bean. -
Set the
quarkus.github-app.credentials-providerto define the name of the credentials provider. See it as the name of a keyring containing your Quarkus GitHub App secrets. -
For the given name, your
CredentialsProvidermay return aMapcontaining entries forgithubAppPrivateKeyand/orgithubAppWebhookSecret. You can use the constants present inio.quarkiverse.githubapp.Credentialsfor practicality.
That is all you need to do:
Quarkus GitHub App will then automatically use the values provided by the CredentialsProvider for the private key and the webhook secret.
