= 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.