Migrating from Red Hat Developer Hub to self-hosted Backstage

Yes, but the move is a re-registration, not an export. Catalog entities are defined in descriptor files, usually catalog-info.yaml, stored in each source control repository. An upstream Backstage app reads those files once you register the repositories as catalog locations in its configuration. The entity records in the Developer Hub database are not carried across, so anything created only through the portal UI, or stored by a plugin in its own database, must be recreated from source. Check the current catalog documentation for the descriptor schema, the location configuration keys and the annotations your teams rely on. Confirm that the upstream version you choose reads the same kinds and annotations, then compare the ingested entity count against your old portal before you cut over.

Usually they do not need a rewrite, but they do need to be re-pointed and tested. Software templates are Template entities defined in YAML, with steps that call scaffolder actions and live in template repositories. Register those repository locations in the new app, and the templates appear once the catalog ingests them. Steps that use actions built into the Backstage scaffolder carry over. Any custom action, or any action supplied by a plugin that is not installed upstream, must exist in the new app before the template runs. Inventory every action each template calls, then run each template end to end in a staging app. A missing action usually fails at run time, not at registration, so registration alone does not prove the template works.

TechDocs sites are rebuilt and published from source, and the portal's existing generated output is not a documented input for a new install. Documentation lives as Markdown in the repositories that own each component, with an MkDocs configuration file. The new app needs a TechDocs builder and a publisher that writes the generated sites to storage the app can read. Each component's catalog entry needs an annotation that points to its docs. Ask your team whether builds will run in CI or inside the portal, because that choice determines how storage credentials are managed. Treat the old storage bucket as something to verify, not a path to copy from. Confirm the builder, publisher and annotation options in the TechDocs documentation for your target version before you start.

It helps with version changes between Backstage releases, but it is not a migration tool between distributions. The Backstage Upgrade Helper shows the template changes between two Backstage versions, so your team can see what to edit in an app it already owns. It does not map Developer Hub configuration, plugins or data into a new app. Use it after you have a working upstream app to confirm that the version you choose matches the core packages you expect. Upgrades move all @backstage packages together with yarn backstage-cli versions:bump, and the release line you follow determines how often you take them. Verify the release line, supported Node.js versions and each upgrade step in the keeping Backstage updated guide before you rely on any version number.

No documented importer converts Red Hat Developer Hub RBAC policy into upstream Backstage permissions, so plan to recreate it. Roles and policies must be rewritten for the permission framework you configure in the new app. Export your current role assignments group by group, then map each one to the permissions you will enforce, and keep that mapping in version control so reviewers can read it. Identity matters as much as the policy. Sign-in resolvers must map each provider's identity to the same catalog user, or group-based rules have nothing to match. Grant access by group, not by individual account, where your identity provider allows it. Confirm the permission framework behavior, the policy format and the group handling in the authentication documentation and the permissions documentation for your version.

No documented export carries installed plugin state across, so you need to inventory and reinstall. Developer Hub loads dynamic plugins from packaged artifacts that its deployment configuration enables. Upstream Backstage plugins are normally compiled into your app through package dependencies and code wiring. These are different packaging models, so a dynamic plugin package is not a drop-in for a compiled plugin. List every enabled plugin in your Helm values or operator configuration, with its version and config keys. For each one, decide whether an upstream equivalent exists and whether it needs a backend, a frontend or both. Plugin-owned databases and secrets do not move automatically. Confirm each plugin's installation method in the Red Hat Developer Hub 1.10 documentation and in the upstream plugin's own README.

Treat the configuration as a reference to rewrite, not a file to load unchanged. Developer Hub settings arrive through app configuration and deployment values, and many keys reflect its packaging. Upstream Backstage reads its own app-config files, and keys for the catalog, integrations, authentication and TechDocs must be checked against the version you deploy. Start from a fresh upstream configuration and copy only the values you can explain, such as integration hosts and organization names. Move credentials through your secret management system, never into config files. Keep the old Helm values or operator resource as a reference until the cutover is verified. Confirm each key in the configuration reference for your target version, because upstream keys change between releases.

The cost is mostly people time, plus the infrastructure you run yourself. No Backstage fee applies because Backstage is licensed under Apache-2.0 and has no paid edition from the project itself. The main cost drivers are the number of plugins you rely on that are shipped in RHDH, how many of them you must compile into your own app, the size of your catalog and template library, and how many identity providers you connect. Your subscription to Red Hat Developer Hub may end or change, so check its terms with Red Hat. Ask any partner for a quote that separates one-time build work (app setup, plugin porting, RBAC design, data migration) from recurring work (upgrades, patching, on-call support, plugin maintenance).

The timeline depends on how many plugins you must replace, how much of your RBAC policy you need to rebuild, and how many teams depend on the portal. Plugins that Red Hat ships for RHDH, such as Argo CD, Kubernetes, Tekton, Keycloak and GitHub integrations, exist as community or upstream packages, but each one needs to be installed, configured and tested in your own app. Identity work often sets the pace, since sign-in resolvers must map every provider to the same identity. Start by listing the plugins and dynamic plugin configuration you use today, then ask for a written schedule that ties each phase to a parallel-run or cutover checkpoint.

Three groups of people are needed from your side. Identity administrators must confirm the identity providers, group sync, and the sign-in resolver logic, and they must agree that guest access will not be used in production. Plugin owners must confirm which plugins the portal needs, the versions they rely on, and the credentials and endpoints each one uses. Catalog owners must review the entities that move across, confirm ownership, and clean up records that have no owner. Your team also needs an agreed place to host the app and a named person who will run upgrades after handover.

Yes, if your team already runs Kubernetes, a PostgreSQL database and an identity provider, and has someone comfortable with TypeScript and the Backstage CLI. The upstream project publishes an upgrade helper and a release policy, so the work is documented. The harder parts are the ones that are specific to your organization: rewriting RBAC rules, porting any RHDH-specific plugin configuration, and building a support rota. Many teams split the work, keeping the infrastructure and day-to-day operations in-house while bringing in outside help for plugin porting and the identity cutover. Ask a partner to explain which parts they would hand back to you.

Most catalog descriptors (catalog-info.yaml files) and entity definitions can be reused because they follow the open Backstage descriptor format. Software templates use the same scaffolder model, so templates can usually move with them. Expect rework where templates call actions or plugins that only exist in RHDH, where they reference Red Hat-specific pipelines or OpenShift resources, or where custom actions were compiled into the RHDH image. Check your template library for those dependencies first. The catalog and templates should be validated in a staging instance before any production switch, and each entity's owner should confirm the result.

Moving to upstream Backstage removes the vendor support contract that comes with Red Hat Developer Hub. You will no longer have Red Hat as the first point of contact for product defects, supported plugin builds, or the documented installation paths on OpenShift, Azure Kubernetes Service and Amazon Elastic Kubernetes Service. Upstream fixes arrive through the Backstage release lines, and the versioning policy says high and critical vulnerabilities are backported to releases from the last six months where feasible. Your own team, or a partner under a retainer, must then cover security response, upgrades, and incident handling. Confirm with Red Hat what your current subscription includes and what it ends.

Dynamic plugins are loaded from configuration at runtime, while compiled plugins are built into your app. RHDH uses dynamic plugins heavily, so teams often assume the same model applies in upstream Backstage, which is not automatic. Compiled plugins are the default approach for a self-built app, and they make upgrades and testing more predictable because the whole app is versioned and built together. Dynamic loading can reduce image rebuilds, but it adds a plugin packaging step and more things to verify. Decide this per plugin, and keep a register of which ones your team has to rebuild on each upgrade.

Backstage does not carry your RHDH role configuration across as-is, so you need to rebuild authorization on the upstream authorization model. Start by listing every role, group and permission your RHDH deployment grants, then map each one to a permission policy in your own Backstage app. Test the policies with real user accounts from each team before cutover, including denied actions. Authorization decisions should be documented because auditors often ask how access was assigned and reviewed.