Backstage just removed the catalog relations compatibility layer — no more catalog.enableRelationsCompatibility, no fallback shape. From now on the Catalog API returns relations in the standard targetRef-only format. If any of your plugins, syncers, or external systems were silently relying on the old relation shape, they will fail to find targets or will mis-handle relations during upgrade time.
This is the single most consequential change in the recent releases. The compatibility flag and its bridging behavior lived in v1.55.x and earlier as a temporary escape hatch; it's gone. Practically, that means any code that inspected relation payloads expecting legacy fields or that munged relation objects before storing them will have to be updated to parse targetRef(s) only. External identity — catalog importers, scaffolder actions that write relations, or one-off sync jobs that backfilled relations — are the likely culprits that will hit production failures first.
Two other changes in the same window make this a non-trivial upgrade for platform teams.
First, @backstage/plugin-search-backend-module-elasticsearch moved to the Elasticsearch 8 client and now targets Elasticsearch 8.x servers. Effect: Elasticsearch 7.x clusters are unsupported with the new client, so instances talking to self-hosted ES7 clusters (or managed clusters still on ES7) will see search break after the upgrade. This migration was overdue — ES7 reached end-of-life — but it won't be painless. Expect analysis/mapping differences and plan for reindexing when you move to ES8.
Second, Backstage published an official codemods repository (backstage/codemods) and versioned migration recipes (for example, v1-56-0 migration recipes). These codemods automate many surface-level API and UI transforms — import paths, plugin API adjustments, and relation shape changes. They're not magical, but they turn a multiday manual hunt-and-replace into deterministic, CI-driven transforms. If you run Backstage at platform scale, add these codemods to your CI upgrade pipeline, run them in an isolated branch, and treat the results as reviewable infra changes.
A related operational change: Scaffolder introduced requireScmUserCredentials. This flag allows platform teams to require user-provided SCM credentials for SCM mutation and fetch actions. That's the right call. Forcing user-supplied creds keeps an auditable chain between actions and identities and avoids the “platform bot did it” problem where shared platform credentials obscure provenance and violate least-privilege principles.
Here’s what to do in the next 30 days.
- Run the v1.56 codemods in a branch and treat the resulting diffs as any breaking change: code review, run unit/integration tests, and stage rollout. The codemods will catch many relation and API shape changes.
- Audit every consumer of Catalog relations: scaffolder templates, custom plugins, sync jobs, ingestion pipelines. Replace legacy relation parsing with targetRef semantics and change writers to emit targetRef-only relations.
- Verify your Elasticsearch endpoint and plan for reindexing to ES8. Pinpoint analyzers and mappings that differ between your current cluster and ES8 to avoid search regressions.
This set of changes is a sign Backstage is transitioning from a forgiving, compatibility-first project to a platform that expects teams to own upgrades and reduce legacy surface area. That's healthy — but it raises the bar operationally. If you’ve been kicking compatibility debt down the road, this release window will force your hand.
Final thought: Backstage's new posture — codemods + stricter APIs + security-first scaffolder controls — is the right path for platform teams that want predictable, auditable platforms. It will be painful for orgs that treated Backstage as a long-lived experiment. Upgrade now on your terms, not on someone else’s timetable.