ci: build CLI only when it changes, reuse prior release otherwise

.github/filters.yaml

@@ -34,6 +34,36 @@ frontend: &frontend
 cli: &cli
   - 'tools/dotcms-cli/**'
 
+# Server-side REST endpoints the dotCMS CLI consumes at runtime. The CLI's
+# integration tests (tools/dotcms-cli, @QuarkusTest + testcontainers) exercise a
+# live dotCMS, so a change to one of these endpoints can break the CLI even when
+# tools/dotcms-cli/** is untouched.
+#
+# Keep in sync with the @Path REST-client interfaces in
+# tools/dotcms-cli/api-data-model/src/main/java/com/dotcms/api/*API.java
+cli_endpoints: &cli_endpoints
+  - 'dotCMS/src/main/java/com/dotcms/rest/api/v1/asset/**'           # AssetAPI          -> /v1/assets
+  - 'dotCMS/src/main/java/com/dotcms/rest/api/v1/folder/**'          # FolderAPI         -> /v1/folder
+  - 'dotCMS/src/main/java/com/dotcms/rest/api/v1/site/**'            # SiteAPI           -> /v1/site
+  - 'dotCMS/src/main/java/com/dotcms/rest/api/v1/contenttype/**'     # ContentTypeAPI    -> /v1/contenttype
+  - 'dotCMS/src/main/java/com/dotcms/rest/api/v2/languages/**'       # LanguageAPI       -> /v2/languages
+  - 'dotCMS/src/main/java/com/dotcms/rest/api/v1/workflow/**'        # WorkflowAPI       -> /v1/workflow
+  - 'dotCMS/src/main/java/com/dotcms/rest/api/v1/authentication/**'  # AuthenticationAPI -> /v1/authentication
+  - 'dotCMS/src/main/java/com/dotcms/rest/api/v1/user/**'            # UserAPI           -> /v1/users
+  - 'dotCMS/src/main/java/com/dotcms/rest/api/v1/analytics/event/**' # AnalyticsAPI      -> /v1/analytics/content/event
+  # Asset push/pull is the CLI's heaviest workflow; WebAssetHelper (in the asset
+  # package above) delegates into these asset-specific business APIs.
+  - 'dotCMS/src/main/java/com/dotmarketing/portlets/fileassets/business/**' # FileAssetAPI
+  - 'dotCMS/src/main/java/com/dotcms/browser/**'                            # BrowserAPI
+  - 'dotCMS/src/main/java/com/dotcms/rest/api/v1/temp/**'                   # TempFileAPI (CLI file uploads on the push path)
+
+# CLI test trigger: run the CLI integration tests when the CLI sources change OR
+# when any server endpoint the CLI consumes changes. Distinct from `cli` (which
+# gates the GraalVM native build) so endpoint-only changes don't force a rebuild.
+cli_test: &cli_test
+  - *cli
+  - *cli_endpoints
+
 sdk_libs:
   - 'core-web/libs/sdk/**'
 

.github/workflows/cicd_1-pr.yml

@@ -82,7 +82,11 @@ jobs:
       postman: ${{ fromJSON(needs.initialize.outputs.filters).backend == 'true' }}
       karate: ${{ fromJSON(needs.initialize.outputs.filters).backend == 'true' }}
       frontend: ${{ fromJSON(needs.initialize.outputs.filters).frontend == 'true' }}
-      cli: ${{ fromJSON(needs.initialize.outputs.filters).cli == 'true' || fromJSON(needs.initialize.outputs.filters).backend == 'true' }}
+      # Run CLI tests only when the CLI sources or a REST endpoint the CLI consumes
+      # change (cli_test filter). A deep backend/service-layer change that alters CLI
+      # behavior without touching a watched endpoint is covered by the trunk CLI run
+      # (cicd_3-trunk.yml gates CLI tests on the broad `backend` filter post-merge).
+      cli: ${{ fromJSON(needs.initialize.outputs.filters).cli_test == 'true' }}
       e2e: ${{ fromJSON(needs.initialize.outputs.filters).build == 'true' }}
     secrets:
       DOTCMS_LICENSE: ${{ secrets.DOTCMS_LICENSE }}

.github/workflows/cicd_2-merge-queue.yml

@@ -31,7 +31,11 @@ jobs:
       postman: ${{ fromJSON(needs.initialize.outputs.filters).backend == 'true' }}
       karate: ${{ fromJSON(needs.initialize.outputs.filters).backend == 'true' }}
       frontend: ${{ fromJSON(needs.initialize.outputs.filters).frontend == 'true' }}
-      cli: ${{ fromJSON(needs.initialize.outputs.filters).cli == 'true' || fromJSON(needs.initialize.outputs.filters).backend == 'true' }}
+      # Run CLI tests only when the CLI sources or a REST endpoint the CLI consumes
+      # change (cli_test filter). A deep backend/service-layer change that alters CLI
+      # behavior without touching a watched endpoint is covered by the trunk CLI run
+      # (cicd_3-trunk.yml gates CLI tests on the broad `backend` filter post-merge).
+      cli: ${{ fromJSON(needs.initialize.outputs.filters).cli_test == 'true' }}
       e2e: false
     secrets:
       DOTCMS_LICENSE: ${{ secrets.DOTCMS_LICENSE }}

.github/workflows/cicd_3-trunk.yml

@@ -95,6 +95,12 @@ jobs:
       java-version: ${{ github.event.inputs.java-version || '' }}
       maven-compiler-release: ${{ github.event.inputs.maven-compiler-release || '' }}
       artifact-suffix: ${{ github.event.inputs.artifact-suffix || '' }}
+      # Post-merge safety net for the CLI. The PR/merge-queue pipelines gate CLI
+      # tests on the narrow `cli_test` filter (CLI sources + the REST endpoints the
+      # CLI consumes), so a deeper business-layer change can slip through untested.
+      # On trunk we run the CLI tests for any backend change to catch that on main
+      # before it reaches a release. (Skipped on java-version overrides, like build-cli.)
+      cli: ${{ !github.event.inputs.java-version && fromJSON(needs.initialize.outputs.filters).backend == 'true' }}
     secrets:
       DOTCMS_LICENSE: ${{ secrets.DOTCMS_LICENSE }}
     permissions:
@@ -112,11 +118,17 @@ jobs:
       SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}
 
   # CLI Build job - builds CLI artifacts
-  # Skipped when java-version is overridden due to GraalVM/Quarkus compatibility requirements
+  # Skipped when java-version is overridden due to GraalVM/Quarkus compatibility requirements.
+  # Also skipped when the CLI sources are unchanged: the CLI is self-contained under
+  # tools/dotcms-cli/** (its only com.dotcms dependency, dotcms-api-data-model, lives in that
+  # same subtree), so the `cli` path filter is a correct change-key. This avoids the expensive
+  # 3-OS native matrix (incl. two macOS runners) on every trunk push when the CLI didn't change.
+  # When skipped, the deployment job's deploy-cli input is also disabled (see below) so it does
+  # not try to download CLI artifacts that were never produced.
   build-cli:
     name: CLI Build
     needs: [ initialize,test ]
-    if: always() && !failure() && !cancelled() && !inputs.java-version
+    if: always() && !failure() && !cancelled() && !inputs.java-version && fromJSON(needs.initialize.outputs.filters).cli == 'true'
     uses: ./.github/workflows/cicd_comp_cli-native-build-phase.yml
     with:
       buildNativeImage: true
@@ -130,7 +142,10 @@ jobs:
     uses: ./.github/workflows/cicd_comp_deployment-phase.yml
     with:
       artifact-run-id: ${{ needs.initialize.outputs.artifact-run-id }}
-      deploy-cli: true
+      # Only deploy the CLI when it was actually (re)built this run. build-cli is skipped when the
+      # CLI sources are unchanged or java-version is overridden; in those cases there are no fresh
+      # cli-artifacts-* to deploy, so deploy-cli must be false to avoid a missing-artifact failure.
+      deploy-cli: ${{ !inputs.java-version && fromJSON(needs.initialize.outputs.filters).cli == 'true' }}
       publish-npm-sdk-libs: ${{ fromJSON(needs.initialize.outputs.filters).sdk_libs == 'true' && github.event_name != 'workflow_dispatch' }}
       environment: trunk
       # tag-identifier intentionally omitted: trunk uses only the environment name as its tag

.github/workflows/cicd_5-lts.yml

@@ -90,7 +90,7 @@ jobs:
       postman: ${{ fromJSON(needs.initialize.outputs.filters).backend == 'true' }}
       karate: ${{ fromJSON(needs.initialize.outputs.filters).backend == 'true' }}
       frontend: ${{ fromJSON(needs.initialize.outputs.filters).frontend == 'true' }}
-      cli: ${{ fromJSON(needs.initialize.outputs.filters).cli == 'true' }}
+      cli: ${{ fromJSON(needs.initialize.outputs.filters).cli_test == 'true' }}
       e2e: false
     secrets:
       DOTCMS_LICENSE: ${{ secrets.DOTCMS_LICENSE }}

.github/workflows/cicd_comp_initialize-phase.yml

@@ -163,9 +163,9 @@ jobs:
           #
           # test_filters: Subset of build_test_filters affected by CICD_SKIP_TESTS
           # ============================================================
-          build_test_filters="frontend cli backend build jvm_unit_test"
+          build_test_filters="frontend cli cli_test backend build jvm_unit_test"
           info_filters="sdk_libs documentation cicd"
-          test_filters="frontend cli backend jvm_unit_test"
+          test_filters="frontend cli cli_test backend jvm_unit_test"
 
           declare -A results