Rollback strategy
Purpose: Define what rollback means per change type in AEM — because code, config and content roll back differently.
Who this page is for
| Audience | Why it matters to you |
|---|---|
| All engineers | Everyone deploys |
| Tech leads | Release planning |
Rollback is three different problems
| Change type | Rollback mechanism | Gotchas |
|---|---|---|
| Code (bundles, /apps) | Redeploy previous versioned package | Clean if packages are complete/immutable; hotfix drift breaks it |
| Config (OSGi, dispatcher) | Previous config version via same pipeline | Dispatcher config needs web-server reload + possibly cache flush |
| Content/structure (/conf templates, CF models, migrations) | Often no clean rollback — forward-fix or restore | Model/structure changes affect content created since; plan before, not after |
The content-coupling trap
The dangerous release is code + content-structure together: v2 component reads a new property shape; authors edit 50 pages; v2 has a bug. Rolling back code breaks the 50 pages. Defenses:
- Expand/contract: v2 reads new shape AND old shape (expand); migrate content; remove old-shape support releases later (contract). Same discipline as DB migrations.
- Feature flags (config-gated behaviour) so code can ship dark and toggle off without redeploy.
- Never bundle irreversible content migrations with feature code in one release.
Per-release rollback plan (write it down)
- Trigger: what observation invokes rollback (error rate X, feature broken, sev1)?
- Decision maker: who calls it?
- Steps: exact commands/pipeline runs, including dispatcher/CDN flush if needed.
- Verification: how we know rollback worked (same checks as deploy verification).
- Content note: what authors did since deploy and what happens to it.
Rehearse on stage quarterly — the deployment runbook and rollback runbook hold the operational detail.