<!--
  Upgrade matrix — Marula PSA documentation
  Source: /docs/psa/v0.3/reference/upgrade-matrix
  License: CC BY 4.0 — https://creativecommons.org/licenses/by/4.0/
  Source file: https://github.com/marulahq/marula-core/tree/main/docs/site/reference/upgrade-matrix.md
-->
---
description: "Every tagged Marula release and the N−2 upgrade paths proven in CI, with the fixture anchors and covered surfaces."
---

<!-- GENERATED by docs/site/scripts/generate-upgrade-matrix.mjs from fixtures/upgrades/ — do not edit by hand. -->
# Upgrade matrix

Every tagged release ships with a CI-proven upgrade path from each of the two previous tagged releases (the **N−2 rule**, policy §1/§8). CI restores each fixture snapshot (a production-like seeded org exercising every customization surface), migrates to HEAD, and runs the API/event conformance suites.

**Latest fixture anchor: `v0.3.0`.** Capture happens at tag time — old snapshots cannot be reconstructed (see fixtures/upgrades/README.md).

| Fixture | Org anchor | Captured | Seed dump | Seed source | Customization surfaces covered (count) |
|---|---|---|---|---|---|
| `v0.2.0` | `00000000-0000-4000-8000-000000000001` | 2026-09-03 | ✓ `v0.2.0.seed.sql.gz` | ✓ | custom_fields (7), boards (2), automation_rules (3), webhooks (2), api_keys (2), settings (4), sla (1), report_definitions (3) |
| `v0.3.0` | `00000000-0000-4000-8000-000000000001` | 2026-10-27 | ✓ `v0.3.0.seed.sql.gz` | ✓ | custom_fields (7), boards (2), automation_rules (3), webhooks (2), api_keys (2), settings (4), sla (1), report_definitions (3), taxonomy (1), client_workflow_overrides (0), roles (1) |

## Notes

- The N−2 matrix anchors on v0.2.0 onward; earlier captures were scoped out of their wave (fixtures README).
- Jump distance at upgrade time: up to two releases behind; further jumps apply the same machinery sequentially.
- Run the preflight before upgrading: `marula upgrade --check` — see the [upgrade how-to](https://getmarula.com/docs/psa/v0.3/how-to/upgrade).
- CI cross-checks customization tables against anything a migration modifies; customizations are migrated as data ([explanation](https://getmarula.com/docs/psa/v0.3/explanation/customizations-are-data)).