chore: merge dev into main

.github/workflows/_ci-check.yml

@@ -80,6 +80,26 @@ on:
         required: false
         type: string
         default: '8.4'
+      setup-java:
+        description: >-
+          Install a JDK before the checks run, with Gradle's wrapper and
+          dependency caches restored. For a repo whose gate chains a Gradle build
+          — the runner image's preinstalled JDK is neither pinned nor the one the
+          build's toolchain asks for. Same input as `_ci-e2e.yml` and
+          `_ci-lighthouse.yml` carry.
+        required: false
+        type: boolean
+        default: false
+      java-version:
+        description: Java version when `setup-java` is set.
+        required: false
+        type: string
+        default: '25'
+      java-distribution:
+        description: JDK distribution when `setup-java` is set, as `actions/setup-java` names it.
+        required: false
+        type: string
+        default: temurin
       install:
         description: Dependency install command.
         required: false
@@ -136,6 +156,23 @@ jobs:
         if: inputs.setup-php
         run: composer install --no-interaction --prefer-dist --optimize-autoloader
 
+      # `cache: gradle` RATHER THAN `gradle/actions/setup-gradle`: first-party, no
+      # extra SHA pin, and the same idiom as `cache: pnpm` above. It keys on the
+      # build files and the wrapper properties, restores the wrapper distribution
+      # and dependency caches here and saves them in its post step — so a re-run
+      # of the same pull request downloads neither. This gate runs on
+      # `pull_request` alone, so nothing here warms a DIFFERENT pull request.
+      #
+      # TOOLCHAINS ARE NOT CACHED, deliberately. With the JDK the toolchain asks
+      # for installed here, Gradle resolves it locally and provisions nothing.
+      - name: Set up Java
+        if: inputs.setup-java
+        uses: actions/setup-java@v6
+        with:
+          distribution: ${{ inputs.java-distribution }}
+          java-version: ${{ inputs.java-version }}
+          cache: gradle
+
       - name: Install dependencies
         env:
           INSTALL_COMMAND: ${{ inputs.install }}

.github/workflows/_ci-e2e.yml

@@ -47,6 +47,24 @@ on:
         required: false
         type: string
         default: '8.4'
+      setup-java:
+        description: >-
+          Install a JDK first, with Gradle's wrapper and dependency caches
+          restored — for a suite whose build or backend runs through Gradle.
+          Same input as `_ci-check.yml` carries.
+        required: false
+        type: boolean
+        default: false
+      java-version:
+        description: Java version when `setup-java` is set.
+        required: false
+        type: string
+        default: '25'
+      java-distribution:
+        description: JDK distribution when `setup-java` is set, as `actions/setup-java` names it.
+        required: false
+        type: string
+        default: temurin
       node-version:
         description: Node version.
         required: false
@@ -98,6 +116,17 @@ jobs:
         if: inputs.setup-php
         run: composer install --no-interaction --prefer-dist --optimize-autoloader
 
+      # Same step as `_ci-check.yml`, and the rationale lives there: first-party
+      # `cache: gradle` restores the wrapper and dependencies for a re-run of the
+      # same pull request; toolchains are not cached.
+      - name: Set up Java
+        if: inputs.setup-java
+        uses: actions/setup-java@v6
+        with:
+          distribution: ${{ inputs.java-distribution }}
+          java-version: ${{ inputs.java-version }}
+          cache: gradle
+
       - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
 
       - uses: actions/setup-node@v7

.github/workflows/_ci-lighthouse.yml

@@ -81,6 +81,24 @@ on:
         required: false
         type: string
         default: '8.4'
+      setup-java:
+        description: >-
+          Install a JDK first, with Gradle's wrapper and dependency caches
+          restored — for an app whose build runs through Gradle. Same input as
+          `_ci-check.yml` carries.
+        required: false
+        type: boolean
+        default: false
+      java-version:
+        description: Java version when `setup-java` is set.
+        required: false
+        type: string
+        default: '25'
+      java-distribution:
+        description: JDK distribution when `setup-java` is set, as `actions/setup-java` names it.
+        required: false
+        type: string
+        default: temurin
       node-version:
         description: Node version.
         required: false
@@ -201,6 +219,17 @@ jobs:
         if: inputs.setup-php
         run: composer install --no-interaction --prefer-dist --optimize-autoloader
 
+      # Same step as `_ci-check.yml`, and the rationale lives there: first-party
+      # `cache: gradle` restores the wrapper and dependencies for a re-run of the
+      # same pull request; toolchains are not cached.
+      - name: Set up Java
+        if: inputs.setup-java
+        uses: actions/setup-java@v6
+        with:
+          distribution: ${{ inputs.java-distribution }}
+          java-version: ${{ inputs.java-version }}
+          cache: gradle
+
       - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
 
       - uses: actions/setup-node@v7

README.md

@@ -271,6 +271,15 @@ A repo whose checks download remote sources — a Nuxt Content site reading `rep
 
 The command appends `cacheable`, `key` and a multi-line `paths` to `$GITHUB_OUTPUT`; the body restores and saves those paths with `actions/cache` under that exact key, and skips both unless `cacheable` is `true`. Left empty, which is the default, nothing runs. The gate runs on pull requests only, so a hit across pull requests comes from the default branch's own writer running the identical command.
 
+A repo whose gate also chains a Gradle build asks for a JDK, the same way a Laravel repo asks for PHP with `setup-php`:
+
+```yaml
+    with:
+      setup-java: true # java-version defaults to '25', java-distribution to temurin
+```
+
+The body installs it through `actions/setup-java` with `cache: gradle`, so a re-run of the same pull request restores the Gradle wrapper and dependencies instead of downloading them; toolchains are not cached, because Gradle finds the installed JDK and provisions nothing. `_ci-e2e.yml` and `_ci-lighthouse.yml` take the same three inputs. `cache: gradle` keys on the repo's Gradle build files, so the opt-in expects them to exist.
+
 ### Adding a check needs no workflow change
 
 Because the job list comes from the gate script, a repo adds a check by editing `package.json` alone. The `.gitignore` drift check is the worked example: