Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 36 ยท Projects and Practice

Project: A CI Pipeline for a Gradle Build (GitHub Actions)

Set up continuous integration for a Gradle project: GitHub Actions workflow, wrapper validation, caching, test reports, matrix builds, publishing on tags and pipeline planning stand-ins.

A build that only works on your laptop is not finished. In this project you create a continuous integration (CI) pipeline that checks every push and pull request, caches Gradle's work, uploads test reports, and publishes a release when you push a version tag. We use GitHub Actions as the example; the ideas apply to GitLab CI, Jenkins or any other system.

The workflow files are shown read-only because they run on GitHub's servers, not here. Java stand-ins model the decisions a pipeline makes (which jobs run, whether the cache hits) and run on Piston. It helps to know incremental builds and the build cache and versioning and releases.

What a good Gradle pipeline does

flowchart LR
    A[Push or PR] --> B[Checkout]
    B --> C[Set up JDK]
    C --> D[Set up Gradle<br/>cache and wrapper check]
    D --> E["./gradlew build"]
    E --> F[Upload reports]
    E -->|tag v*| G["./gradlew publish"]

Fast feedback on every change; publishing only for release tags.

Principles:

  1. Use the wrapper. CI runs ./gradlew, so it uses the same Gradle as developers.
  2. Pin the JDK (and let toolchains find others).
  3. Cache what is expensive to rebuild: downloaded dependencies and build cache entries.
  4. Fail loudly and keep evidence: upload test and coverage reports even when tests fail.
  5. Keep secrets in the CI secret store, never in the repo.

Step 1: the build workflow

YAML
# .github/workflows/build.yml
name: build

on:
  push:
    branches: [main]
  pull_request:

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        java: [21, 25]
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: ${{ matrix.java }}

      - uses: gradle/actions/setup-gradle@v4
        with:
          cache-read-only: ${{ github.ref != 'refs/heads/main' }}

      - name: Build and test
        run: ./gradlew build --warning-mode=fail

      - name: Upload test reports
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: reports-java-${{ matrix.java }}
          path: |
            **/build/reports/tests/
            **/build/reports/jacoco/

What it does:

  • matrix runs the whole build on two JDKs, a cheap way to prove compatibility.
  • gradle/actions/setup-gradle validates the wrapper jar, restores and saves the Gradle user home cache, and prints a build summary. cache-read-only makes pull requests only read the cache and lets main write it, which avoids cache poisoning from untrusted code.
  • --warning-mode=fail turns deprecation warnings into failures so upgrades never surprise you.
  • if: always() uploads the reports whether the build passed or not.

Step 2: tune Gradle for CI

In gradle.properties (or environment variables) keep CI-friendly defaults:

TEXT
org.gradle.parallel=true
org.gradle.caching=true
org.gradle.jvmargs=-Xmx3g

Notes:

  • GitHub-hosted runners start fresh each time, so the daemon has no benefit across jobs; Gradle starts one per build anyway.
  • A remote build cache (see the caching lesson) lets jobs reuse each other's outputs, and isPush should be true only on CI main builds.
  • Give long builds a timeout-minutes so hung processes do not block the queue.

Step 3: release by tag

YAML
# .github/workflows/release.yml
name: release

on:
  push:
    tags: ['v*']

permissions:
  contents: write

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: 21
      - uses: gradle/actions/setup-gradle@v4

      - name: Work out the version
        run: echo "VERSION=${GITHUB_REF_NAME#v}" >> "$GITHUB_ENV"

      - name: Build and publish
        run: ./gradlew build publish -Pversion="$VERSION"
        env:
          ORG_GRADLE_PROJECT_repoUser: ${{ secrets.REPO_USER }}
          ORG_GRADLE_PROJECT_repoPassword: ${{ secrets.REPO_PASSWORD }}
          SIGNING_KEY: ${{ secrets.SIGNING_KEY }}
          SIGNING_PASSWORD: ${{ secrets.SIGNING_PASSWORD }}

      - name: Create GitHub release
        uses: softprops/action-gh-release@v2
        with:
          files: cli/build/distributions/*.zip

Pushing the tag v1.4.0 runs the job, with VERSION=1.4.0. The Gradle build reads -Pversion, publishes to the repository using credentials passed as ORG_GRADLE_PROJECT_* environment variables (they become Gradle properties), and attaches the distribution zip to a release page. Secrets are created in the repository settings and are not visible in logs.

Step 4: protect the main branch

In the repository settings require the build check to pass before merging, and require review for changes to .github/workflows. These rules matter as much as the YAML, since a pipeline with publish rights is a high-value target.

Stand-in: which jobs run for which event?

Java Stand-in: pipeline planner

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Notice that a push to a feature branch without a pull request starts nothing, the same as the on: section of the workflow above.

Stand-in: how the cache key works

CI caches use a key built from files that describe the dependencies. When the key matches, the cache is restored; otherwise a fresh one is created and saved. The setup-gradle action does this for you, but the idea is simple:

Java Stand-in: cache key hit and miss

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Troubleshooting CI builds

Symptom Likely cause and fix
Works locally, fails on CI different JDK, locale or timezone; pin them in toolchains and test JVM settings
Permission denied: ./gradlew the executable bit is lost; run git update-index --chmod=+x gradlew
Out of memory lower org.gradle.jvmargs or maxParallelForks; runners have limited RAM
Very slow first build no cache yet; the second run should be much faster
Tests flaky in CI only shared ports/files; use random ports and temp directories
Publish step fails with 401 wrong secret name or missing permission

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why should CI always run ./gradlew instead of a system gradle?

    The wrapper guarantees identical Gradle versions for developers and CI.
  2. 2. What does cache-read-only on pull requests prevent?

    Only trusted builds on main should write to the cache; pull requests read it.
  3. 3. How do ORG_GRADLE_PROJECT_repoUser environment variables reach the build?

    Environment variables with the ORG_GRADLE_PROJECT_ prefix are read as Gradle project properties.
  4. 4. Why upload test reports with if: always()?

    Without always(), a failed build step would skip the upload, hiding the evidence.

Summary

  • A Gradle pipeline checks out code, sets up a JDK and Gradle, runs ./gradlew build, and uploads reports.
  • Cache dependencies and build outputs; let only trusted builds on main write caches.
  • Publish from tag-triggered workflows using secrets passed as environment variables.
  • Use a JDK matrix and --warning-mode=fail to catch compatibility problems early.
  • Protect the branch and the workflow files.

Next: Troubleshooting Gradle and practice exercises