Quick setup for Maven in GitHub Actions

So you want a predictable Java build that does not waste everyone's morning. Good news, GitHub Actions and Maven get along just fine when you set up a workflow that checks out code, picks a JDK, caches dependencies, runs tests and then packages or uploads artifacts. This short guide gives a practical workflow you can copy and adapt without sacrificing your sanity.

Why caching and a stable JDK matter

CI speed is mostly about not downloading the internet over and over. Cache Maven dependencies to skip repeated jar downloads. Locking the Java runtime avoids those mysterious failures that only show up on Monday mornings when the universe is already tired. Caching plus a consistent JDK yields faster and more reproducible continuous integration runs for Java projects.

What to include in your workflow

• Workflow YAML under .github/workflows so contributors do not play hide and seek
• actions/checkout to get your source
• actions/setup-java to set a specific Java version and optionally enable built in caching
• A cache step for ~/.m2/repository if you prefer explicit control
• Maven goals that match your stage like test or package
• Optional upload of build artifacts or test reports for later inspection

Example workflow using setup java cache

This example is compact and uses setup-java's maven cache option for convenience. Tweak java-version and goals to match your project.

name: CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up JDK
        uses: actions/setup-java@v3
        with:
          distribution: 'temurin'
          java-version: '17'
          cache: 'maven'
          cache-dependency-path: '**/pom.xml'
      - name: Build with Maven
        run: mvn -B -V test package
      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: build-artifacts
          path: target/*.jar

Alternative explicit cache step

If you like full control or have a multi module repo you can use actions/cache to store the local Maven repository. Use a key that includes runner os, java version and a hash of your pom files to prevent stale dependencies.

      - uses: actions/cache@v3
        with:
          path: ~/.m2/repository
          key: $-maven-$
          restore-keys: |
            $-maven-

Practical tips that actually help

• Use mvn -B for non interactive runs and consistent logs
• Fail fast on tests to keep broken code from wandering into main branches
• Include the OS and java version in your cache key to avoid weird breakage and mismatched artifacts
• Upload test reports and jars so debugging is easier than yelling at logs
• If your CI is slow profile the build to find the real offender before blaming Maven

Troubleshooting without tears

If dependencies are not restored check the key and the paths. Make sure your pom files are included in the hash when you base the cache key on them. If tests pass locally but fail in CI check the Java version and system locale. Small differences can produce dramatic Monday level surprises.

Follow these steps and your GitHub Actions workflow will give faster, clearer CI feedback for Java projects. You will also earn the quiet respect of anyone who has waited for a build while clutching a cold cup of coffee.