build-pr.yml

# This is a variation of the basic use-case, which generates both the 
# coverage and branches coverage badges storing them in the default directory,
# .github/badges. The workflow runs on pushes, pull requests, and can
# be run manually (the workflow_dispatch event). The difference from the basic
# use-case is that instead of committing and pushing the badges, this workflow
# generates a pull request with the badges. This is probably the simplest
# way to deal with a protected branch that has required checks or required 
# reviews. However, it does introduce the need for a human to merge the
# pull request containing the badge update. 
#
# It performs the following steps:
# 1) It starts with a checkout.
# 2) Sets up Java for JDK 11 (change details if you
#    use a different Java version).
# 3) Builds the project with mvn package. Note that package
#    includes the test phase. If you just want to build and test,
#    then change package to test. Jacoco is configured to run
#    during the test phase, so either one is sufficient for the
#    purposes of this example.
# 4) Runs the jacoco-badge-generator to generate both the 
#    coverage and branches coverage badges to the default directory
#    which is .github/badges. That directory will be created if it
#    doesn't exist.
# 5) Logs the coverage and branches coverage to the workflow's output
#    for inspection in the event the workflow fails prior to committing
#    badges.
# 6) Generates a Pull Request (using the peter-evans/create-pull-request
#    GitHub action). Notice that this step is conditional and
#    only runs if the workflow was triggered by a push or workflow_dispatch, 
#    and not by a pull request. Why?  Well, for one, the workflow will be 
#    in a detached head state if triggered by a pull request.  Additionally, 
#    you may or may not choose to merge a pull request, and should only really 
#    update the coverage badges if you choose to accept the changes by merging 
#    the pull request, at which point this will be handled by the push that 
#    occurs with the merge. 
# 7) The last step uploads the JaCoCo reports as a workflow artifact.
#    In this way, if you want to inspect the details, you can do so
#    via the actions tab of your repository. That step essentially attaches
#    a zip of the JaCoCo report directory to the workflow run. You can download
#    it manually from the page for the workflow run.  GitHub automatically
#    deletes these after 90 days.
#
# A Few Notes:
# If your main branch is protected and includes either required checks or
# required reviews, then the push step will fail (this is true even if you 
# use one of the available actions for pushing). To get around this, one 
# option is to see GitHub's documentation on using a personal access token (PAT)
# with the actions/checkout step. However, some of the other workflows in this
# directory provide alternatives that do not require additional access.

name: build (PR version)

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
  workflow_dispatch:

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - name: Checkout
      uses: actions/checkout@v4

    - name: Set up JDK 11
      uses: actions/setup-java@v4
      with:
        distribution: 'adopt'
        java-version: '11'

    - name: Build with Maven
      run: mvn -B package

    - name: Generate Jacoco Badge
      id: jacoco
      uses: cicirello/jacoco-badge-generator@v2
      with:
        generate-branches-badge: true

    - name: Log coverage percentage
      run: |
        echo "coverage = ${{ steps.jacoco.outputs.coverage }}"
        echo "branches = ${{ steps.jacoco.outputs.branches }}"

    - name: Create pull request
      if: ${{ github.event_name != 'pull_request' }}
      uses: peter-evans/create-pull-request@v7
      with:
        title: "Autogenerated Jacoco Coverage Badge"
        commit-message: "Autogenerated Jacoco Coverage Badge"
        delete-branch: true

    - name: Upload Jacoco coverage report
      uses: actions/upload-artifact@v4
      with:
        name: jacoco-report
        path: target/site/jacoco/