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
- Build and unit tests — Maven build in Cloud Manager's image. A failing unit test stops the pipeline here, before any scan.
- Code scanning — SonarQube (9.9 since Cloud Manager 2025.1.0) with Adobe's rule set, plus OakPAL content-package checks.
- Build images — your artifacts are assembled with the current AEM release.
- Stage deploy — blue-green; a failure leaves the previous version serving.
- 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). - Approval / schedule — optional manual approval, then a scheduled production deploy.
- 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-versionselects the build JDK:21(preferred),17, or11.8is 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.xmlthat contains no secrets:
<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.shgreen 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.