Skip to content

Backstage (Developer Portal Framework)

Scope

This file covers Backstage as the build side of the internal developer portal decision: the fixed catalog entity model (Component, System, API, Resource, Group, User, Domain, Template, Location), the catalog-info.yaml descriptor and discovery model, ownership and its decay, Software Templates (the scaffolder) as golden paths, TechDocs, the plugin surface and what it costs to carry, the release and versioning policy that sets the real operating burden, the permission framework, and the commercial distributions (Spotify Portal, Roadie) that change the buy-vs-build calculus.

For the SaaS side of the same decision, see providers/port/internal-developer-portal.md; the Backstage vs Port trade appears in both files and is argued here from the build side. For the governed request-catalog alternative that overlaps on infrastructure requests, see providers/servicenow/itsm.md. For the CI/CD systems Backstage catalogs and templates execute through, see providers/github/ and providers/gitlab/.

Checklist

  • [Critical] Is there a named team that owns the portal as a product, with capacity budgeted for monthly upgrades -- not a side project on top of existing work? (Backstage is a framework, not a product; it self-describes that way. The dominant cost is not licensing, it is the engineers who keep it current, and an unowned Backstage becomes an unupgradable Backstage within about a year.)
  • [Critical] Has the upgrade burden been accepted explicitly, against the actual policy -- a monthly main release line, breaking changes permitted in minor versions with a deprecation of at least one mainline release, no LTS, security fixes backported roughly six months where feasible, and bug reports valid only against the most recent release? (Verified 2026-08-05. This is the single number that decides whether "free" is true.)
  • [Critical] Does the fixed entity model fit the questions being asked -- Component, System, API, Resource, Group, User, Domain, plus Template and Location? (The model is not user-extensible the way Port's blueprints are. Custom kinds and annotations exist but diverge from the ecosystem, and a plugin expecting a standard kind will not understand yours. If the estate does not decompose into these, that is a real signal to weigh Port.)
  • [Critical] How do entities get registered and stay registered -- catalog-info.yaml committed beside the code with discovery providers scanning the org, or manual URL registration? (Discovery is what makes the catalog self-maintaining; manual registration produces a catalog that reflects whoever last remembered to add something.)
  • [Critical] What happens when a descriptor is absent, stale or wrong -- is there a check that a new repo without catalog-info.yaml is visible as a gap, or does it simply not appear? (A missing entity is invisible by construction, which is the failure mode unique to descriptor-in-repo catalogs: the catalog looks clean precisely because something is missing from it.)
  • [Recommended] Where does ownership data come from, and what happens when a team is reorganized -- IdP sync into Group/User, a checked-in org file, or hand-maintained entities? (Ownership is the field every other feature depends on and the first one to rot; a Group that no longer exists silently orphans every component pointing at it.)
  • [Recommended] Are Software Templates treated as maintained code -- owned, tested, and exercised often enough to still work? (A scaffolder template nobody has run in six months encodes a golden path that has since moved, and the first developer to discover that is the one who trusted it.)
  • [Recommended] Is the plugin inventory classified by who maintains each one -- core, community, commercial, or bespoke -- with the upgrade cost of each understood? (backstage-cli versions:bump moves core packages; community plugins move on their own schedules and version skew across them is the usual reason an upgrade stalls.)
  • [Recommended] Is the permission framework configured, and is its scope understood? (It is a policy layer the organization implements, commonly delegated to OPA/Rego for per-plugin decisions; it is not an out-of-the-box RBAC product, and treating it as one leaves actions and reads open by default.)
  • [Recommended] Is TechDocs in scope, and if so who owns the build pipeline and its storage? (Docs-as-code in the repo rendered into the portal is a strong pattern and a second build system to operate; adopting it half-way produces a docs tab that is empty for most services.)
  • [Recommended] Is the deployment architecture defined -- hosting, the PostgreSQL instance, auth provider integration, and backup of the catalog database? (The organization owns all of it. The catalog is largely reconstructible from descriptors, which is a genuine resilience advantage, but the non-catalog state is not.)
  • [Optional] Have the commercial distributions been evaluated before committing to self-hosting -- Spotify Portal, Roadie, and similar -- which absorb the upgrade burden for a fee? (This is the option most self-host decisions never price, and it converts the question from build-vs-buy into a spectrum.)
  • [Optional] Is CNCF Incubating status weighed appropriately for the governance requirement? (Backstage is a CNCF Incubating project originated by Spotify; incubation is a real signal about governance and continuity, and it is not the same as Graduated.)
  • [Optional] Is there a measurable adoption goal beyond deployment -- time-to-first-commit for a new joiner, percentage of services with a current owner, template usage -- rather than "the portal exists"? (A portal is infrastructure for a behaviour change; without a metric there is no way to tell a successful one from an abandoned one that still renders.)

Why This Matters

Backstage's defining property is that it is a framework, which the project says about itself, and almost every disappointed adoption traces back to having bought that word as "product". What ships is a foundation plus a plugin ecosystem; what an organization operates is a Node application it has customized, a PostgreSQL database, an auth integration, and a set of plugins on independent release schedules. The licensing cost is zero and the staffing cost is not, and the staffing cost is recurring rather than one-off. The honest comparison against a SaaS portal is not "free versus per-seat" but "a permanently funded platform team versus a per-seat bill", and organizations that skip that comparison tend to discover it at the first upgrade they cannot complete.

The release policy is where that cost becomes concrete, and it deserves reading before adoption rather than after. The main release line ships monthly; breaking changes are permitted in minor versions, with deprecation guaranteed for at least one mainline release; there is no LTS; security fixes are backported for roughly six months where feasible; and bug reports are only valid against the most recent release. The practical consequence is that falling six months behind is not a version-number problem, it is a support problem — the project's answer to most bug reports at that point is "upgrade". backstage-cli versions:bump handles core packages well, and the stall is almost always community plugins that have not moved yet, which is why the plugin inventory belongs in the design rather than growing by accretion.

The catalog's own failure mode is different from a pulled catalog's and worth naming because it is quiet. Backstage entities are declared by catalog-info.yaml files committed beside the code and found by discovery. That is a genuinely good model: ownership lives with the team, changes go through review, and the catalog is largely reconstructible. But a service whose descriptor was never written simply does not appear, and a catalog that is missing things looks identical to a catalog that is complete. A pulled catalog (Port's Ocean integrations, for instance) fails loudly by showing stale data; a descriptor catalog fails silently by showing less data. Whichever model is chosen, the check that matters is the one comparing the catalog against an independent inventory of what actually exists — repositories, running workloads, cloud resources — because neither model detects its own absences.

Common Decisions (ADR Triggers)

  • Backstage vs Port, from the build side -- Backstage is free to license and costly to operate: a framework the organization hosts, extends and upgrades monthly, with a fixed entity model that keeps small deployments coherent and constrains large ones. Port is SaaS with user-defined blueprints and managed ingestion, priced per seat, with no customer-hosted control plane. Choose Backstage when service metadata must not leave the organization, when deep custom UI or bespoke plugins are the point, or when a platform team already exists and wants to own the surface. Choose Port when time-to-value matters, when the estate does not decompose cleanly into Component/System/API, or when there is no team to fund permanently. See providers/port/internal-developer-portal.md for the same trade argued from the SaaS side.
  • Self-hosted Backstage vs a commercial distribution -- Spotify Portal, Roadie and similar carry the upgrade burden and some plugin curation for a fee, while keeping the Backstage model and ecosystem. This is the middle option most build-vs-buy analyses omit entirely, and it is frequently the right answer for organizations that want Backstage's model without funding a platform team indefinitely. Price it explicitly rather than treating self-hosting as the only Backstage.
  • Discovery vs manual registration -- Automatic discovery over the Git org keeps the catalog current and surfaces new repositories without human action; manual registration gives tighter control over what appears and guarantees drift. Discovery is the default for any estate large enough to justify a portal. The corollary decision is what to do about repositories discovery finds that have no descriptor — report them as gaps, or ignore them.
  • Fixed kinds vs custom kinds and annotations -- Extending the model with custom kinds is possible and immediately costs ecosystem compatibility, since plugins expect the well-known kinds. Prefer annotations and spec.type values within the standard kinds; treat a genuine need for custom kinds as evidence worth re-examining the Port decision against.
  • Permission framework: policy in code vs OPA -- Implementing the permission policy directly is simpler for a small ruleset; delegating to OPA/Rego enables per-plugin authorization changes without a redeploy and matches an existing policy practice where one exists. The decision is about who changes authorization and how often, not about capability.
  • TechDocs adoption -- Docs-as-code rendered into the portal is a strong pattern and a second pipeline to own (generation, storage, freshness). Adopting it for a subset of services produces a portal where most docs tabs are empty, which reads as neglect. Decide whether it is org-wide or explicitly out of scope.
  • Upgrade cadence commitment -- Tracking the monthly release line keeps upgrades small and continuous; batching upgrades quarterly reduces interruption and compounds breaking changes across community plugins. Given that breaking changes land in minor versions and there is no LTS, continuous is materially cheaper — but only if the owning team's capacity is real.

AI and GenAI Capabilities

There is no single first-party AI layer in Backstage the way there is in the commercial portals; AI capability arrives through plugins, through the commercial distributions, or through whatever the organization builds against the catalog API. The architecturally interesting property is the same one that makes any well-maintained catalog valuable to an agent: it is grounded, structured context about the estate, and it is queryable. An organization intending to point agents at its catalog should evaluate that as a build item with its own data-handling review — what catalog content leaves the network, and to which model provider — rather than assuming it arrives with the platform. Treat vendor and plugin claims in this area as fast-moving and verify against current documentation.

See Also

  • providers/port/internal-developer-portal.md -- the SaaS side of this decision: blueprints, Ocean ingestion, scorecards, and the residency constraint that most often decides it
  • providers/servicenow/itsm.md -- the governed request catalog that overlaps on infrastructure requests
  • providers/vmware/aria-suite.md -- names Backstage as the build option against VCF Automation's packaged self-service
  • general/change-management.md -- where the change record lives when scaffolder templates and actions perform changes
  • general/local-development-environments.md -- the onboarding metric a portal is often bought to improve