Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/quarkusio/quarkus-github-bot

A Quarkus-powered GitHub App to simplify issues and pull requests management in the Quarkus project.
https://github.com/quarkusio/quarkus-github-bot

github-app quarkus

Last synced: about 1 month ago
JSON representation

A Quarkus-powered GitHub App to simplify issues and pull requests management in the Quarkus project.

Awesome Lists containing this project

README 

        
= Quarkus GitHub Bot



> A Quarkus-powered GitHub App to simplify issues and pull requests management in the Quarkus project.



++++



++++



== Introduction



This GitHub App is based on the https://github.com/quarkiverse/quarkus-github-app[Quarkus GitHub App framework].



It can be run as a native executable.



== Current Actions



=== Check pull request editorial rules



This action checks that the title of a pull request respects some editorial rules to make Release Notes more consistent.



=== Check pull request contribution rules



This action checks that pull requests do not contain any merge or fixup commits.



=== Triage issues



Based on the `.github/quarkus-github-bot.yml` file, this rule affects labels to issues and also pings the appropriate people.



Syntax of the `.github/quarkus-github-bot.yml` file is as follows:



[source, yaml]

----

triage:

  rules:

    - labels: [area/amazon-lambda]

      title: "lambda"

      notify: [patriot1burke, matejvasek]

      files:

        - extensions/amazon-lambda

        - integration-tests/amazon-lambda

    - labels: [area/persistence]

      title: "db2"

      notify: [aguibert]

      files:

        - extensions/reactive-db2-client/

        - extensions/jdbc/jdbc-db2/

----



For issues, each rule can be triggered by:



* `title` - if the title matches this regular expression (case insensitively), trigger the rule

* `body` - if the body (i.e. description) matches this regular expression (case insensitively), trigger the rule

* `titleBody` - if either the title or the body (i.e. description) match this regular expression (case insensitively), trigger the rule

* `expression` - allows to write a Jakarta EL expression testing `title`, `body` or `titleBody`. Be careful when writing expressions, better ping `@gsmet` in the pull request when creating/updating an expression.



[TIP]

====

When writing expressions, you can use the `matches(String pattern, String string)` function that behaves as follows:



[source,java]

----

public static boolean matches(String pattern, String string) {

    return Pattern.compile(".*" + pattern + ".*", Pattern.DOTALL | Pattern.CASE_INSENSITIVE).matcher(string)

            .matches();

}

----



A rule using an expression based on `matches()` would look like:



[source,yaml]

----

    - labels: [area/hibernate-orm, area/persistence]

      expression: |

              matches("hibernate", title)

              && !matches("hibernate.validator", title)

              && !matches("hibernate.search", title)

              && !matches("hibernate.reactive", title)

      notify: [gsmet, Sanne, yrodiere]

----

====



If the rule is triggered, the following actions will be executed:



* `notify` - will create a comment pinging the users listed in the array

* `labels` - will add the labels to the issue



=== Triage pull requests



The pull requests triage action uses the same configuration file as the issues triage action.



There are a few differences though as it doesn't behave in the exact same way.



For pull requests, each rule can be triggered by:



* `files` - if any file in the commits of the pull requests match, trigger the rule. This is not a regexp (it uses `startsWith`) but glob type expression are supported too `extensions/test/**`.



If no rule is triggered based on files, or if rules are triggered but they all specify `allowSecondPass: true`,

a second pass will be executed; in that second pass, rules can be triggered by:



* `title` - if the title matches this regular expression (case insensitively), trigger the rule

* `body` - if the body (i.e. description) matches this regular expression (case insensitively), trigger the rule

* `titleBody` - if either the title or the body (i.e. description) match this regular expression (case insensitively), trigger the rule

* `expression` - allows to write a Jakarta EL expression testing `title`, `body` or `titleBody`. Be careful when writing expressions, better ping `@gsmet` in the pull request when creating/updating an expression.



If the rule is triggered, the following action will be executed:



* `labels` - will add the labels to the issue

* `notify` - will create a comment pinging the users listed in the array **only if `notifyInPullRequest` is true**



`notifyInPullRequest` should be used as follows:



[source, yaml]

----

triage:

  rules:

    - labels: [area/amazon-lambda]

      title: "lambda"

      notify: [patriot1burke, matejvasek]

      notifyInPullRequest: true

      files:

        - extensions/amazon-lambda

        - integration-tests/amazon-lambda

----



=== Push issues/pull requests to a project



For new projects, you can push issues which gets the label `area/hibernate-validator` with the following configuration:



[source, yaml]

----

projects:

  rules:

    - labels: [area/hibernate-validator]

      project: 1

      issues: true

      pullRequests: false

      status: Todo

----



For classic projects, use the following snippet (note the `projectsClassic` root):



[source, yaml]

----

projectsClassic:

  rules:

    - labels: [area/hibernate-validator]

      project: 1

      issues: true

      pullRequests: false

      status: Todo

----



* `labels` defines the list of labels for which the rule will be applied. Any time one of the labels is added to an issue/pull request, it will be added to the project (if not already in it).

* `project` is the id of the project as seen in the URL

* `issues` and `pullRequests` are false by default

* `status` defines the name of the column in which the item will be added e.g. `Todo`, `Backlog`. It is mandatory.



=== Triage discussions



The rules applied for issues and pull requests are also applied to discussions, as long as the category is monitored.

Typically, in the case of the Quarkus main repository, we are only monitoring the `Q&A` category.



Monitoring a category is enabled with:



[source, yaml]

----

triage:

  discussions:

    monitoredCategories: [33575230]

----



The number is the numeric id as present in the JSON event payload.



=== Notify QE



When the `triage/qe?` label is added to an issue or a pull request, the QE team is pinged.



The configuration is done in the `quarkus-github-bot.yml` config file:



[source,yaml]

----

triage:

  qe:

    notify: [rsvoboda, mjurc]

----



=== Affect milestones



When a pull request is merged, if it targets the `main` branch, it affects the milestone ending with ` - main` to the pull request and the issues resolved by the pull request (e.g. `Fixes #1234`).



It only affects the milestone is no milestone has been affected prior to the merge.

If the milestone cannot be affected, we add a comment to the pull request indicating the items for which we haven't affected the milestone.



=== Workflow run report



When a workflow run associated to a pull request is completed, a report is generated and added as a comment in the pull request:



> image::documentation/screenshots/workflow-run-report.png[]



=== Approve workflow runs



This rule applies more fine-grained protections to workflow runs

than is provided by the basic GitHub settings. If a repository

is https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository[set up to only allow workflow runs from committers],

the bot can automatically approve some workflows which meet a set of rules.



Syntax of the `.github/quarkus-github-bot.yml` file is as follows:



[source, yaml]

----

features: [ APPROVE_WORKFLOWS ]

workflows:

      rules:

        - allow:

            files:

             - ./src

             - ./doc*

             - "**/README.md"

            users:

              minContributions: 5

          unless:

            files:

             - ./.github

             - "**/pom.xml"

----



Workflows will be allowed if they meet one of the rules in the `allow` section,

unless one of the rules in the `unless` section is triggered.



In the example above, any file called `README.md` would be allowed, except for `./github/README.md`.

Users who had made at least 5 commits to the repository would be allowed to make any changes,

except to a `pom.xml` or any files in `.github`. Other users could make changes to `./src` or directories whose name started with `./doc`.



If the rule is triggered, the following actions will be executed:



* `approve` - will approve the workflow which needs approval



If the workflow is not approved, it will be left untouched, for a human approver to look at.



=== Mark closed pull requests as invalid



If a pull request is closed without being merged, we automatically add the `triage/invalid` label to the pull request.



=== Automatically remove outdated labels



The bot will automatically remove these labels when they are outdated:



* `triage/needs-triage` from closed issues

* `waiting-for-ci` from closed pull requests



=== Enforce color for specific labels



The bot enforces a specific color for any label created that starts with `area/` so that all these labels are consistent.



== Contributing



To participate to the development of this GitHub App, create a playground project in your own org and

follow the steps outlined in https://quarkiverse.github.io/quarkiverse-docs/quarkus-github-app/dev/index.html[the Quarkus GitHub App documentation].



GitHub permissions required:



* Actions - `Read & Write`

* Checks - `Read & Write`

* Contents - `Read only`

* Discussions - `Read & Write`

* Issues - `Read & Write`

* Pull Requests - `Read & Write`



Events to subscribe to:



* Discussions

* Issues

* Label

* Pull Request

* Workflow run

* Workflow dispatch



By default, in dev mode, the Bot runs in dry-run so it's logging its actions but do not perform them.

You can override this behavior by adding `_DEV_QUARKUS_GITHUB_BOT_DRY_RUN=false` to your `.env` file.



== Deployment



Once logged in to the OpenShift cluster (using `oc login...`), just run:



[source, bash]

----

$ ./deploy-to-openshift.sh

----



== License



This project is licensed under the Apache License Version 2.0.