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 |
|---|---|---|
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
|
Miss an event type? It is easy to add support for a new one:
|
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 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 |
