= 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:
triage: rules:
For issues, each rule can be triggered by:
title
- if the title matches this regular expression (case insensitively), trigger the rulebody
- if the body (i.e. description) matches this regular expression (case insensitively), trigger the ruletitleBody
- if either the title or the body (i.e. description) match this regular expression (case insensitively), trigger the ruleexpression
- 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.When writing expressions, you can use the matches(String pattern, String string)
function that behaves as follows:
A rule using an expression based on matches()
would look like:
- 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 arraylabels
- 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 rulebody
- if the body (i.e. description) matches this regular expression (case insensitively), trigger the ruletitleBody
- if either the title or the body (i.e. description) match this regular expression (case insensitively), trigger the ruleexpression
- 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 issuenotify
- will create a comment pinging the users listed in the array only if notifyInPullRequest
is truenotifyInPullRequest
should be used as follows:
triage: rules:
=== 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:
projects: rules:
For classic projects, use the following snippet (note the projectsClassic
root):
projectsClassic: rules:
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 URLissues
and pullRequests
are false by defaultstatus
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:
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:
=== 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:
features: [ APPROVE_WORKFLOWS ] workflows: rules:
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 approvalIf 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 issueswaiting-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:
Read & Write
Read & Write
Read only
Read & Write
Read & Write
Read & Write
Events to subscribe to:
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:
== License
This project is licensed under the Apache License Version 2.0.