feat(ci): run integration suites under an ES→OS migration phase (#36320)

[fabrizzio-dotCMS]

Proposed Changes

Enables running the full integration battery under a chosen ES→OS migration phase, both locally and in CI. Contributes to #36320 ("Make it possible to run MainSuite Tests in all 3 phases").

The opensearch-phase-suite Maven profile already existed (two clusters ES @9207 + OS 3.x @9201, sets DOT_FEATURE_FLAG_OPEN_SEARCH_PHASE, inherits the base suite includes). This PR wires that capability into the day-to-day tooling — it does not change any product code, and default (phase 0) behavior is untouched.

Local (justfile)

• New recipe test-integration-phase-all <N> — iterates the MainSuite/Junit5 suites one at a time (forkCount=1) under phase <N>, giving an attributable per-suite pass/fail plus a summary (non-zero exit if any suite fails). This is the triage tool for de-ES-ifying the ITs.
• Documented that test-integration-phase <N> (no test arg) already runs the full battery in a single JVM.

CI

• cicd_comp_test-phase.yml: new opensearch_phase input. setup-matrix appends -Dopensearch.phase=<N> to the integration MainSuite/Junit5 matrix entries only — never the OpenSearch Upgrade Suite (it already drives OS via -Dopensearch.upgrade.test). The value is passed via env (not interpolated into the github-script) to avoid script injection. Empty/0 = off; only 1/2/3 activate a phase.
• cicd_1-pr.yml: a PR carrying a PR: opensearch phase <N> label runs the integration battery under that phase (mirrors the existing PR: docker image label pattern). No label → phase 0 (current behavior).
• cicd_4-nightly.yml: workflow_dispatch gains an opensearch_phase choice input for on-demand runs; phases 1/2/3 skip the deployment job (test-only — never deploy a build that ran under a non-default phase).

Checklist

• YAML validated; matrix-generation logic simulated against the real test-matrix.yml (phase applied to the 6 MainSuite/Junit5 entries, skipped for the Upgrade Suite, no-op when off).
• Smoke-verified locally: just test-integration-phase 1 ContentletIndexAPIImplTest brings up both clusters, bootstraps OS under PHASE_1_DUAL_WRITE_ES_READS, and runs the suite.
• No product code changed (CI/tooling only).

Notes for reviewers

The PR: opensearch phase <N> PR label must exist in the repo labels for the label trigger to be selectable.

Related: #36320, PR #36268 / #36266 (added the opensearch-phase-suite profile).

[claude]

Claude finished @fabrizzio-dotCMS's task in 3m 30s —— View job

---

Code Review — ES→OS phased integration suite

I reviewed the diff against origin/main, cross-checked the matrix generator against .github/test-matrix.yml, the opensearch-phase-suite/opensearch-upgrade Maven profiles in dotcms-integration/pom.xml, and the nightly/PR workflow wiring.

The core logic is sound: the matrix generator appends -Dopensearch.phase=<N> only to integration entries, guards with /^[1-3]$/, and correctly excludes the Upgrade Suite by matching opensearch.upgrade.test in its maven_args. Passing OPENSEARCH_PHASE via env (not string-interpolated into the github-script) is the right call for injection safety. Type/default handling across the three workflows is consistent.

A few things worth raising — none are code bugs, but two affect how the feature actually behaves in CI:

New Issues

• 🟡 Medium: .github/workflows/cicd_1-pr.yml:114 — The PR workflow triggers only on types: [opened, synchronize] (line 30-32), not labeled. Adding a PR: opensearch phase <N> label to an already-open PR will not start a phased run on its own — a new push (synchronize) or re-open is required. This matches the existing PR: docker image behavior (line 83), and the PR body acknowledges mirroring that pattern, so it's a known/consistent limitation rather than a defect. Flagging so reviewers/users know the label must be present before the run that consumes it. Assumption: no separate labeled-triggered entry point exists for this. What to verify: whether the team wants label-then-rerun to be self-service (would need labeled added to types).

• 🟡 Medium: .github/workflows/cicd_comp_test-phase.yml:182 — The phase is appended to the existing 6 MainSuite/Junit5 matrix entries in place; it does not add new entries. So a PR labeled for phase testing runs its integration battery only under phase <N> and no longer under the default phase-0 store. That's reasonable for a deliberate opt-in triage label, but it means: (a) normal phase-0 integration coverage is dropped for that run, and (b) a legitimate phase-related failure (the whole point of the exercise) will fail the PR's integration check and can block merge. Worth confirming this is the intended trade-off, and/or documenting it next to the label so users don't mistake a phase failure for a regression in their change.

Notes (non-blocking)

• justfile:181 — the suite list (MainSuite1a … Junit5Suite1) is hardcoded and duplicates the test_class values in .github/test-matrix.yml. If suites are added/renamed there, this recipe silently drifts (a new suite won't be triaged). A comment pointing at test-matrix.yml as the source of truth would help. set -uo pipefail without -e plus the if ./mvnw … guard is correct for "continue past failures + non-zero exit if any failed."
• .github/workflows/cicd_4-nightly.yml:185 — deployment if guard (inputs.opensearch_phase == '' || inputs.opensearch_phase == '0') correctly preserves scheduled-run deploys (inputs is empty on schedule, so == '' holds) and dispatch default '0'. Good.

No blocking issues. The two Mediums are behavioral/documentation clarifications, not correctness bugs.
• issue-36320-phased-integration-suite