hibernate/hibernate-github-bot

A bot to handle GitHub events from repositories of the Hibernate organization

Hibernate GitHub Bot

Powered by

This project uses Quarkus, the Supersonic Subatomic Java Framework.

If you want to learn more about Quarkus, visit its website: https://quarkus.io/.

Specifically, most of the GitHub-related features in this bot are powered by the quarkus-github-app extension.

Features

Pull request checking

This bot checks various contribution rules on pull requests submitted to Hibernate projects on GitHub, and notifies the pull request authors of any change they need to work on.

This includes:

• Basic formatting of the pull request: at least two words in the title, ...
• Proper referencing of related JIRA tickets: the ticket key must be mentioned in the PR description.
• Proper formatting of commits: every commit message must start with the key of a JIRA ticket.
• Etc.

Jira link insertion

Optionally, the bot can be configured to automatically add links to JIRA issues in PR descriptions. When this is enabled links to JIRA tickets will be appended at the bottom of the PR body.

Develocity build scan extraction

Optionally, the bot can be configured to automatically create a GitHub check listing Develocity build scans for every commit that has completed checks related to CI (GitHub Actions or Jenkins).

Configuration

Enabling the bot in a new repository

You will need admin rights in the Hibernate organization.

Go to the installed application settings and add your repository under "Repository access".

If you wish to enable the JIRA-related or Develocity-related features as well, create the file .github/hibernate-github-bot.yml in default branch of your repository, with the following content:

---
jira:
  projectKey: "HSEARCH" # Change to whatever your project key is
  insertLinksInPullRequests: true # This is optional and enables automatically adding links to Jira issues found in a PR's commits to its description
  linkIssuesLimit: 3 # This is optional and allows disabling automatic issue links when more than the specified number of keys are found in a PR's commits (defaults to 3)
  # To skip JIRA-related checks (pull request title/body includes JIRA issue keys/links etc.),
  # a list of ignore rules can be configured:
  ignore:
    - user: dependabot[bot]
      titlePattern: ".*\\bmaven\\b.*\\bplugin\\b.*" # will ignore build dependency upgrades i.e. maven plugin version upgrades.
    - user: all-contributors[bot]
      titlePattern: ".*"
  # To skip commits that contain only irrelevant files for JIRA-related checks (commit includes JIRA issue key),
  # a list of ignored files rules can be configured:
  ignoreFiles:
     # Ignore a directory recursively
     - ".github"
     - "ci"
     - "build/config"
     # Ignore a specific file
     - "Jenkinsfile"
     # Ignore all paths matching a given pattern
     - "*/Jenkinsfile"
     - "*.Jenkinsfile"
develocity:
  buildScan:
    # To have the bot create a GitHub check listing Develocity build scans
    # for every commit that has completed checks related to CI (GitHub Actions or Jenkins)
    addCheck: true
    # To group tags in a separate column and/or alter/remove some tags,
    # a list of column rules can be configured:
    tags:
       - column: "OS"
         pattern: "Linux"
       - column: "OS" # Multiple rules can target the same column
         pattern: "Windows.*"
         replacement: "Windows"
       - column: "Java"
         pattern: "jdk-(.*)"
         replacement: "$1"
       - column: "Backend"
         pattern: "elasticsearch-(.*)"
         replacement: "es-$1" # Replacement can refer to capture groups
       - column: "Backend"
         pattern: "(.*-)?opensearch-(.*)"
         replacement: "$1os-$2"
       - column: "Backend"
         pattern: "lucene"
       - column: "DB"
         pattern: "h2|postgres|postgres(ql)?|mysql|mssql|derby|tidb|cockroach(db)?|oracle.*|db2"
         replacement: "$0"
       - pattern: "hibernate.search|elasticsearch|opensearch|main|\\d+.\\d+|PR-\\d+"
         replacement: "" # Just remove these tags

Altering the infrastructure

This should only be needed very rarely, so think twice before trying this.

You will need admin rights in the Hibernate organization.

The infrastructure configuration can be found here.

The GitHub registration of this bot can be found here.

Contributing

Development and testing

Always test your changes locally before pushing them.

You can run the bot locally by:

1. Registering a test instance of the GitHub application on a fake, "playground" repository as explained here.
2. Adding an .env file at the root of the repository, as explained here.
3. Running ./mvnw quarkus:dev.

Deployment

Just push to the main branch.

The main branch is automatically deployed in production through this Jenkins job, configured through the Jenkinsfile at the root of this repository.

Container images are pushed to this quay.io repository.

Maintenance

You can check the current health of the bot like this:

curl https://infra.hibernate.org/bot/github/q/health | jq

hibernate-github-bot's Issues

Develocity build scan retrieval does not handle merge commits

Build scan retrieval just searches for all build scans for a given commit.

When CI performs a merge commit before the build, the build scan is attached to a different commit, so the bot will not find it.

We should try to retrieve info from the GitHub checks instead and try to match the CI build regardless of the commit. The question is: do we have the required info in GitHub checks? :/

For Jenkins:

For GitHub Actions:

Better handling of Dependabot PRs

Dependabot PRs are practical but... you end up with quite some work to get it included in our usual workflow:

• create a JIRA issue
• adjust PR title and description to reference the issue
• adjust the commits to include the issue number
• attach the PR to the issue

I wonder if we could automate at least some of these things. Maybe not for every Dependabot PR coming as we ignore some of them but if we could add a comment like:

@hibernate-bot jira

and get things done, that would be awesome.

Note that Quarkus GitHub App now comes with a new extension to handle commands so this part would be easy. The rest might me more complicated :).

Note: I don't think closing the issue automatically is a good idea as we usually deal with fixed versions.

Forbid fixup/squash commits

Commits whose message starts with fixup! or squash! must be squashed before the PR is merged.

Not strictly necessary since we check that commit messages start with the key of a JIRA ticket, but that could be a nice check regardless.

See https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---fixupltcommitgt

Forbid merge commits

We don't allow those in Hibernate Search, in particular.

See https://github.com/hibernate/hibernate-search/blob/main/CONTRIBUTING.md#commit

Automatically add a comment with links to JIRA tickets mentioned in a PR

List all JIRA tickets:

• Mentioned in commit messages
• Mentioned in the PR description

Related to #1

Check the state of issues on JIRA

We generally should not submit a PR on an issue in closed state.

cc @beikov

Automatic check and PR comment with link to Develocity build scans

Problem

When there are test failures on CI, one has to look at the test results:

• For GitHub Actions, that means going through the logs, which is rather painful due to being raw text, and sometimes insufficient (no stdout/stderr).
• For Jenkins, through BlueOcean it's more manageable, but in Search we had to disable JUnit test result publishing¹ so we don't have anything.

So the best place to look at test results right now is the Develocity build scans, which include detailed test reports along with stacktraces and stdout/stderr.

However, those build scans are not easily accessible from pull requests or build failure notifications.

Solution

We could improve on this situation with our bot:

• In general (for PRs as well as branch builds), we could add a check to every commit on which we detect another GitHub check pointing to a GitHub Actions build or Jenkins build that ended up publishing a build scan.
• For PRs we could go a step further and add a comment with direct links to test failures if there are any.

This should address most problems, with the exception of Jenkins build failure notifications through email: those would still link to the Jenkins build, which doesn't give easy access to relevant build scans. We could try to modify the templates for those emails to point to GitHub checks...?

Implementation notes

For presentation, we could take inspiration from what has been done on Quarkus:

The build reporter from Quarkus could prove a great source of inspiration: https://github.com/quarkusio/build-reporter
It's much more advance than what we intend to do, but that also means what we want to do is probably done there somewhere.

Build scans for a given job can be found easily through custom values, e.g. like this: https://ge.hibernate.org/scans?search.names=CI%20build%20number,CI%20job&search.timeZoneId=Europe%2FParis&search.values=37,hibernate-search%2Fbuild-cache&selection.buildScanB=67qztdpjyl5qm#

Develocity provides a REST API that probably exposes a similar search feature: https://docs.gradle.com/enterprise/api-manual/

Footnotes

1. Hibernate Search has hundreds of thousands of test executions due to tests being split very finely, and the XML test report file ends up being huge (100MB to several GB), slowing down Jenkins significantly and causing disk space issues. ↩

Make tags more readable in Develocity build scan reports

Currently we get reports that look like this:

It's great to have all the information, but it's a bit hard to read at the moment. More specifically, it's a bit hard to quickly find one specific build you're looking for, say "Elasticsearch 7.10".

A few ideas:

• Split tags in multiple columns: OS, JDK, DB, "Backend" (Hibernate Search), . Probably should be made configurable, using patterns to match tags to columns.
• Remove duplicate tags, e.g. we don't need elasticsearch and elasticsearch-7.10
• Add icons next to tags, e.g. Windows/Tux logos, Java logo, DB logo, ... Probably should be made configurable, using patterns to match tags to an icon URL.

Additionally, maybe we should show less information in the job/workflow column, to give more width to other columns. The job/workflow isn't that useful in day to day work. We could:

• Remove that column completely
• Not show the stage name in that column
• Replace the content of that column with an icon (octocat or Jenkins icon), with the text displayed in a tooltip only.
• ...