Level Up Your Java CI: A Fully Automated Monorepo Pipeline with GitHub Actions

Dynamic builds, mixed Java versions, and auto-generated badging for 50+ Quarkus examples

Managing a GitHub repository with more than fifty independent Java and Quarkus projects is rarely smooth. My repository, ejq_substack_articles, is exactly that: a flat monorepo where each folder represents a standalone application that accompanies my tutorials on The Main Thread.

Every project includes its own pom.xml, dependencies, Java version, and Maven configuration. The challenge was simple to describe but difficult to solve:

• build only what changed

• use the correct Java version per project without hardcoding anything

• publish status badges for each project

• and update the README automatically

I needed a self-maintaining system. So I built one.

What follows is the complete architecture: a single GitHub Action that detects changes across the repo, builds only what matters, supports mixed Java versions, generates per-project Shields.io badges, and injects an always-up-to-date build table into the README.

This is the “Smart Matrix” workflow.

The Architecture

The workflow is organized into four logical stages:

1. Detect and parse changed projects.

2. Build projects using a runtime-generated matrix that includes the required Java version.

3. Generate per-project build badges.

4. Update the README with a live Markdown table.

All of this happens inside one YAML file.

Intelligent Project Detection

Hardcoding 100+ folders into a workflow is not an option. Instead, a shell script determines exactly which projects changed using git diff for regular pushes, or a full scan when manually triggered via workflow_dispatch.

The key feature is version detection.

The script reads each project’s pom.xml and extracts its <maven.compiler.release> value:

JAVA_VERSION=$(grep -oP ‘(?<=<maven.compiler.release>).*?(?=</maven.compiler.release>)’ “$dir/pom.xml”)

If a project uses an outdated version, a variable, or simply omits the tag, the workflow falls back to a default version.

The output becomes a dynamic JSON matrix:

[
  { “path”: “ai-document-assistant”, “java”: “21” },
  { “path”: “legacy-demo”, “java”: “17” }
]

This matrix describes exactly what to build and how.

Step 2: The Polymorphic Build Matrix

The build stage consumes the JSON and spawns a parallel workflow for each project. Every job sets up its own correct Java version:

- name: Set up JDK ${{ matrix.project.java }}
  uses: actions/setup-java@v4
  with:
    java-version: ${{ matrix.project.java }}

This allows Java 17 and Java 21 projects to run side-by-side with zero special cases. Slow projects no longer block the rest. Failing builds don’t stop others because fail-fast: false.

In practice, it behaves like a small CI cluster composed of dozens of isolated builds.

Step 3: The “Badge Backend”

GitHub provides only one badge per workflow. Monorepos with multiple independent projects need more than that.

To support per-project badges, the workflow builds its own tiny backend:

1. After each Maven build, a JSON file is generated:

{ “schemaVersion”: 1, “label”: “build”, “message”: “passing”, “color”: “green” }

1. The file is uploaded as an artifact.

2. A later job collects all artifacts and pushes them into a dedicated badges orphan branch.

Each JSON file is an endpoint for Shields.io:

https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/myfear/ejq_substack_articles/badges/project-name.json

With this, every example project in the monorepo has a live status badge.

Step 4: Automating the README

The last part of the system keeps the documentation fresh.

The README.md contains invisible HTML markers reserved for auto-injection:

## Build Status

<!-- BUILD_BADGES_START -->

<!-- BUILD_BADGES_END -->

The workflow reads all badge JSON files from the badges branch, builds a Markdown table, and inserts it between those markers using sed.

That means:

• When new projects are added, they appear automatically.

• When projects are deleted, they disappear.

• When builds fail or pass, the table reflects that instantly.

No manual edits. No maintenance tax.

The Complete Workflow Code

Here is the full .github/workflows/monorepo-build.yml workflow, exactly as I use it today, with dynamic detection, mixed Java versions, badge generation, and README injection:

name: Monorepo Build

on:
  push:
    branches: [ “main” ]
  pull_request:
    branches: [ “main” ]
  workflow_dispatch:
    inputs:
      build_all:
        description: ‘Force build all projects?’
        required: true
        default: true
        type: boolean

permissions:
  contents: write # Required to push badges to the orphan branch

jobs:
  # ------------------------------------------------------------------
  # JOB 1: Detect which projects need building and which Java version
  # ------------------------------------------------------------------
  detect-changes:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
      has-changes: ${{ steps.set-matrix.outputs.has-changes }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Identify projects and Java versions
        id: set-matrix
        run: |
          # --- Configuration ---
          DEFAULT_JAVA=”21”
          # Space-separated list of folders to ignore
          EXCLUDES=”video-pipeline”
          # ---------------------

          if [ “${{ github.event_name }}” == “pull_request” ]; then
            BASE_SHA=”origin/${{ github.base_ref }}”
          else
            BASE_SHA=”${{ github.event.before }}”
          fi

          touch matrix_data.json

          # Logic: If manual trigger (and true), find ALL projects. Otherwise, find CHANGED projects.
          if [ “${{ github.event_name }}” == “workflow_dispatch” ] && [ “${{ inputs.build_all }}” == “true” ]; then
             echo “Manual trigger: Scanning all projects...”
             # Find all poms, exclude target folders, get directory names
             FIND_CMD=$(find . -maxdepth 2 -name “pom.xml” -not -path ‘*/target/*’ | xargs dirname | sed ‘s|^\./||’ | sort -u)
          else
             echo “Diffing against $BASE_SHA”
             FIND_CMD=$(git diff --name-only $BASE_SHA HEAD | awk -F/ ‘{print $1}’ | sort -u)
          fi

          # Process the list of directories
          echo “$FIND_CMD” | while read dir; do
            # Only process if it looks like a directory with a pom.xml
            if [[ -d “$dir” ]] && [[ -f “$dir/pom.xml” ]]; then
              
              # Check Exclusions
              if [[ “ $EXCLUDES “ =~ “ $dir “ ]]; then
                echo “Skipping $dir (Explicitly Excluded)” >&2
                continue
              fi
              
              # --- Java Version Detection ---
              # Priority 1: maven.compiler.release
              JAVA_VERSION=$(grep -oP ‘(?<=<maven.compiler.release>).*?(?=</maven.compiler.release>)’ “$dir/pom.xml” | head -1)
              
              # Priority 2: java.version
              if [ -z “$JAVA_VERSION” ]; then
                JAVA_VERSION=$(grep -oP ‘(?<=<java.version>).*?(?=</java.version>)’ “$dir/pom.xml” | head -1)
              fi

              # Priority 3: maven.compiler.source
              if [ -z “$JAVA_VERSION” ]; then
                JAVA_VERSION=$(grep -oP ‘(?<=<maven.compiler.source>).*?(?=</maven.compiler.source>)’ “$dir/pom.xml” | head -1)
              fi

              # Fallback: Default or if variable found
              if [ -z “$JAVA_VERSION” ] || [[ “$JAVA_VERSION” == *’$’* ]]; then
                JAVA_VERSION=$DEFAULT_JAVA
              fi
              
              # Normalize 1.8 -> 8
              if [ “$JAVA_VERSION” == “1.8” ]; then JAVA_VERSION=”8”; fi

              echo “Found: $dir (Java $JAVA_VERSION)” >&2
              echo “{\”path\”: \”$dir\”, \”java\”: \”$JAVA_VERSION\”}” >> matrix_data.json
            fi
          done

          # Output the JSON matrix
          if [ -s matrix_data.json ]; then
            JSON_MATRIX=”[$(paste -sd, matrix_data.json)]”
            echo “has-changes=true” >> $GITHUB_OUTPUT
            echo “matrix=$JSON_MATRIX” >> $GITHUB_OUTPUT
          else
            echo “No buildable projects found.”
            echo “has-changes=false” >> $GITHUB_OUTPUT
            echo “matrix=[]” >> $GITHUB_OUTPUT
          fi

  # ------------------------------------------------------------------
  # JOB 2: Build projects in parallel
  # ------------------------------------------------------------------
  build:
    needs: detect-changes
    if: needs.detect-changes.outputs.has-changes == ‘true’
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        project: ${{ fromJson(needs.detect-changes.outputs.matrix) }}
    
    name: ${{ matrix.project.path }} (JDK ${{ matrix.project.java }})
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up JDK ${{ matrix.project.java }}
        uses: actions/setup-java@v4
        with:
          java-version: ${{ matrix.project.java }}
          distribution: ‘temurin’
          cache: ‘maven’

      # Build, but don’t crash the job immediately on failure (so we can write the Red badge)
      - name: Build with Maven
        id: build
        working-directory: ${{ matrix.project.path }}
        continue-on-error: true
        run: |
          if [ -f “mvnw” ]; then chmod +x mvnw; CMD=”./mvnw”; else CMD=”mvn”; fi
          $CMD package -DskipTests=false

      # Create the JSON file for Shields.io
      - name: Generate Badge JSON
        run: |
          SAFE_NAME=$(echo “${{ matrix.project.path }}” | sed ‘s/\//-/g’)
          
          if [ “${{ steps.build.outcome }}” == “success” ]; then
            COLOR=”green”
            STATUS=”passing”
          else
            COLOR=”red”
            STATUS=”failing”
          fi
          
          echo “{ \”schemaVersion\”: 1, \”label\”: \”build\”, \”message\”: \”$STATUS\”, \”color\”: \”$COLOR\” }” > “$SAFE_NAME.json”

      - name: Upload Badge Artifact
        uses: actions/upload-artifact@v4
        with:
          name: badge-${{ strategy.job-index }}
          path: “*.json”
          retention-days: 1

      # Fail the job if the build actually failed
      - name: Check Build Status
        if: steps.build.outcome != ‘success’
        run: exit 1

  # ------------------------------------------------------------------
  # JOB 3: Aggregate badges and push to orphan branch
  # ------------------------------------------------------------------
  update-badges:
    needs: [detect-changes, build]
    # Only run if there were changes, AND run even if builds failed (provided the workflow wasn’t cancelled manually)
    if: needs.detect-changes.outputs.has-changes == ‘true’ && !cancelled()
    runs-on: ubuntu-latest
    steps:
      - name: Checkout badges branch
        uses: actions/checkout@v4
        with:
          ref: badges
          path: badges-branch

      - name: Download all artifacts
        uses: actions/download-artifact@v4
        with:
          pattern: badge-*
          path: temp-artifacts
          merge-multiple: true

      - name: Move and Commit Badges
        run: |
          # Create directories to ensure find commands don’t crash if empty
          mkdir -p temp-artifacts
          mkdir -p badges-branch
          
          # Only proceed if we actually found JSON files
          if [ -n “$(find temp-artifacts -name ‘*.json’ -print -quit)” ]; then
            echo “Found badge artifacts. Updating...”
            
            # Copy all json files to the badges branch root
            find temp-artifacts -name “*.json” -exec cp {} badges-branch/ \;
            
            cd badges-branch
            git config user.name “github-actions[bot]”
            git config user.email “github-actions[bot]@users.noreply.github.com”
            
            git add .
            if git diff --staged --quiet; then
              echo “No changes in badges.”
            else
              git commit -m “Update build badges [skip ci]”
              git push origin badges
            fi
          else
            echo “No artifacts found (maybe all builds were skipped or failed early).”
          fi

  # ------------------------------------------------------------------
  # JOB 4: Update README with badge table
  # ------------------------------------------------------------------
  update-readme:
    needs: update-badges
    if: always()
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Main
        uses: actions/checkout@v4
        with:
          ref: main # We are editing the main README
          path: main-repo

      - name: Checkout Badges Branch
        uses: actions/checkout@v4
        with:
          ref: badges # We need to see what JSON files exist
          path: badges-repo

      - name: Generate New Badge Table
        run: |
          cd main-repo
          
          # Start the table
          echo “| Project | Status |” > ../badge_table.md
          echo “| :--- | :--- |” >> ../badge_table.md
          
          # Iterate over JSON files in the badges branch to build rows
          # We use the badges branch as the source of truth for what projects exist
          cd ../badges-repo
          for file in *.json; do
            if [ “$file” == “*.json” ]; then continue; fi # Handle empty case
            
            # remove .json extension
            PROJECT_NAME=”${file%.json}”
            
            # Generate the Shield URL
            # Note: We must use the raw.githubusercontent URL for the JSON endpoint
            SHIELD_URL=”https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/${{ github.repository }}/badges/$file”
            
            # Append row to table
            echo “| **$PROJECT_NAME** | ![$PROJECT_NAME]($SHIELD_URL) |” >> ../badge_table.md
          done
          
          cd ../main-repo

      - name: Inject Table into README
        run: |
          cd main-repo
          
          # Define markers
          START_MARKER=”<!-- BUILD_BADGES_START -->”
          END_MARKER=”<!-- BUILD_BADGES_END -->”
          FILE=”README.md”
          
          # 1. Create a temporary file with the content BEFORE the start marker
          sed -n “1,/$START_MARKER/p” “$FILE” > “$FILE.tmp”
          
          # 2. Append the new generated table
          cat ../badge_table.md >> “$FILE.tmp”
          
          # 3. Append the content AFTER the end marker
          # We use sed to find the end marker, then print from there to end of file
          sed -n “/$END_MARKER/,\$p” “$FILE” >> “$FILE.tmp”
          
          # 4. Overwrite original file
          mv “$FILE.tmp” “$FILE”

      - name: Commit and Push README
        run: |
          cd main-repo
          git config user.name “github-actions[bot]”
          git config user.email “github-actions[bot]@users.noreply.github.com”
          
          # Only commit if the README actually changed
          if git diff --quiet README.md; then
            echo “README is up to date.”
          else
            git add README.md
            git commit -m “docs: Auto-update build status badges”
            git push origin main
          fi

Final Thoughts

This workflow ended up removing every point of friction that made monorepos feel heavy. New projects register themselves automatically. Old experiments still build with their own Java version. Every project has its own badge. And the README stays accurate without manual work.

A little automation is all it takes to transform a chaotic monorepo into a predictable, self-updating system.