AEM Sites Playbook, Chapter 18: Environments, pipelines, testing and release quality
Is a change compatible, tested and recoverable on the target environment?
November 10, 2026
Specify the change and its release path
Use this chapter for application, component, configuration, index, frontend or web-tier changes. Record the source revision, dependency versions, affected content and expected behavior. Choose the supported release path for the actual deployment. A content update and a code/configuration deployment can be related without being the same operation.
Maintain an environment comparison: AEM/runtime/tool versions, configuration, domains, identities, connected services and representative content. Include differences that are intentional, such as a local image-delivery fallback, so a developer does not spend time trying to reproduce a cloud-only service locally.
Use compatible dependencies and the Core Component matrix. Review Cloud Service project structure and development requirements for that branch; retain the actual 6.5/LTS procedures for those environments. A successful local install cannot prove that a target pipeline or platform will accept the package.
Diagnose the first failing check
The Dispatcher discrepancy discussion separates local link/tooling problems from a pipeline configuration defect. The author confirms a pipeline repair but not complete local resolution. Compare the same revision, SDK/tool release, mode, links and validation phase before treating the two observations as contradictory. Follow Dispatcher validation guidance, including the prerequisites for the operating system in use.
Capture the first actionable failure and the related logs. Keep later cascading errors separate. If dependency/runtime compatibility changes, identify that before changing application logic. The index-package case reports a local repair, not permission to override Cloud Service managed-index or package boundaries.
Build the acceptance set across roles
Scroll horizontally if needed.
| Change area | Minimum representative checks to select for the project |
|---|---|
| Component/template | Existing rendering, new editing, validation, responsive content and inclusive interaction |
| Publication/content | Approval baseline, dependencies, destination, freshness and withdrawal |
| Permissions/API | Allowed/denied actions, identities, payload contract and failure/replay behavior |
| Delivery/URL | Routing methods, redirects, cache/privacy variation, metadata and domain consistency |
| Upgrade/dependency | Author tasks, deletion/restore, integrations, query behavior and recovery |
These are selection prompts, not a claim that the same short suite covers every installation. Expand them for the actual risk and customer tasks. Automate stable, repeatable checks where useful; retain human evaluation where usefulness or interaction requires it.
Use fixtures with long translations, optional/missing fields, shared references and realistic media. The blank editor, multifield focus and servlet rewrite cases supply concrete regression scenarios. A build can pass while one of those essential tasks fails.
Match checks to what the change can affect
Community discussions describe partial repairs at different stages of a release. A pipeline repair does not establish complete local-tool resolution, and a local package repair demonstrates only that project's outcome. Release evidence must identify the actual revision, stage and target rather than inherit a pass from a different environment.
Scroll horizontally if needed.
| Change | Include in the test selection | Owner who accepts the consequence |
|---|---|---|
| Shared component/template | Existing and new content, author interaction, locales and accessibility | Content/design/platform owners |
| Web-tier route/cache rule | Methods, domains, redirects, API paths, cache variation and metadata | Delivery/application owners |
| Content model/API | Existing consumers, reference changes, updates and withdrawal | Model/consumer owners |
| Identity/profile | Permitted and denied actions across relevant routes | Business/security/platform owners |
| Dependency/runtime | Activation, packaging and representative task regressions | Engineering/platform owners |
| Operational procedure | Alert, failure handling, recovery and handover | Service/support owners |
Keep the test selection proportionate but explicit. A small text change and a shared template change need different evidence. Record why a check is irrelevant rather than omit an affected boundary without explanation.
Worked scenario of a combined component and web-tier release
This hypothetical release changes a product component and its page-route configuration. The engineer has a successful local build. The release owner requires compatible deployment, usable authoring, correct customer routes and a demonstrated recovery path.
The team retains the same source revision and fixtures while comparing stages:
Scroll horizontally if needed.
| Stage | Required evidence | Illustrative observation |
|---|---|---|
| Local validation | Correct tooling/mode and first failing check | Pass after a documented link prerequisite is met |
| Target pipeline | Supported package/configuration and quality gates | A separate header/configuration defect fails |
| Author acceptance | Normal user edits and saves realistic content | A nested dialog loses task focus |
| Public route | Correct methods, destinations and component output | Main GET works; a related POST redirects incorrectly |
| Release recovery | Previous compatible state and authority are understood | Recovery has not yet been rehearsed |
The release remains on hold. The owner assigns separate repairs for pipeline configuration, author interaction and the API route, then schedules the recovery rehearsal. Re-running the pipeline alone cannot close the other findings.
After correction, the team repeats all affected checks on the intended target configuration and completes the recovery exercise. In this hypothetical continuation, the defined fixtures pass and the approvers authorize the scoped release. Post-release observations use the same task/route list. The tested scope remains explicit; unrelated brands or components do not inherit an untested guarantee.
Preserve a useful environment comparison
Record the application/dependency revision, AEM/runtime release, SDK/tools, configuration, connected-system destinations, identities and representative content. Note intentional differences such as a local delivery fallback. An environment that looks similar in the console may still lack the fixture or API entitlement needed for the test.
When a failure differs by stage, identify the first meaningful divergence. Use Dispatcher tooling guidance, project structure and the target's deployment requirements. Do not weaken validation to make the environments agree. If the current local environment cannot reproduce a managed service behavior, retain that limitation and test the appropriate target instead.
Decide how a failed mandatory check affects the window
Scroll horizontally if needed.
| Result | Permitted decision to consider |
|---|---|
| All mandatory checks pass for the defined scope | Authorize that release with observation and recovery ownership |
| A mandatory task fails | Hold or explicitly redesign/narrow scope where requirements permit |
| A non-mandatory limitation remains | Record impact, owner, accepted scope and review date |
| Evidence is missing | Obtain it or record a decision that does not pretend the check passed |
| Recovery is incompatible with current content | Resolve the recovery/content plan before relying on rollback |
Set authority before the window: who can halt, approve a narrower release or initiate recovery? Include ordinary support coverage and the person who will inspect post-release results. A green deployment notification is a checkpoint, not the final business acceptance.
Hand over the actual release state
Give the receiving operator the deployed revision, content fixtures, intentional environment differences, outstanding limitations and the first checks to run after an alert. Identify which credentials and approvals the recovery procedure requires without placing secrets in the handover. Have that operator explain how to distinguish an application regression from a content/publication issue using the retained evidence. If the answer depends on a developer's private notes or memory, complete the handover before treating support readiness as passed.
Record release and recovery authority
Complete W18 with the release identity, environment differences, required tests, results, approvers and recovery approach. Define the hold condition before the release window. Agree who can stop, continue within a narrower scope or restore the prior state. Coordinate content changes with the code/configuration they require and retain both identities. After release, repeat critical observations through the public/author routes and hand unresolved issues to a named operator rather than assume successful deployment ended the work.
W18 Release manifest and acceptance
Use with chapter 18. Set required results and hold conditions before the window.
Scroll horizontally if needed.
| Record | Entry |
|---|---|
| Source / code / configuration / dependency identity and affected content | [enter] |
| Target environment and intentional local/pipeline differences | [enter] |
| Required automated/human checks and fixture identities | [enter] |
| First failing check, diagnosis and regression evidence | [enter] |
| Business/technical approvers, hold condition and recovery authority | [enter] |
| Post-release observations, exception owner and handover | [enter] |
Related chapters
3. Engineering foundations and maintainable customization · 4. Authoring, components, templates and design systems · 10. Preview, publication, scheduling and withdrawal · 19. Monitoring, maintenance, incidents and recovery · 20. Upgrades, migration, cutover and continuous improvement
