How to migrate from Port to Backstage without losing the catalog
If your renewal, data residency rules or lock-in concerns are pushing you off Port, the short answer is this: the catalog can move, but Port blueprints must be remapped to Backstage kinds such as Component, API, Resource, System and Domain, and Port's self-service actions have to be rebuilt as Software Templates. Platform engineering teams usually own this work, often with an implementation partner who handles the export scripts, the descriptor templates and the cutover plan. The effort depends mostly on how many blueprints you have, how many relationships between them need to survive, and how many actions carry business logic that lives in Port's action runners today. Treat the blueprint inventory as the first deliverable, because every later step depends on it.
Backstage is licensed under Apache-2.0 and has no paid edition from the project itself, so the license line on your quote should be zero. What remains is infrastructure (a PostgreSQL database, hosting for the backend and the frontend, and CI for the portal's own build), the build effort to model entities and author templates, the plugins you need for integrations, and the ongoing time a team spends upgrading Backstage. Backstage ships a monthly main release line and a weekly next line, so budget for regular upgrades rather than a one-off project. Ask any partner to split their quote into those components. Confirm with your own team whether you also want an identity provider for sign-in, because Backstage's authentication documentation expects sign-in resolvers that map every provider to the same identity and advises against guest access in production.
Run the old and new portals side by side during cutover. Export entities from Port first, using its API as described in the Port export guidance, then generate catalog-info.yaml files and register them through a Location so that ownership and relationships are visible in Backstage before you turn anything off. Keep Port read-only for teams that still depend on it, and set a dated checklist per team covering catalog accuracy, template parity and access rules. Confirm your rollback path before you retire any Port integration, because Port's data integrations may still feed Port's own catalog in parallel. Plan for the data that will not map cleanly, such as Port scorecards and custom properties, and decide in advance whether you rebuild them or accept a gap.
Which Port capabilities map to Backstage and which need rework
This table maps each part of a Port catalog to its closest Backstage equivalent and labels it clean, needs rework or gap. Read the rows as a starting inventory for your migration, then check each Port-specific feature against your own blueprints and integrations. The main takeaway is that the catalog data model moves cleanly, while actions, integrations and access rules need design work.
| Port capability | Backstage equivalent | Status |
|---|---|---|
| Blueprints for Component, API and Resource entities | Catalog kinds Component, API and Resource, each described in a catalog-info.yaml file | Clean: map each blueprint to one kind, then confirm the spec fields you rely on |
| Blueprints for Service groupings and ownership | System, Domain, Group and User kinds, linked through owner and system references | Needs rework: relations must be re-expressed as Backstage references |
| Entities and their properties | Entity metadata, spec fields and annotations in catalog-info.yaml files kept in Git | Needs rework: export entities, then decide which properties stay in Git and which come from live sources |
| Self-service actions | Software Templates with scaffolder actions | Needs rework: rebuild each action as a template and confirm approval steps and backend runners |
| Ocean integrations for Kubernetes, cloud and CI data | Backstage plugins such as Kubernetes, or custom ingestion into the catalog | Gap: confirm a plugin exists for each source before planning custom ingestion |
| Scorecards and maturity rules | Scorecard or insights plugins, which must be confirmed for your Backstage version | Gap: confirm plugin availability and rebuild rules as code |
| Role-based access by plan and team | Sign-in resolvers and permission policies, configured per deployment | Needs rework: map Port roles to Backstage groups and test that identities resolve consistently |
| Port-specific UI features and dashboards | Backstage home page and custom UI plugins | Gap: confirm each Port-only view or widget and budget custom plugin work |
What data moves out of Port and what to rebuild
Port's catalog data leaves through two routes: its REST API and the state of the Terraform resources that manage it. What you can move cleanly is the entity and blueprint data, while integrations, identity links and Ocean-based feeds need to be rebuilt on the Backstage side.
REST API export path
Blueprints and entities can be read through Port's REST API and written to JSON, which becomes the input for generating catalog-info.yaml files. Before you script the export, confirm the regional API endpoint for your Port organization, the access token lifetime and the request limits in Port's current documentation, since these shape how you page through large catalogs. Store the raw export unchanged so you can rerun the mapping as blueprints evolve.
Terraform state route
If Port blueprints and entities were provisioned with Terraform, the state file holds resource definitions that can be read as a second source of truth. This route is useful for catching blueprints created in code, but state may lag behind changes made in the Port UI. Reconcile the state output against the API export before you treat either as complete.
Blueprints become catalog kinds
Each Port blueprint must be assigned a Backstage kind, typically Component, API, Resource, System or Domain. Properties map to spec and metadata fields, and relations map to dependsOn or ownerOf references. Decide the mapping per blueprint in writing, because a blueprint that describes both a service and a database often needs to split into two entities.
Ownership and identity links
Port teams, user references and ownership fields must resolve to Backstage Group and User entities that match your identity provider. Backstage sign-in resolvers need to map every login method to the same identity, so ownership data is only useful once those identifiers are consistent. Check for stale users and retired teams during the mapping review.
Ocean feeds must be rebuilt
Port's data integrations, most built on its Ocean framework, pull from sources such as Git, CI and cloud accounts on a resync interval. Those feeds do not transfer to Backstage. Each one needs a replacement, either a Backstage plugin, a catalog processor or a scheduled ingestion job, and each replacement needs an owner who will maintain it after cutover.
Git and CI links to reconnect
Port entities link to repositories, pipelines and deployment records. In Backstage, these links are set through annotations in catalog-info.yaml and through the plugins that read them, so each annotation and each plugin needs an explicit check. Confirm that every Git and CI link resolves to a live repository and pipeline before you retire the Port links.
Migration sequence from inventory to decommission
This sequence moves a Port catalog into a self-hosted Backstage portal in controlled stages, so each stage produces evidence before the next one starts. Port stays live until the Backstage portal has been checked against it, users are moved, and every action has a tested replacement.
Inventory blueprints, entities and actions
Export the Port data model in full: every blueprint with its properties and relations, the entity counts per blueprint, the self-service actions, and the scorecards and integrations that feed them. Record which Port integrations are hosted by Port and which are self-hosted with Helm or Docker, because the self-hosted ones carry their own infrastructure to retire or keep. Have the owning teams confirm which entities are still active. The output is an inventory spreadsheet with one row per blueprint, action and integration, marked keep, map, rebuild or retire.
Run a pilot with one domain
Choose a single domain with a small number of services, a team willing to give feedback, and a clear owner. Stand up a Backstage instance in your infrastructure with PostgreSQL, sign-in through your identity provider with a single resolver that maps each provider to the same identity, and guest access turned off. Load only that domain's catalog and one Software Template. The pilot is done when the owning team can find, edit and scaffold its components in Backstage and the team lead signs off in writing on what is missing.
Map blueprints to Backstage kinds
Build a mapping table that links each Port blueprint to a Backstage kind such as Component, API, Resource, System, Domain, Group, User or Template, and records how each property and relation translates. Blueprints that describe a service usually map to Component, while infrastructure types often map to Resource. Flag any blueprint with no clean equivalent so the team decides whether to model it as a custom kind, a tag, or drop it. The output is a reviewed mapping table approved by the platform owner and the teams that use the blueprints.
Generate and validate catalog-info files
Script the export of Port entities into catalog-info.yaml descriptor files, one per entity, stored next to the source code they describe. Validate every file against the Backstage descriptor format, check that owner references point to real Group or User entities, and confirm that each Location file registers the expected paths. Run the import in a non-production Backstage instance and compare entity counts and ownership with the Port export. The output is a validated set of catalog-info.yaml files and a reconciliation report showing zero unexplained differences.
Rebuild self-service actions as Software Templates
For each Port self-service action on the keep list, write a Software Template that collects the same inputs, runs the same scaffolder steps, and publishes the same results. Note where an action needs an approval step or a backend runner, and where a custom plugin is needed. Owners review each template with a test run in a sandbox account. The output is a signed-off template list showing each Port action, its Software Template replacement, the reviewer, and any gaps still open.
Run both portals in parallel
Keep Port and Backstage live side by side for a defined comparison window agreed in advance. Each day or each sync cycle, compare entity counts, owners, scorecard results and action outcomes between the two portals, and log every mismatch with its cause. Ask a sample of users from each domain to complete their normal tasks in Backstage and record what they could not do. Treat the parallel run as complete only when mismatches are resolved or accepted in writing by the owners.
Cut over users and actions
Publish the cutover checklist before the switch: DNS or bookmark changes, identity provider configuration, access roles translated from Port to Backstage permissions, integrations repointed to Backstage, the rollback steps, and the named person who can authorize rollback. Move domains in waves, starting with the pilot domain, and confirm each wave against the checklist. Redirect Port links where possible and notify teams before each wave. The output is a completed checklist for every wave and a record of any rollback decisions.
Decommission Port and retire its integrations
After the final wave has been stable through an agreed observation period, export a final archive of Port data and keep it under your records policy. Revoke Port API tokens, remove the Port integrations and any self-hosted Ocean or Helm deployments, and tell the vendor the subscription will end, confirming the contract terms and any data deletion commitments in writing. Remove the old DNS entries and access groups. The output is a decommission record listing the archive location, revoked credentials, removed integrations and the vendor's written confirmation of termination and data handling.
How the migration changes by catalog size and starting point
When most entities were created by hand in Port's UI, the migration is mostly a modeling exercise. Each blueprint becomes a decision about which Backstage kind fits it, and each entity becomes a catalog-info.yaml file that someone must write and place in the owning repository. Because there are few integrations to rebuild, the work is concentrated in review and ownership.
- Blueprint review: List every blueprint and map it to a kind such as Component, Resource, System or Domain. Several blueprints often collapse into one kind with a
typevalue. - Entity export: Pull entities through Port's REST API so the catalog is captured as data before any edits in the UI.
- Ownership placement: Move each descriptor into the repository of the team that owns the service, so ownership lives with the code.
- Relations: Recreate dependencies as
dependsOnandownerOfreferences, since these are the links teams most often miss. - Single cutover: A small catalog can usually move in one batch once entities validate in a staging Backstage instance.
Confirm with your Port administrator which entities were edited by hand after import, because those edits exist only in Port and must be copied across.
When a large share of entities arrive through Ocean integrations, the catalog is a live feed from sources such as cloud accounts, Git hosts and incident tools. The migration then has two parts: the entity data and the pipelines that keep it current. Backstage does not run Ocean, so each feed needs an equivalent ingestion path, either a catalog provider, a processor or a scheduled job that writes descriptors.
- Integration inventory: List every Ocean integration, its source system and its resync interval, which Port documents as configurable for hosted integrations.
- Ingestion equivalents: Decide per source whether Backstage's catalog providers, a custom processor or a generator job from the source system will replace it.
- Volume and sequencing: Migrate feed by feed, starting with the sources that other teams rely on most, and compare counts after each step.
- Dual running: Keep both catalogs populated until each feed has produced matching entities for a full cycle.
- Hosting questions: Port can host these integrations or run them in your infrastructure, so confirm which mode you use before you map the replacement.
Check that every feed has an owner and an alert for failure in the new setup, because a silent stale feed is harder to notice than a missing page.
Teams that already keep service definitions in Git, often generated from Terraform or application repositories, start closer to the target model. The Port entities may largely be a copy of data that exists elsewhere. The migration then focuses on removing duplicate sources of truth and deciding which file is authoritative.
- Source of truth: Decide whether the repository, a generator or Port itself owns each field, and document that decision before export.
- Descriptor generation: Where Terraform state or service manifests already hold owner and tier data, generate
catalog-info.yamlfrom them rather than typing it again. - Drift check: Compare exported Port entities with the code-defined ones to find fields that were edited only in the portal.
- Templates reuse: Existing scaffolding repositories can often become Software Templates with fewer changes, which shortens the self-service rebuild.
- Pull request validation: Run descriptor validation in CI so broken files fail review, not the catalog.
Before cutover, confirm that the generated files produce the same ownership and lifecycle values Port reports today.
In a regulated environment, the question shifts from what to migrate to where the new portal runs and what it can reach. Port's hosted portal cannot run inside an isolated network, so a Backstage deployment must reach the identity provider, Git hosts, container registries and documentation sources from inside the boundary. The catalog migration itself follows the same steps, but the infrastructure and evidence work expands.
- Network path: Map every system the portal must call, and confirm each is reachable from the private network without external dependencies.
- Identity: Configure one sign-in resolver so every provider resolves to the same identity, and disable guest access before production use.
- Data flow: Document where exported Port data is stored during the move and who can read the export file, then delete temporary copies on schedule.
- Change control: Plan upgrades on the Backstage release cadence and the Node.js versions it supports, and record each change for the assessment file.
- Evidence: Keep the export, validation and access-review records, since DeployOpen prepares evidence but auditors and certification bodies decide on it.
Confirm with your security and compliance leads which of these controls they need documented before the first production entity loads.
What drives the cost and duration of the move
This table breaks the move from Port into components, showing who is paid for each, whether it is one-time or recurring, and what pushes it up or down. Use it to scope the work before requesting a quote, since blueprint sprawl, action backends and identity design usually matter more than the portal install itself.
| Driver | Why it changes cost or effort | What to ask for or confirm |
|---|---|---|
| Blueprint count and relationships | Each blueprint maps to a Backstage kind and catalog-info.yaml pattern. Many relations between blueprints need explicit modeling, which raises design and validation time. | Inventory of blueprints, relation types and entity counts from your Port export, with the proposed kind mapping in writing. |
| Self-service actions and backends | Each Port action becomes a Software Template with scaffolder steps. Actions that call external systems or need approvals need custom actions or plugins and tested backends. | Count of actions, the backend each one calls, and which ones need approvals or custom scaffolder actions. |
| Ocean integrations to replace | Port's Ocean integrations push data into the catalog. Each one must be rebuilt as a Backstage ingestion source, a processor or a scheduled sync, then validated against source systems. | List of active integrations, source systems, sync frequency and whether each has a Backstage equivalent or needs custom code. |
| Identity and RBAC design | Backstage has no single built-in permission model for every team. Sign-in resolvers must map each provider to one identity, and access rules must be designed and tested before cutover. | Identity provider used, group structure, the permission policy model and who approves the access design. |
| Plugin choices and maintenance | Plugins for Kubernetes, search, scorecards or cloud resources vary in maturity. Forked or custom plugins add recurring upgrade and security work. | Shortlist of required plugins, whether each is community or custom, and the named owner for each plugin after handover. |
| Hosting and PostgreSQL | Production runs need a managed or self-operated PostgreSQL database, container hosting, backups, TLS and monitoring. These are recurring infrastructure costs billed by your cloud or data center. | Hosting target, database service, backup and restore targets and the environments included in the quote (for example, staging). |
| Upgrade cadence | The main release line ships monthly and the next line ships weekly on Tuesdays, per the versioning policy. Each upgrade needs testing against your plugins and custom code. | Upgrade procedure, test scope per release, and whether upgrades are included in a retainer or billed per change. |
| Platform team time | Someone must own the portal, plugin maintenance, catalog data quality and developer onboarding after go-live. This effort recurs for as long as the portal runs. | Estimated monthly effort per role, the internal owner named for the portal, and the handover plan with documentation. |
| Parallel running during cutover | Running Port and Backstage together means two sets of catalog data and actions to keep consistent until teams switch. Duration depends on how many teams depend on each workflow. | Cutover plan, the number of teams migrated per wave and the criteria for retiring Port actions. |
What usually goes wrong and how to prevent it
Most failed Port to Backstage migrations break in the same few places: the data model, identity, access settings, catalog maintenance, templates and the runtime. Each risk below has a prevention step you can check before cutover, and several of them only show up after users start relying on the new portal.
Blueprints flattened into too few kinds
Teams often map every Port blueprint to a generic Component because it is faster. Port blueprints carry their own properties, relations and ownership fields, and collapsing them loses the distinctions that drive scorecards, filters and ownership views. Before writing any catalog-info.yaml, list each blueprint and choose a Backstage kind (Component, API, Resource, System, Domain, Group or User) that matches how it is used. Check that relations survive the mapping by sampling a few entities in the new catalog.
Identity resolvers mapping one person to several users
When a person signs in through more than one provider, such as GitHub and Okta, the default behavior can create separate User entities. Ownership then splits across duplicate identities and access reviews become unreliable. Configure sign-in resolvers so every provider resolves to the same identity, and test with one account that uses two providers. Confirm that group membership from your identity provider maps to Backstage Group entities before you import ownership data from Port.
Guest access left on in production
Guest sign-in is convenient during a pilot, but it lets unauthenticated or loosely identified users reach the catalog and templates. Teams sometimes forget to disable it when they move from a demo instance to production. Remove the guest provider from the production auth configuration, then verify with a logged-out browser session that catalog pages, TechDocs and scaffolder actions all redirect to sign-in. Record this check in the cutover runbook so it is repeated for each environment.
Catalog-info files drifting from repositories
Port entities were updated from the portal or from integrations, so the source of truth was never the repository. After migration, catalog-info.yaml files can fall behind the code they describe, and the catalog quietly shows stale owners, lifecycles and dependencies. Add the descriptor files to the same repositories as the code, require them in pull request review, and schedule a report that lists entities whose owners no longer exist. Assign one team to own the catalog data after cutover.
Untested Software Templates
Self-service actions in Port often ran in a tested pipeline, but a Software Template that scaffolds a repository, creates a pipeline and registers the new component has many steps that can fail silently. A template that worked in one organization may write to the wrong group or use an expired token elsewhere. Run each migrated template against a sandbox organization, check the generated catalog-info.yaml and the registered entity, and repeat the run after every change to the template or its plugins.
Node.js version mismatches
Backstage supports exactly two adjacent even-numbered Node.js releases, and as of Backstage 1.46.0 these are Node.js 22 and 24. A build server, container image or developer laptop on another version can produce failures that look like plugin bugs. Pin the Node.js version in your build image and in the repository's engines or version files, check it against the current versioning policy before each Backstage upgrade, and plan upgrades on the monthly release line so security backports arrive without a long gap.
Questions teams ask before moving from Port to Backstage
How much effort does a move from Port to Backstage take?
The effort depends on how much catalog data you have, how many blueprints and self-service actions need rebuilding, and how many integrations must be re-pointed at Backstage. Effort rises with the number of custom blueprint relations, the number of Ocean integrations feeding Port, and the number of actions that call internal systems through custom code. It falls when your blueprints map cleanly to Backstage kinds such as Component, API, System and Group, and when most actions can be expressed as Software Templates using existing scaffolder actions. Ask any partner to size the work from an inventory of blueprints, entities, actions and integrations, and to state the assumptions behind that estimate in writing.
Can an internal platform team do the migration alone?
Often yes, if the team already runs Kubernetes, manages Git repositories and understands the services Port reads from. Backstage is a TypeScript and Node.js codebase, so the team needs people comfortable with that stack, plus owners for identity, the database and the plugins they choose. Teams that have not built a portal before usually underestimate catalog modelling and the plugin work. A fixed-scope engagement from DeployOpen can cover planning, implementation, integration, hardening and documentation of the Backstage portal inside your own infrastructure, with scope and deliverables agreed in writing before work starts.
What does the work need from engineering and security teams?
Engineering teams provide the catalog owners, the service repositories where catalog-info.yaml files will live, and the self-service actions they rely on today. Security teams need to define how users sign in, which identity provider resolves each user, and how roles map to catalog access. The Backstage authentication documentation advises configuring sign-in resolvers so every provider resolves to the same identity, and not offering guest access in production. Security should also review the PostgreSQL database, the secrets used by templates and the network paths between Backstage, Git and your cloud accounts before the portal is opened to developers.
Can all of Port's catalog data be exported completely?
Port's REST API exposes blueprints and entities, so most catalog structure and property values can be pulled out in a machine-readable form and mapped to Backstage kinds. Completeness depends on your setup, so confirm it against your own tenant before relying on it. Check that relations, scorecard results, action run history, audit logs and any data written by custom integrations are included in your export path. Also confirm the API token lifetime and request limits for your region, and plan the export as a repeatable script so you can rerun it during cutover. Confirm these details with Port's documentation and account team.
Can the parallel run between Port and Backstage be avoided?
A parallel run can be shortened or skipped for a small catalog with a single team, but it is hard to avoid for a large organization. Port feeds data through integrations that keep updating while you build, so a direct cutover needs a freeze window on catalog changes or a final resync. Running both portals gives teams a fallback while the Backstage catalog is validated against source systems, and it lets owners review entities before developers depend on them. Decide the parallel period based on how many teams depend on Port actions, how often the catalog changes, and how confidently you can reconcile the two data sets.
What ongoing upkeep does a self-hosted Backstage portal require?
Backstage is open source under Apache-2.0 with no paid edition from the project, so the recurring costs are your own infrastructure, the engineers who maintain the portal, and any support retainer you buy. The versioning policy describes a main release line shipped monthly and a next line shipped weekly, and high and critical vulnerabilities are backported to releases from the last six months where feasible. Plan for regular upgrades, Node.js version alignment, plugin maintenance, database backups, monitoring and access reviews. Ask any partner what upgrade cadence, plugin ownership and on-call model are included in the quote.
Does moving to Backstage remove all licensing costs?
Backstage itself carries no license fee, but it is not a zero-cost option. You still pay for compute and storage, the PostgreSQL database, identity provider licenses you already hold, and the people who build, run and upgrade the portal. Some commercial tools that plug into Backstage may carry their own fees. Compare these components with your current Port subscription, including seats, plan features and integrations, rather than comparing license lines alone. The Backstage GitHub repository and CNCF project page confirm the open-source status and project maturity.
How DeployOpen scopes and runs a Port to Backstage migration
DeployOpen is a Chainscore Labs company that plans, implements, customizes, integrates, hardens, backs up, upgrades and documents self-hosted open-source platforms inside the client's own infrastructure, including their cloud accounts, data centers or air-gapped networks. For a Port to Backstage move, that means the Backstage deployment, its PostgreSQL database, the identity provider behind sign-in, the Git hosts that hold catalog-info.yaml files, and the CI pipelines that run Software Templates all sit in your environment, not ours. DeployOpen does not run your catalog for you and does not issue audit reports or certifications. Independent auditors and certification bodies do that work, and DeployOpen prepares the systems, controls and evidence they will review.
Most engagements are fixed-scope. Before any work starts, the written scope names the blueprints to be mapped, the entity kinds that will be produced, the self-service actions to rebuild as Software Templates, the identity and RBAC decisions, the cutover approach, and the deliverables and timelines both sides accept. Items you should expect to see in that scope include the export method (Port's API or Terraform state), the agreed mapping of each blueprint to a Backstage kind, the list of Port integrations that must be replaced or retired, and the criteria for switching teams to the new portal. Ongoing upgrades, Backstage release tracking and support can be added as an optional retainer, which is useful because Backstage ships on a regular release cadence. A quote follows from the written scope, so the more precisely you describe the Port tenant, its integrations and your identity setup, the more precise the quote will be.
