Skip to content

Repository maintenance #236

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
xjusko merged 2 commits into from
Jan 16, 2026
Merged

Repository maintenance #236

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ef6b5c6
Add .env.example for for easier and up-to-date example of an .env file
mskacelik Jan 9, 2026
9805cd6
Maitenance of a README.md file
mskacelik Jan 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions .env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Since the ".env" file is gitignored, you can use the ".env.example" file to
# build a new ".env" file when you clone the repo. Keep this file up-to-date
# when you add new variables to `.env`.

# This file will be committed to version control, so make sure not to have any
# secrets in it. If you are cloning this repo, create a copy of this file named
# ".env" and populate it with your secrets.

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

# uncomment and set the following variables to enable email notifications
# QUARKUS_MAILER_FROM=<email-address>
# QUARKUS_MAILER_USERNAME=<email-address>
# QUARKUS_MAILER_PASSWORD=<email-password>
140 changes: 74 additions & 66 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,9 @@
# wildfly-github-bot
wildfly-github-bot helps you to keep your pull requests in the correct format.
# WildFly GitHub Bot
WildFly GitHub Bot helps you to keep your pull requests in the correct format.

This project is built with usage of Quarkus GitHub App: https://quarkiverse.github.io/quarkiverse-docs/quarkus-github-app/dev/index.html

## Functionality

* Expected format for Pull Requests - Defined in config file:
* Title - Regex, we expect to match for title of the Pull Request.
* Commit - Regex, we expect to match for at least one commit in the Pull Request.
Expand All @@ -24,16 +23,13 @@ This project is built with usage of Quarkus GitHub App: https://quarkiverse.gith
* Tracking changes to config file, if it's kept valid
* On startup, validates config file, creates `rebase-this` and `fix-me` labels if necessary. Notifies `emails` in case of problems encountered.


## Development
### Step 1 - Register the application

After forking the project we need to register wildfly-github-bot on GitHub for your account. Go to [GitHub Apps](https://github.com/settings/apps) and click on `New GitHub Apps`

Also, you can access this page by clicking on your profile picture on gitHub and go to `Settings > Developer Settings > GitHub Apps > New GitHub App`.

Fields to fill in:

1. GitHub App name - should be unique
2. Homepage URL - the link to the forked project
3. Webhook URL
Expand All @@ -54,25 +50,28 @@ Fields to fill in:
- You will be asked to download the key, keep it around, we will need it for the next step.

### Step 2 - Set up the app

As the configuration is environment-specific, and you probably don’t want to commit it in your repository, the best is to create in the root a `.env` file.
As the configuration is environment-specific, and you probably don’t want to commit it in your repository, the best is to create in the root an environment file (`.env`) file.
If you haven't already, create your own `.env` file by copying the provided up-to-date `.env.example` file:
```sh
cp .env.example .env
```
Comment on lines +55 to +57
Copy link
Collaborator

@xjusko xjusko Jan 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add a short explanatory sentence before the command


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_APP_ID=<your-GitHub-app-id>
QUARKUS_GITHUB_APP_APP_NAME=<name-of-your-app>
QUARKUS_GITHUB_APP_WEBHOOK_PROXY_URL=<your-Smee.io-channel-URL>
QUARKUS_GITHUB_APP_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\
<your private key> \
<your-private-key> \
-----END RSA PRIVATE KEY-----

QUARKUS_MAILER_FROM=<email address>
QUARKUS_MAILER_USERNAME=<email address>
QUARKUS_MAILER_PASSWORD=<email password>
QUARKUS_MAILER_FROM=<email-address>
QUARKUS_MAILER_USERNAME=<email-address>
QUARKUS_MAILER_PASSWORD=<email-password>
```

> **_NOTE:_** If you do not wish to send emails, do not fill in the `QUARKUS_MAILER_*` variables please.
> [!NOTE]
> If you do not wish to send emails, do not fill in the `QUARKUS_MAILER_*` variables please.

**QUARKUS_GITHUB_APP_APP_ID**
The numeric app id appears in the App ID field.
Expand All @@ -93,15 +92,18 @@ email address displayed in the message
email address sending the email

**QUARKUS_MAILER_PASSWORD**
password to the email address corresponding to QUARKUS_MAILER_USERNAME. **Note** You probably want to generate it using _Gmail_ > _Settings_ > _Security_ > _2-Step Verification_ > _App passwords_
password to the email address corresponding to QUARKUS_MAILER_USERNAME.
> [!NOTE]
> You probably want to generate it using _Gmail_ > _Settings_ > _Security_ > _2-Step Verification_ > _App passwords_

***Default email service***
is Gmail. To change this behavior or to override predefined parameters in _applications.properties_ file please refer to [Mailer Extension Documentation](https://quarkus.io/guides/mailer-reference#popular)
### Step 3 - Set up the app
is Gmail. To change this behavior or to override predefined parameters in `application.properties` file please refer to [Mailer Extension Documentation](https://quarkus.io/guides/mailer-reference#popular)

### Step 3 - Set up the app
1. Create a new repo or use an already created one in which you want to track PRs.
2. Go to the settings of your GitHub App and go to `Install App > Install > Only select repositories > Select the one you need > Install`
3. In your repo in the main branch create a folder `.github` and a file `wildfly-bot.yml` with YAML code in it:

#### Structure of the `wildfly-bot.yml` file:
```yaml
wildfly:
Expand Down Expand Up @@ -130,7 +132,8 @@ wildfly:
4. `message` - The text of an error message in the respective check.
5. `emails` - List of emails to receive notifications.

> **_NOTE:_** `title` and `commit` are enabled by default. More [here](wildfly-bot-config-example.yml).
> [!IMPORTANT]
> `title` and `commit` are enabled by default. More [here](wildfly-bot-config-example.yml).

Also, there is a possibility to select checks that you need. Just leave in the `wildfly-bot.yml` file the checks you need.

Expand All @@ -153,48 +156,47 @@ wildfly:
```

### Run the application in dev mode

Run your application in dev mode that enables live coding using:
```shell script
```sh
./mvnw compile quarkus:dev
```

> **_NOTE:_** Dev UI available in dev mode only at http://localhost:8080/q/dev/.
> > **_NOTE:_** In Dev mode sending emails is mocked. To disable this, set the following property `quarkus.mailer.mock=false`
> [!NOTE]
> Dev UI available in dev mode only at http://localhost:8080/q/dev/.
> In Dev mode sending emails is mocked. To disable this, set the following property `quarkus.mailer.mock=false`.

### Dry run
By default, in `dev` mode, **DRY RUN** mode is enabled. This means the bot will only log the actions it would take without actually performing them. You can disable **DRY RUN** by setting the `wildfly-bot.dry-run=false` property in the `application.properties` file - or by compiling the executable with `-Dwildfly-bot.dry-run=false` flag.

Try to create a PR and update it a few times. The format check sends commit statuses that you will see in the PR.

### Testing

Our application currently runs in **2 different modes**:
* **SSE** - Events received by GitHub
* **Event Polling** - Retrieve manually events in scheduled intervals

For such use case, we have profile aware tests, where by default we test **SSE** events. To run **Event Polling** you should set `quarkus.test.profile=polling`.

## Deployment on OpenShift

### Requirements

- JDK 17+ with **JAVA_HOME** configured appropriately
- OpenShift (e.g., https://developers.redhat.com/developer-sandbox)
- [OpenShift CLI](https://docs.openshift.com/container-platform/4.7/cli_reference/openshift_cli/getting-started-cli.html)
- Apache Maven 3.8.6

### Step 1 - Register new GitHub App

Fill in the following information.
1. Application name
2. Homepage URL
3. Webhook URL
- put any placeholder URL here, as you will get the URL after the deployment
4. Webhook secret
- You can generate a secret by using GitHub's recommended method:
```
```shell script
ruby -rsecurerandom -e 'puts SecureRandom.hex(20)'
```
- or use `pwgen`:
```
```shell script
pwgen -N 1 -s 40
```
- **save it** as you will need it later
Expand All @@ -207,73 +209,79 @@ Fill in the following information.
- `Pull request review comment`

### Step 2 - Generate a private key

- Scroll down to generate a private key
- Download it as you will need it later

### Step 3 - Install the application in the desired repository

- You can find this in the "Install App" tab of your GitHub application

### Step 4 - Log into the OpenShift cluster
- `oc login -u <username>`
- You will need to fill required information in prompt
- `oc login --token=<token> --server=<serverUrl>`
- You can request the token via the `Copy Login Command` link in the OpenShift web console.
You can log into with a command
```shell script
oc login -u <username>
```
You will need to fill required information in prompt
```sh
oc login --token=<token> --server=<server-url>
```
You can request the token via the `Copy Login Command` link in the OpenShift web console.

### Step 5 - Create OpenShift secret with webhook secret and private key

```shell script
oc create secret generic wildfly-bot --from-literal=QUARKUS_GITHUB_APP_WEBHOOK_SECRET=<your-webhook-secret> --from-file=QUARKUS_GITHUB_APP_PRIVATE_KEY=<path-to-your-private-key>
```sh
Copy link
Collaborator

@xjusko xjusko Jan 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you need to add backslashes at the end of the line so the copy-paste works properly.
oc create secret generic wildfly-bot
--from-literal=QUARKUS_GITHUB_APP_WEBHOOK_SECRET=
--from-file=QUARKUS_GITHUB_APP_PRIVATE_KEY=

Copy link
Collaborator Author

@mskacelik mskacelik Jan 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

true

oc create secret generic wildfly-bot \
--from-literal=QUARKUS_GITHUB_APP_WEBHOOK_SECRET=<your-webhook-secret> \
--from-file=QUARKUS_GITHUB_APP_PRIVATE_KEY=<path-to-your-private-key>
```


> **_NOTE:_** If you wish to use mailing option, please append the following properties to the previous command ` --from-literal=QUARKUS_MAILER_FROM=<email address> --from-literal=QUARKUS_MAILER_USERNAME=<email address> --from-literal=QUARKUS_MAILER_PASSWORD=<email password>`
> [!NOTE]
> If you wish to use mailing option, please append the following properties to the previous command
>```sh
Copy link
Collaborator

@xjusko xjusko Jan 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same thing with backslashes here

>--from-literal=QUARKUS_MAILER_FROM=<email-address> \
>--from-literal=QUARKUS_MAILER_USERNAME=<email-address> \
>--from-literal=QUARKUS_MAILER_PASSWORD=<email-password>
>```

### Step 6 - Deploy the application

- Go to the application home directory and run:
```
./mvnw clean install -Dquarkus.kubernetes.deploy=true -Dquarkus.openshift.env.vars.quarkus-github-app-app-id=<your-github-app-id>
```sh
Copy link
Collaborator

@xjusko xjusko Jan 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same thing with backslashes here

./mvnw clean install \
-Dquarkus.kubernetes.deploy=true \
-Dquarkus.openshift.env.vars.quarkus-github-app-app-id=<your-GitHub-app-id>
```
- You can also put the config properties to the `application.properties`

### Step 7 - Edit the WebHook URL in your GitHub application

1. Get the list of exposed routes:

`oc get routes`
```sh
oc get routes
```

2. Edit the WebHook URL using the retrieved `HOST/PORT` value:

`http://<HOST/PORT>`

And that's it. Again, try to create a PR to verify the format of the PR.
## Production deployment

## Production deployment
We run WildFly GitHub Bot on Openshift in production. To save resources we also deploy it as native executable.

1. Log in into Openshift
```
```sh
oc login -u <username>
```
2. Then create the relevant secret:
```
oc create secret generic wildfly-bot
--from-literal=QUARKUS_GITHUB_APP_WEBHOOK_SECRET={TBD}
--from-file=QUARKUS_GITHUB_APP_PRIVATE_KEY={TBD}
--from-literal=QUARKUS_MAILER_FROM={TBD}
--from-literal=QUARKUS_MAILER_USERNAME={TBD}
--from-literal=QUARKUS_MAILER_PASSWORD={TBD}
```sh
oc create secret generic wildfly-bot \
--from-literal=QUARKUS_GITHUB_APP_WEBHOOK_SECRET=<your-webhook-secret> \
--from-file=QUARKUS_GITHUB_APP_PRIVATE_KEY=<path-to-your-private-key> \
--from-literal=QUARKUS_MAILER_FROM=<email-address> \
--from-literal=QUARKUS_MAILER_USERNAME=<email-address> \
--from-literal=QUARKUS_MAILER_PASSWORD=<email-password>
```
3. Deploy the bot:
```
./mvnw clean install
-Dquarkus.kubernetes.deploy=true
-Dquarkus.openshift.env.vars.quarkus-github-app-app-id={TBD}
-Dquarkus.native.container-build=true
```sh
Copy link
Collaborator

@xjusko xjusko Jan 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same thing with backslashes.

./mvnw clean install \
-Dquarkus.kubernetes.deploy=true \
-Dquarkus.openshift.env.vars.quarkus-github-app-app-id=<your-GitHub-app-id> \
-Dquarkus.native.container-build=true \
-Dnative
```

### Dry run
By default, in `dev` mode, **DRY RUN** mode is enabled. This means the bot will only log the actions it would take without actually performing them. You can enable **DRY RUN** by setting the `wildfly-bot.dry-run=true` property in the `application.properties` file.
Loading