Migrate from OpsLevel to Backstage

Migrate from OpsLevel to Backstage without losing ownership data

Most teams leave OpsLevel because of a renewal, a licensing change or a residency requirement, and the move is mainly a data and ownership project, not a code rewrite. The work is to get every service, team and owner out of OpsLevel, express them as Backstage catalog entities, and keep those entities accurate until the switch is complete. Platform engineering teams usually own this work, and many bring in an implementation partner for the export scripts, the catalog model and the cutover plan. The effort depends mainly on how many services OpsLevel tracks, how clean its ownership records are and how many integrations feed it. Backstage is Apache-2.0 licensed and has no paid edition from the project itself, so the recurring cost moves to your own hosting, build work and plugin maintenance. Confirm those components with your team before you size the project.

Start with an inventory rather than a conversion. Use the MIT-licensed OpsLevel CLI or the GraphQL API to export services, teams and ownership, then compare the export with what your teams believe is true. Ownership gaps found in this step are cheaper to fix now than after the catalog is live. Next, decide how each OpsLevel service maps to a Backstage Component, System or Group and to a catalog-info.yaml file in the owning repository. Confirm with the owning teams where the descriptor should live, who may edit it and how a Location entry will point the catalog at it. Check the Backstage descriptor format documentation for the exact required fields before you write a converter, because a converter that drops owner values will silently break routing.

Phase the switch so both systems can be compared for a fixed period. Run the Backstage catalog in parallel, reconcile owner and lifecycle fields against OpsLevel every time a sync runs, and only retire OpsLevel integrations one team at a time. Plan the rubric and check migration separately, because OpsLevel checks do not translate one to one into Backstage. Ask your partner and your security team to sign off on the sign-in design as well: the Backstage authentication documentation advises configuring sign-in resolvers so every provider maps to the same identity and avoiding guest access in production. Before you cancel the OpsLevel contract, confirm the export is complete, retain a dated copy of it for audit and record who approved the cutover.

Which OpsLevel capabilities map cleanly to Backstage

This table maps the main OpsLevel capabilities to their closest Backstage equivalents and marks each as clean, needs rework or gap. Read the status column first, then the confirm column for items that depend on your own OpsLevel configuration and integrations. The main takeaway is that catalog and ownership data move cleanly, while maturity rubrics and push-based integrations need design work before cutover.

OpsLevel capability	Backstage equivalent	Status and what to confirm
Services and components	Software Catalog Component entities in catalog-info.yaml files	Clean. Confirm each service has a stable name and a repository location the catalog can reference.
Teams and ownership	Group entities with owner fields on Components and Systems	Needs rework. Confirm team names match identity provider groups so ownership resolves to one identity.
Individual users	User entities populated by the sign-in resolver and catalog providers	Needs rework. Confirm your chosen auth provider maps each person to a single User entity.
Systems, domains and APIs	System, Domain and API entities, with OpenAPI, AsyncAPI, GraphQL or gRPC definitions	Clean for most APIs. Confirm which API specifications exist in source control today.
Documentation links	TechDocs, which builds MkDocs sites from Markdown kept next to the code	Needs rework. Links to external wikis stay as links, so confirm which docs must move into repositories.
Self-service actions	Software Templates that scaffold repositories and run actions	Needs rework. Confirm each OpsLevel-triggered action has an equivalent scaffolder step or external workflow.
Maturity rubrics and checks	Tech Insights checks and fact-based scorecards	Gap for direct export. Confirm each rubric rule can be written as a fact or rule-based check before retiring OpsLevel scores.
Push-based integrations and webhooks	Backstage plugins or scheduled ingestion from source systems	Gap until replaced. Confirm which OpsLevel integrations push data and which source systems can be polled instead.

What exports, what converts and what to rebuild

Moving from OpsLevel to Backstage is three jobs: pull the existing catalog out, rewrite its ownership and service records as catalog descriptors, and rebuild the integrations that fed OpsLevel. Each card below covers one of those jobs or one of the checks that keeps ownership data accurate while you do them.

Exporting with the OpsLevel CLI

The MIT-licensed OpsLevel CLI can export services, teams and checks through Terraform and produce JSON or CSV output. Use the Terraform export as a structured snapshot of what OpsLevel holds, then keep that snapshot under version control so you can compare later runs. Confirm with OpsLevel which resource types the current CLI version exports, since coverage of checks and custom properties varies by release. Record the export date next to the file so the team knows which state of ownership it reflects.

Paging and rate limits in the GraphQL API

The GraphQL API is the path for data the CLI export does not cover, such as relationships between services and teams or fields added by your own configuration. Results are paged, so a complete pull needs a loop that follows cursors until no more pages remain, and it must respect the rate limits OpsLevel documents for your account. Run large pulls outside working hours and write each page to disk so a failed run can resume. Verify the paging and limit details against OpsLevel's current API documentation before scripting against them.

Converting opslevel.yml to catalog-info.yaml

Each service that carries an opslevel.yml file needs a matching catalog-info.yaml descriptor in Backstage. Map the service name, description, lifecycle and tags to the Component kind, and map the owning team to the spec.owner field. Keep the descriptor in the same repository as the code so it changes with the service. Expect some fields to have no direct equivalent and decide, field by field, whether to carry them as annotations, drop them or rebuild them as checks.

Mapping ownership to Group and User entities

Teams in OpsLevel become Group entities in Backstage, and the people in them become User entities that reference those groups. Ownership is only accurate if each Component points to a Group that exists, and each Group lists members who exist as Users. Run a validation pass after import that lists components with missing or dangling owners, because a broken owner reference will show a service as unowned even when the team is correct. Treat this list as the acceptance test for the cutover.

One identity across sign-in providers

Backstage's authentication guidance says to configure sign-in resolvers so every provider resolves to the same identity, and to avoid guest access in production. If a person signs in through GitHub in one place and Google or Okta elsewhere, they can end up with two User entities and split ownership. Decide which provider is the source of identity, map the others to it, and test with accounts that use more than one provider. Confirm the resolver setup against the current Backstage authentication documentation before go-live.

Rebuilding integrations as plugins or ingestion

OpsLevel pulled source control, CI and cloud resources into its catalog through its own integrations, and Backstage does not reproduce those by default. For each integration, decide whether a Backstage plugin covers it, whether a scheduled ingestion job can populate the catalog, or whether the data should be dropped. Start with the integrations that feed ownership, because a stale source integration will quietly leave services with outdated owners. List every integration before you start so none is lost in the move.

Rebuilding maturity checks

OpsLevel rubric checks do not transfer as-is. Export the checks, then sort each one into three groups: checks that become Backstage facts or rule-based checks, checks that need a custom plugin, and checks you retire. Keep a written record of which checks were retired and why, so teams can see the change rather than find a missing score later. Confirm the rubric scoring with your platform owners before you present progress to teams.

The migration sequence from inventory to decommission

The sequence moves ownership data from OpsLevel into a Backstage catalog in controlled stages, so each team's owners stay accurate at every point. Each step closes with a written artifact that the next step depends on, and OpsLevel is switched off only after a defined verification.

Inventory services, teams and checks
Export services, teams, ownership relationships and rubric checks from OpsLevel using the OpsLevel CLI's Terraform export or its JSON and CSV output, or pull the same data through the GraphQL API if you need paging control. The platform team reviews the export with team leads to flag stale services, duplicate records and services with no owner. The output is an inventory workbook with one row per service, its owning team, its repository location and its current check results, signed off by the platform owner.
Pilot conversion with a few teams
Choose a small set of teams whose services are well understood and convert their opslevel.yml files into catalog-info.yaml descriptors, using the Backstage descriptor format for Component, Group and System kinds. Register the pilot entities in a non-production Backstage instance and confirm each owner resolves to the correct Group entity. The output is a pilot report listing every converted descriptor, every field that needed manual mapping and the team leads' written acceptance of their entries.
Reconcile ownership in a parallel run
Run OpsLevel and Backstage side by side for the pilot and then the wider estate, with both catalogs fed from the same source repositories. Compare owner, team and system assignments for every service each day or on each sync, and log every mismatch with a named owner who resolves it. The output is an ownership reconciliation report that shows zero unexplained differences for the scope under review, and a record of how each difference was closed.
Replace rubric checks in Backstage
Map each OpsLevel rubric check to a Backstage Tech Insights check or to a catalog-based property, and agree with each team which checks still apply. Confirm the new checks produce the same pass or fail results on the reconciled services before anyone relies on them for reporting. The output is a check mapping document listing each original rubric item, its Backstage equivalent and any check that was retired or redefined by agreement.
Cut over team by team or domain
Move teams or business domains in groups, starting with the lowest-risk group from the pilot. For each group, make Backstage the system of record for ownership, update the repository files and access rules that depend on owner data, and tell the on-call and incident contacts where the new catalog lives. The output is a cutover record per group, dated and signed by the team lead, showing the source of truth moved and the rollback path that was tested.
Verify the catalog snapshot before decommission
Take a final catalog snapshot from Backstage and compare it with the last OpsLevel export for every migrated group, checking services, owners, relationships and check outcomes. Ask the auditors or internal risk owners which evidence they need from the old portal and confirm it is preserved in the new one. The output is a signed-off catalog snapshot and a retained archive of the OpsLevel export, approved by the platform owner and the security lead.
Decommission OpsLevel after verification
Once the verification snapshot is signed off, disable OpsLevel integrations that push ownership data, revoke API tokens and remove the webhooks that pointed at the old portal. Confirm with your vendor how long your subscription and data remain available under your contract before you cancel, and what export formats apply at exit. The output is a decommission record listing each integration removed, each credential revoked and the date the subscription was closed, filed with the verification snapshot.

How to run both portals in parallel and cut over safely

Ownership stays accurate during the overlap only if every field has exactly one system of record. Decide that per field before the first sync: for example, the owning team and on-call contact might live in the service's catalog-info.yaml in Git, while scorecard results stay in OpsLevel until their Backstage replacement is live. Write the decision down in a short table that names the field, the owner of that field and the direction data flows. A sync that runs in both directions on the same field will eventually overwrite a correction, so treat the reverse flow as a deliberate exception rather than a default. Reconcile on a fixed schedule, for example a weekly diff of services, teams and owners pulled through the OpsLevel CLI export against the catalog, and log every mismatch with a named person who resolves it.

Cutover should happen team by team, not portal by portal. During each team's window, freeze ownership edits in one place: announce the date, stop changes in OpsLevel for that team's services, run a final export and diff, then make Backstage the only place where the team's owners, groups and lifecycle are edited. Keep OpsLevel in read-only use for that team for a short period so people can check history and rubric results. Confirm with the OpsLevel account team, in writing, how long your subscription and any licensed self-hosted edition remain active after notice, whether the CLI and GraphQL API keep working until the contract ends, and whether you can run full exports during that notice period. Also confirm how the license file or subscription terms apply if you stop renewing before every team has moved. Build your exit plan around those answers, not around an assumed date.

What drives migration cost and duration

This table lists the components that set the cost and effort of moving OpsLevel data and checks into a self-hosted Backstage portal, and what each one depends on. Read it as a checklist for scoping: the one-time items are mostly migration work, while the recurring items are hosting, plugin upkeep and release tracking that continue after cutover.

Cost driver	What it depends on	One-time or recurring
Services and teams in scope	Number of services, teams and ownership records exported through the OpsLevel CLI or GraphQL API, and how many have a clear owner	One-time
Clean opslevel.yml files	How many service files already convert to catalog-info.yaml with little editing, versus those needing manual review of owners, lifecycle and tags	One-time
Maturity checks to replace	Number and complexity of OpsLevel rubric checks, and how many translate into Backstage Tech Insights facts and checks	One-time, then recurring as rules change
Integrations to rebuild	Each source system that feeds ownership or status today, such as CI, cloud accounts or incident tools, and whether a Backstage plugin or custom ingestion exists for it	One-time build, recurring upkeep
Plugin build and maintenance	Custom plugins, version pinning and upgrades against Backstage's monthly main line or weekly next line	Recurring
Hosting and PostgreSQL	Kubernetes or VM capacity, a PostgreSQL database for production, backups, and the caching layer you choose	Setup one-time, operating cost recurring
Authentication setup	Choice of provider from the 19 built-in options, sign-in resolvers that map each provider to one identity, and whether guest access is disabled	One-time, then recurring review
Release tracking and Node.js support	Monthly main line and weekly next line releases, security backports to releases from the last 6 months, and the two supported Node.js versions (22 and 24 for Backstage 1.46.0)	Recurring
Parallel running window	Length of time both portals run so ownership data stays accurate during cutover, which your own team sets during planning	One-time, with overlapping run costs

What usually goes wrong and how to prevent it

Most failed OpsLevel to Backstage cutovers do not fail on the catalog import itself. They fail afterward, when ownership drifts, checks go missing, or the team switches off the old system before anyone has verified the new one. Each card below names one failure and the check that prevents it.

Stale ownership after cutover

Teams keep changing owners, on-call rotations and repository names after the import, so the catalog starts drifting the day it goes live. Ownership is the data people rely on during incidents, so a wrong owner is worse than a missing entry. Before cutover, freeze a snapshot of owners from the OpsLevel export, then run a reconciliation against the source of truth for team membership, such as your identity provider or repository permissions. Assign a named owner to the catalog itself and set a review date for each team's entries.

Duplicate or orphaned entities

Running the OpsLevel export alongside catalog-info.yaml files produced by repositories can create two entities for one service, or leave entities that point at repositories that were renamed or archived. Duplicates split scorecard results and confuse ownership queries. Give every entity a stable metadata.name and a single source of truth per service, then list entities that have no matching repository or that share a repository URL. Remove or merge the extras before any team relies on the portal.

Rubric checks that do not translate

OpsLevel rubric checks often depend on OpsLevel-specific concepts, such as its own tag and ownership logic, so a direct copy can silently pass or fail services for the wrong reason. Treat each check as a claim to re-test, not a rule to port. Export the checks, write each one as a Backstage fact or rule-based check, and run both systems side by side for the same services. Investigate every service where the results disagree before you retire the OpsLevel check.

Guest access left on in production

A Backstage instance built from the default template may still allow guest sign-in, which lets anyone reach catalog data that OpsLevel protected with your identity provider. The Backstage authentication documentation advises against guest access in production. Before go-live, remove the guest provider from the production configuration, confirm that unauthenticated requests are refused, and test sign-in with a user who has no team membership. Record the result as evidence for your access review.

Identity resolvers that create two users

When a person signs in through more than one provider, such as GitHub and Google, a resolver that maps each provider to a separate identity produces two Backstage users with two sets of group memberships. Ownership then points at the wrong user record and access reviews miss the duplicate. The authentication documentation recommends sign-in resolvers that make every provider resolve to the same identity. Test with one person who uses each provider, and confirm that both logins show a single user entity with the expected groups.

Upgrades outside the versioning policy

Teams that upgrade Backstage ad hoc often fall behind, or jump versions in a way that breaks plugins. Backstage ships a main release line monthly and a next release line weekly, and it backports high and critical security fixes only to releases from the last six months. Choose a release line deliberately, pin the Node.js version the policy supports, and schedule upgrades on a recurring cadence. Keep the portal inside the supported window so security fixes can be applied without a rebuild.

Decommissioning before verification

Shutting down OpsLevel, or cancelling its subscription, before the parallel run ends removes the only complete record of ownership and checks. Keep the OpsLevel export archived and the subscription active until teams have confirmed their entities, owners and check results in Backstage. Set an exit criterion in writing, such as zero unresolved ownership mismatches for each team, and ask your OpsLevel account contact what data retention applies after cancellation. Only decommission once that criterion is signed off.

How the migration differs by size and starting point

When one platform team owns a modest catalog, the migration is mostly a question of sequencing and discipline rather than volume. The team can usually inventory services, teams and checks in one working session, decide which entities become Backstage components, and move the catalog in a few passes. Because few people edit the catalog, the main risk is that the team moves too fast and leaves OpsLevel and Backstage disagreeing about who owns what.

Export first, then decide scope: Pull the full service and team list through the OpsLevel CLI or GraphQL API before choosing which entities to carry over.
Pick one owner per entity: Confirm that each service has a single owning Group in the catalog-info.yaml before any consumer reads it.
Convert in small batches: Move a few teams at a time and compare ownership output in both systems after each batch.
Keep the rubric simple at first: Port only the checks the team actually reviews, and postpone the rest.
Set a cutover date for ownership edits: Decide when edits move to Backstage so two systems never accept changes to the same service.

Before cutover, confirm with the team that every service shows the expected owner and that Backstage sign-in resolves each user to one identity.

Questions buyers ask before moving from OpsLevel to Backstage

How much effort and cost does moving from OpsLevel to Backstage involve?

The cost is mostly people time and hosting, not a license fee, because Backstage is Apache-2.0 licensed and has no paid edition from the project itself. The main drivers are the number of services and teams to migrate, how many opslevel.yml files need conversion to catalog-info.yaml, how many checks must be rebuilt, which plugins you need, and how much custom integration work your environment requires. One-time costs include export scripting, descriptor conversion, catalog validation and cutover. Recurring costs include hosting the Backstage backend with PostgreSQL, upgrades (the main release line ships monthly and the next line weekly, per the Backstage versioning policy) and plugin maintenance. If you bring in an implementation partner, ask for a fixed-scope written proposal that lists each deliverable, and compare it against your own staffing estimate. DeployOpen plans and implements these migrations under written scope, and it does not publish prices.

How long does an OpsLevel to Backstage migration take?

The timeline depends on catalog size, the number of teams that must confirm ownership, and how many OpsLevel checks and integrations must be replaced before you can retire the old portal. Services that already have clean ownership data and a single owning team move faster than those with shared or unclear ownership. Plan the work in phases: export, convert, run both portals in parallel, then switch ownership sources team by team. No duration figure is supplied for this migration, so ask any vendor or partner to commit to a timeline based on your inventory and to show the phases in writing, and check each phase against your own change calendar and any renewal deadline with OpsLevel.

What does the migration need from our engineering and platform teams?

Expect to need a platform engineer who owns the Backstage deployment, engineers who review converted descriptor files for their own services, and an owner for identity configuration. Backstage's authentication documentation advises configuring sign-in resolvers so every provider resolves to the same identity and not offering guest access in production, so your identity team must be involved early. Security and compliance staff should review how catalog data, API definitions and TechDocs content are stored and accessed. Confirm named owners and their available hours before the project starts.

Can we do the migration ourselves with the documented OpsLevel exports?

Yes, many teams can export their data themselves, because the OpsLevel CLI supports Terraform export and JSON or CSV output, and the GraphQL API can return services, teams and checks. The harder work is judgment: deciding which services become Backstage components, which teams own them, how to map OpsLevel tiers and aliases to entity fields, and how to rebuild checks. Confirm the exact CLI version, export options and GraphQL paging and rate limits in OpsLevel's current documentation before you script anything. A partner is most useful when you need a reproducible pipeline, validation rules and cutover support, not because the export itself is closed.

Does Backstage have a paid edition I should budget for?

No. Backstage is an open source framework released under the Apache License 2.0, and there is no paid edition from the project itself. Your costs come from running the infrastructure, building and maintaining your deployment, and any third-party plugins or commercial support contracts you choose to buy. The CNCF accepted Backstage on September 8, 2020 and moved it to the Incubating maturity level on March 15, 2022, according to the CNCF project page, which describes its governance, not a license fee. Confirm the license terms for any individual plugin you plan to use, since plugins are separate projects.

How do we handle OpsLevel maturity rubrics during the move?

Do not copy rubric scores directly, because Backstage has no one-to-one equivalent to OpsLevel rubrics. Export your existing checks first, then translate each one into a Backstage Tech Insights fact or rule-based check that produces a comparable result. Run both systems side by side for a period so teams can see whether the new results match what they expect, and agree on how maturity levels will be presented before you retire OpsLevel scorecards. Some checks will need custom code, and some may not translate at all, so list those gaps early and decide with each team whether to drop, redefine or keep them in a separate tool.

How do we keep ownership data accurate during the switch?

Assign a single source of truth for ownership at each phase, and do not let OpsLevel and Backstage both edit the same field. Convert opslevel.yml files to catalog-info.yaml descriptors, which use kinds such as Component, Group and User, and validate them in a staging catalog before you go live. Confirm with each team that its services, owner groups and dependencies appear correctly, then switch ownership writes team by team. Keep the OpsLevel export as a rollback reference until every team has signed off.

What changes for developers and owners after cutover

The most visible change is where ownership lives. After cutover, a service owner updates its catalog-info.yaml in the repository that builds the service, and the Backstage catalog reads that file, so a change to the owner, lifecycle or dependencies is a commit and a pull request rather than an edit in the OpsLevel UI. Owners should expect to make that change in code review, with the same approval path they use for application code. Before cutover, confirm with the platform team which fields in the converted files are authoritative, and whether the owner reference on each Component points to a Group or User entity that actually exists in the catalog. Catalog entities are described by YAML descriptor files, and Backstage's descriptor format documentation lists the kinds an owner can reference, so a short reference sheet with the kinds your teams will use is worth preparing before the first repository changes.

Templates and TechDocs replace OpsLevel workflows only where your team has built equivalents. Backstage Software Templates give developers a scaffolding path for new services, and TechDocs builds documentation sites from Markdown kept next to the code using MkDocs. Whether a given OpsLevel workflow maps cleanly onto one of these is a question to answer per workflow, not assume: list the actions your developers take in OpsLevel today, mark which ones a template or a docs page can cover, and identify the rest as open items with an owner. Confirm the MkDocs plugins your documentation needs before you commit to a TechDocs layout, since the core feature set is documented but your plugin choices determine the build. Team leads should also agree on who answers the question "where do I change this?" during the first weeks, because the answer moves from a vendor interface to a repository.

Training needs to cover the repository workflow, the descriptor format and the portal itself, and it should be short, role-based and tied to real repositories. Plan one session for service owners on editing catalog-info.yaml, validating changes and reading catalog errors, one for team leads on approving ownership changes, and one for platform engineers on the portal's operation. Write a runbook that covers how to request a new entity, how to fix a broken descriptor, how to deal with a missing owner and who to contact for sign-in problems. Sign-in deserves a specific check: the Backstage authentication documentation advises configuring sign-in resolvers so every provider resolves to the same identity and not offering guest access in production, so confirm that with your identity team before developers log in. Keep the training materials in the same repository as the catalog so they are updated when the descriptor format changes.

How DeployOpen scopes and runs the migration

DeployOpen plans and implements the move from OpsLevel to a Backstage portal inside your own cloud accounts, data centers or air-gapped networks. Engagements are fixed-scope, so the catalog, ownership mapping, check replacement and cutover steps are agreed in writing before work starts.

How we scope

Inventory the OpsLevel services, teams, owners, tags and rubric checks that the Backstage catalog must reproduce.
Agree which OpsLevel data sources, Terraform exports and GraphQL extracts feed the first catalog load.
Define the phased cutover, the parallel-run period and the owners who sign off ownership accuracy at each stage.

How we build

Convert opslevel.yml files into catalog-info.yaml descriptors, with kinds, owners and relations validated against your entity model.
Stand up the Backstage instance, PostgreSQL database, sign-in resolvers and catalog ingestion in your environment.
Rebuild maturity checks as Backstage Tech Insights checks, then test each one against known services before go-live.

How we hand over

Deliver the descriptor conventions, ingestion configuration, check definitions and runbooks as documented source in your repositories.
Document the reconciliation steps used to confirm ownership data matches the source before OpsLevel is switched off.
Walk your platform and engineering teams through upgrades, plugin maintenance and the on-call steps for the new portal.

How we support

Support after handover, including upgrades and plugin maintenance, is available as a retainer agreed separately from the migration scope.
Ask for a written quote that lists each deliverable, the environments in scope and the responsibilities your team keeps.
Confirm with your OpsLevel contract terms and export rights before scoping, so the data extraction timeline is set accurately.

Migrate from OpsLevel to Backstage