Adovo

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.

Build the acceptance set across roles: table 5
Change areaMinimum representative checks to select for the project
Component/templateExisting rendering, new editing, validation, responsive content and inclusive interaction
Publication/contentApproval baseline, dependencies, destination, freshness and withdrawal
Permissions/APIAllowed/denied actions, identities, payload contract and failure/replay behavior
Delivery/URLRouting methods, redirects, cache/privacy variation, metadata and domain consistency
Upgrade/dependencyAuthor 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.

Match checks to what the change can affect: table 8
ChangeInclude in the test selectionOwner who accepts the consequence
Shared component/templateExisting and new content, author interaction, locales and accessibilityContent/design/platform owners
Web-tier route/cache ruleMethods, domains, redirects, API paths, cache variation and metadataDelivery/application owners
Content model/APIExisting consumers, reference changes, updates and withdrawalModel/consumer owners
Identity/profilePermitted and denied actions across relevant routesBusiness/security/platform owners
Dependency/runtimeActivation, packaging and representative task regressionsEngineering/platform owners
Operational procedureAlert, failure handling, recovery and handoverService/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.

Worked scenario of a combined component and web-tier release: table 11
StageRequired evidenceIllustrative observation
Local validationCorrect tooling/mode and first failing checkPass after a documented link prerequisite is met
Target pipelineSupported package/configuration and quality gatesA separate header/configuration defect fails
Author acceptanceNormal user edits and saves realistic contentA nested dialog loses task focus
Public routeCorrect methods, destinations and component outputMain GET works; a related POST redirects incorrectly
Release recoveryPrevious compatible state and authority are understoodRecovery 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.

Decide how a failed mandatory check affects the window: table 15
ResultPermitted decision to consider
All mandatory checks pass for the defined scopeAuthorize that release with observation and recovery ownership
A mandatory task failsHold or explicitly redesign/narrow scope where requirements permit
A non-mandatory limitation remainsRecord impact, owner, accepted scope and review date
Evidence is missingObtain it or record a decision that does not pretend the check passed
Recovery is incompatible with current contentResolve 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.

W18 Release manifest and acceptance: table 20
RecordEntry
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]

Continue exploring

Adobe Experience ManagerAEM Sites

AEM Sites Playbook, Chapter 1: Strategy, value, ownership and adoption

What outcome justifies the work, and who will operate it?

Read more
Adobe Experience ManagerAEM Sites

AEM Sites Playbook, Chapter 10: Preview, publication, scheduling and withdrawal

How do we release and remove the complete approved experience?

Read more
Adobe Experience ManagerAEM Sites

AEM Sites Playbook, Chapter 11: Delivery, Dispatcher, CDN, domains and caching

Which layer controls the request, redirect or stale response?

Read more
Explore data and analytics services →