From ef6b5c62ece9cc310f46e5f21cd210c831114695 Mon Sep 17 00:00:00 2001 From: Marek Skacelik Date: Fri, 9 Jan 2026 11:52:10 +0100 Subject: [PATCH 1/2] Add .env.example for for easier and up-to-date example of an .env file --- .env.example | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 .env.example diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..7786a96 --- /dev/null +++ b/.env.example @@ -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= +QUARKUS_GITHUB_APP_APP_NAME= +QUARKUS_GITHUB_APP_WEBHOOK_PROXY_URL= +QUARKUS_GITHUB_APP_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\ + \ +-----END RSA PRIVATE KEY----- + +# uncomment and set the following variables to enable email notifications +# QUARKUS_MAILER_FROM= +# QUARKUS_MAILER_USERNAME= +# QUARKUS_MAILER_PASSWORD= From 9805cd650f16f1e830b90632a2ca638197364a2e Mon Sep 17 00:00:00 2001 From: Marek Skacelik Date: Fri, 9 Jan 2026 11:52:38 +0100 Subject: [PATCH 2/2] Maitenance of a README.md file --- README.md | 140 +++++++++++++++++++++++++++++------------------------- 1 file changed, 74 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index 5710436..f319944 100644 --- a/README.md +++ b/README.md @@ -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. @@ -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 @@ -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 +``` The content of your `.env` file should be as follows: - ``` -QUARKUS_GITHUB_APP_APP_ID= -QUARKUS_GITHUB_APP_APP_NAME= -QUARKUS_GITHUB_APP_WEBHOOK_PROXY_URL= +QUARKUS_GITHUB_APP_APP_ID= +QUARKUS_GITHUB_APP_APP_NAME= +QUARKUS_GITHUB_APP_WEBHOOK_PROXY_URL= QUARKUS_GITHUB_APP_PRIVATE_KEY=-----BEGIN RSA PRIVATE KEY-----\ - \ + \ -----END RSA PRIVATE KEY----- -QUARKUS_MAILER_FROM= -QUARKUS_MAILER_USERNAME= -QUARKUS_MAILER_PASSWORD= +QUARKUS_MAILER_FROM= +QUARKUS_MAILER_USERNAME= +QUARKUS_MAILER_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. @@ -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: @@ -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. @@ -153,19 +156,21 @@ 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 @@ -173,16 +178,13 @@ Our application currently runs in **2 different modes**: 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 @@ -190,11 +192,11 @@ Fill in the following information. - 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 @@ -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 ` - - You will need to fill required information in prompt - - `oc login --token= --server=` - - 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 +``` +You will need to fill required information in prompt +```sh + oc login --token= --server= +``` +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= --from-file=QUARKUS_GITHUB_APP_PRIVATE_KEY= +```sh +oc create secret generic wildfly-bot \ +--from-literal=QUARKUS_GITHUB_APP_WEBHOOK_SECRET= \ +--from-file=QUARKUS_GITHUB_APP_PRIVATE_KEY= ``` -> **_NOTE:_** If you wish to use mailing option, please append the following properties to the previous command ` --from-literal=QUARKUS_MAILER_FROM= --from-literal=QUARKUS_MAILER_USERNAME= --from-literal=QUARKUS_MAILER_PASSWORD=` +> [!NOTE] +> If you wish to use mailing option, please append the following properties to the previous command +>```sh +>--from-literal=QUARKUS_MAILER_FROM= \ +>--from-literal=QUARKUS_MAILER_USERNAME= \ +>--from-literal=QUARKUS_MAILER_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= + ```sh + ./mvnw clean install \ + -Dquarkus.kubernetes.deploy=true \ + -Dquarkus.openshift.env.vars.quarkus-github-app-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://` 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 ``` 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= \ + --from-file=QUARKUS_GITHUB_APP_PRIVATE_KEY= \ + --from-literal=QUARKUS_MAILER_FROM= \ + --from-literal=QUARKUS_MAILER_USERNAME= \ + --from-literal=QUARKUS_MAILER_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 + ./mvnw clean install \ + -Dquarkus.kubernetes.deploy=true \ + -Dquarkus.openshift.env.vars.quarkus-github-app-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. \ No newline at end of file