# Cloud Manager quality gates — what fails and how to fix it

> **Verified:** 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/using-cloud-manager/code-quality-testing and https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/using-cloud-manager/create-application-project/build-environment-details

Open this when a pipeline step fails, or before a release when you want the first run to be green.

## Gate levels

| Level | Behaviour |
|---|---|
| **Critical** | The pipeline stops. No override |
| **Important** | The pipeline pauses; a Deployment Manager, Project Manager or Business Owner can override and continue |
| **Info** | Reported only |

Unit-test **line coverage of 50 %** is an *Important* metric — overridable, which is exactly why teams end up with 20 % coverage and a habit of clicking through. Treat an override as a dated, recorded exception with an owner, never as a workflow.

Security and Cloud Service compatibility findings are not candidates for an override at all: they describe code that will misbehave on the platform.

## The steps, in order

1. **Build and unit tests** — Maven build in Cloud Manager's image. A failing unit test stops the pipeline here, before any scan.
2. **Code scanning** — SonarQube (9.9 since Cloud Manager 2025.1.0) with Adobe's rule set, plus OakPAL content-package checks.
3. **Build images** — your artifacts are assembled with the current AEM release.
4. **Stage deploy** — blue-green; a failure leaves the previous version serving.
5. **Stage testing** — product functional tests, custom functional tests (`it.tests`), custom UI tests (`ui.tests`), and the experience audit (Lighthouse-based scoring of configured paths).
6. **Approval / schedule** — optional manual approval, then a scheduled production deploy.
7. **Prod deploy** — blue-green.

## The failures you will actually hit

| Finding | Cause | Fix |
|---|---|---|
| **Customer Package Quality: mixed package** | One package contains both `/apps` and `/content` or `/conf` | Split into `ui.apps` (`packageType=application`) and `ui.content` (`packageType=content`) |
| **Package overlaps `/libs`** | A component overlays a product path | Extend with `sling:resourceSuperType` instead |
| **Index definition not allowed** | `/oak:index` node in a package without `allowIndexDefinitions`, or a name that breaks the grammar | `<allowIndexDefinitions>true</allowIndexDefinitions>` and the correct name — see `oak-index-naming.md` in `../../../development/aem-backend-development/references/` |
| **Filter root too broad / replace mode** | `<filter root="/content/acme"/>` with the default replace mode | `mode="merge"` and a narrower root |
| **Cloud Service compatibility: `loginAdministrative`** | Admin session in code | Service user with repoinit and a sub-service mapping |
| **Cloud Service compatibility: writing to `/apps` or the file system** | Runtime writes to immutable paths | Write to `/var`, `/conf`, or an external store |
| **Sonar: unclosed resource** | `ResourceResolver` not in try-with-resources | try-with-resources; never close `request.getResourceResolver()` |
| **Coverage below 50 %** | New code without tests | Tests for the new Sling Models and services (`aem-testing`) |

**You cannot reproduce all of these locally with SonarQube.** Adobe's AEM-specific rules are not shipped as a SonarQube plugin. What you *can* run locally is the AEM Analyser Maven plugin (part of the archetype build), which catches the Cloud Service compatibility class of finding; a local Sonar run covers only the generic rules.

## Build environment facts

- `.cloudmanager/java-version` selects the build JDK: `21` (preferred), `17`, or `11`. `8` is no longer supported for AEM as a Cloud Service.
- The compile target must match what the AEM release runs — the runtime moved to Java 21 in 2025.
- Third-party artifacts must come from a repository the build can reach. Credentials for a private repository are **pipeline variables** (build-time), not environment variables (runtime), and are referenced from a committed `settings.xml` that contains no secrets:

```xml
<server>
  <id>acme-private</id>
  <username>${env.ACME_REPO_USER}</username>
  <password>${env.ACME_REPO_TOKEN}</password>
</server>
```

## UI tests

Custom UI tests run only when you opt in: a `testing.properties` file containing `ui-tests.version=1` next to the `ui.tests` module's `pom.xml`. Cypress is the default; Playwright, WebdriverIO and Selenium are supported. The runner receives `AEM_AUTHOR_URL`, `AEM_PUBLISH_URL`, `AEM_AUTHOR_USERNAME`, `AEM_AUTHOR_PASSWORD` and `REPORTS_PATH`, and Cloud Manager reads **JUnit XML reports from `REPORTS_PATH`** — it does not look at your exit code. A test suite that fails loudly but writes no XML is reported as passing. See `aem-testing`.

## Release checklist

Fill this in for a go-live and attach it to the release ticket:

- [ ] Local build and `validate.sh` green on the current SDK
- [ ] Code scanning: zero critical; importants fixed, or recorded with an owner and a date
- [ ] Index changes named correctly and deployed ahead of the code that needs them
- [ ] repoinit covers the new service users and ACLs; no user content in packages
- [ ] Environment variables and secrets created on stage **and** production before the deploy
- [ ] Stage tests and the experience audit reviewed; UAT signed off
- [ ] Deploy scheduled off peak; the revert plan names the commit to redeploy
- [ ] Post-deploy smoke test and a log check, with an owner for each

## Experience audit

The experience audit scores configured paths with Lighthouse on every stage deployment and reports the delta against the previous run. It is a trend signal, not a gate you should tune for: pick the handful of paths that represent the site, and investigate drops with the tools in `aem-performance`.
