Enterprises often begin a platform-engineering programme by buying or building a developer portal. Six months later, the portal contains a service catalogue and a collection of links, but developers still wait for environments, copy deployment configurations and depend on platform specialists.
The problem is conceptual. A portal is an interaction and discovery layer. An internal developer platform is the productised set of capabilities that lets teams build, deploy and operate software through supported paths. Backstage can be a strong foundation for the portal and orchestration experience, but installing it does not create a platform.
The decision to adopt Backstage should follow a clear platform strategy, user research and ownership model. Otherwise, the organisation creates another interface that reflects existing fragmentation rather than removing it.
Define the three layers correctly
The developer portal is the front door. It helps engineers discover services, documentation, owners, templates, operational links and platform capabilities.
The internal developer platform is the underlying system of self-service APIs, workflows, infrastructure modules, delivery pipelines, identity controls, policies and observability integrations. It turns common engineering tasks into reliable products.
Platform engineering is the discipline and operating model used to design, build and evolve those products around developer needs.
These layers reinforce one another but are not interchangeable. A portal without platform capabilities becomes a catalogue. A platform without a coherent portal may expose excellent automation through fragmented interfaces. Platform engineering without product management can create technically impressive tools that teams do not adopt.
What Backstage provides
Backstage is an open-source framework for building developer portals. Its core concepts include a software catalogue, software templates, technical documentation and a plugin ecosystem.
The catalogue creates a common model for services, websites, libraries, resources, systems and owners. Software templates can initiate standard workflows such as creating a service repository with approved scaffolding. TechDocs supports a docs-like-code model. Plugins integrate delivery, monitoring, security and cloud tools into a common experience.
Backstage is deliberately a framework rather than a complete enterprise platform. The organisation must integrate identity, define catalogue governance, operate the application, curate plugins and connect templates to real automation.
This flexibility is valuable when the enterprise has differentiated workflows and engineering capacity. It is a cost when the organisation wants an immediately managed product.
What an internal developer platform must deliver
A useful platform reduces the cognitive load of building and operating software. It should provide paved roads for recurring tasks while preserving escape hatches for legitimate exceptions.
Capabilities often include:
- Service creation with repository, ownership and baseline controls
- Environment and infrastructure provisioning
- Standard CI/CD workflows
- Secrets and identity integration
- Observability and service-level configuration
- Security scanning and policy evidence
- Runtime deployment and rollback
- Cost and resource visibility
- Operational documentation and ownership
- Lifecycle actions such as upgrades and decommissioning
The portal can expose these capabilities, but the reliability, APIs and operating contracts belong to the platform beneath it.
Signals that an enterprise needs a developer portal
A portal becomes valuable when engineers cannot answer basic questions: Who owns this service? Where is its runbook? Which version is deployed? What dependencies does it have? Which template should a new team use?
It is also useful when developers jump across many tools to understand one service, or when audit and incident teams assemble ownership data manually.
A portal is less urgent in a small organisation where service ownership is obvious, tooling is consistent and teams communicate directly. Introducing Backstage too early can create more metadata maintenance than discovery value.
The threshold is not a specific number of developers. It is the degree of fragmentation, ownership ambiguity and repeated discovery work.
Signals that the platform—not the portal—is the priority
If developers know what they need but cannot obtain it without tickets and specialist intervention, the primary problem is platform capability.
Long environment lead times, inconsistent pipelines, repeated cloud configuration, fragile deployment procedures and manual security approvals require automation and productised workflows. A prettier catalogue will not resolve them.
Prioritise the highest-friction developer journeys. Build or improve the underlying capability, expose it through a stable API or workflow, and then make it discoverable in the portal.
When Backstage is a strong fit
Backstage fits enterprises that want an extensible portal, have multiple engineering tools and need a common software catalogue. It is particularly attractive when teams can maintain a TypeScript application and need to customise workflows, entity models and integrations.
It also suits organisations willing to treat the portal as a product. That means a dedicated owner, user research, reliability objectives, an upgrade budget, plugin governance and measurable adoption goals.
Backstage can be powerful in regulated environments because catalogue metadata and templates can expose ownership and approved paths. However, governance must be designed; the framework does not automatically make metadata complete or evidence trustworthy.
When a managed portal may be better
A managed internal developer portal can be a better choice when speed, predictable operations and built-in integrations matter more than deep customisation. It can reduce the burden of upgrades, hosting and plugin compatibility.
Evaluate managed products based on data model flexibility, workflow integration, access controls, portability, API coverage and exit options. A fast implementation that locks critical platform workflows into proprietary automation may create future switching cost.
Run the buying decision against user journeys, not screenshots. Ask vendors to demonstrate how a service is created, governed, operated and retired in your environment.
Backstage is not a workflow engine by default
Software Templates can collect inputs and trigger actions, but complex long-running processes require careful orchestration, state handling, approvals, retries and auditability.
Do not bury critical business logic in a chain of portal actions without a durable workflow system. Use the portal to initiate and show workflow status while purpose-built automation or orchestration executes the process.
This separation improves reliability and allows the same platform capability to be used through CLI, API, automation and portal interfaces.
Design the software catalogue as a governed data product
A catalogue loses trust when services are duplicated, owners are stale and lifecycle fields are optional. Define authoritative sources for ownership, repositories, deployment environments, criticality and dependencies.
Automate ingestion where possible. Validate entity definitions in delivery pipelines. Assign responsibility for metadata quality and establish rules for archived or orphaned services.
Do not centralise every field in Backstage if another system is authoritative. The catalogue should aggregate and link reliable data, not become a manually maintained shadow database.
Build golden paths with escape hatches
A golden path should be the fastest way to meet common security, reliability and operational standards. It should generate more than a repository skeleton. A mature path may provision environments, register ownership, connect telemetry, configure delivery and create baseline documentation.
Keep templates opinionated but composable. Separate organisation-wide controls from language or runtime choices. Version templates and define how existing services receive improvements; otherwise, only newly generated projects benefit.
Escape hatches need explicit ownership and review. Teams should be able to depart from the path when the product requires it, but exceptions should not silently become unsupported permanent platforms.
Security and permission architecture
Integrate the portal with enterprise identity and define permissions around entities, actions and sensitive data. Catalogue visibility, deployment actions and production diagnostics may require different access models.
Treat plugins as software supply-chain dependencies. Review maintenance, privileges, backend integrations and data exposure. Store secrets outside configuration repositories and scope service credentials narrowly.
For high-impact actions, use approval, policy and audit controls in the underlying platform. The portal should not become an ungoverned administrative console merely because it offers a unified interface.
Measure adoption and impact
Portal page views are insufficient. Measure whether developers complete important tasks successfully and whether the platform changes delivery outcomes.
Useful measures include time to create a production-ready service, percentage of services with valid ownership, task completion rate, golden-path adoption, workflow failure rate, onboarding time, developer satisfaction and support-ticket reduction.
Combine these with delivery and reliability measures. A platform that attracts users but produces unstable services has not succeeded. A technically sound platform that teams avoid has also not succeeded.
A phased adoption roadmap
Phase one should focus on discovery: catalogue a bounded set of services, establish ownership and integrate documentation and operational links.
Phase two should expose two or three high-value workflows such as service creation, environment provisioning or production readiness checks. Build these on stable platform APIs and test them with pilot teams.
Phase three should expand golden paths, introduce scorecards and lifecycle management, and improve policy evidence. Retire redundant interfaces only after teams have a reliable replacement.
Throughout the programme, run developer research, publish platform service levels and maintain a visible backlog based on friction rather than stakeholder volume.
Cost categories leaders underestimate
Open source does not mean zero cost. Budget for hosting, upgrades, plugin maintenance, schema design, integration work, support and user research. Backstage also creates organisational costs: platform ownership, metadata governance and change management.
Compare total cost against the recurring time lost to discovery, manual provisioning, duplicated templates and inconsistent controls. The business case should focus on reduced friction and risk, not licence cost alone.
Decision checklist
Adopt Backstage when the organisation needs a customisable portal, can own its lifecycle, has a catalogue problem and intends to connect the portal to genuine platform capabilities.
Delay or choose a managed option when there is no dedicated owner, the platform APIs do not exist, rapid implementation is essential or customisation is not strategically valuable.
Do not proceed until leaders can answer:
- Which developer journeys will improve first?
- What systems remain authoritative?
- Who owns the portal as a product?
- Which workflows exist beneath the interface?
- How will adoption and task success be measured?
- What is the plugin and upgrade governance model?
- What can teams do when the golden path does not fit?
Final recommendation
Treat the portal as a front door and the internal developer platform as the building. Backstage can organise discovery, templates and integrations, but it cannot substitute for reliable self-service capabilities or a platform product team.
Start with developer problems, build the underlying paved roads and introduce Backstage where a unified, extensible experience will reduce measurable friction. The successful outcome is not a populated catalogue. It is an engineering system in which teams can find, create, change and operate software safely with less cognitive load.
Sources and further reading
Backstage documentation
Backstage Software Catalog
Backstage Software Templates
DORA platform engineering guidance
Reference operating model
Create a portal product team responsible for experience, catalogue and integrations, and platform capability teams responsible for provisioning, delivery, runtime and observability products. A platform product leader coordinates priorities across the experience and capability layers.
Establish office hours and user research, but do not make office hours the normal fulfilment path. Support interactions should feed product backlog and documentation. Publish service levels for platform workflows and the portal itself.
Backstage implementation architecture
Operate Backstage as a production application with separate development and production environments, automated upgrades, dependency scanning, database backup and observability. Integrate enterprise authentication and map identities to catalogue ownership.
Keep custom plugins small and purposeful. Place reusable orchestration in external services so workflows remain accessible through APIs and automation. Use a curated plugin allow-list, maintainers and upgrade tests. Instrument template steps so failures can be located without exposing secrets.
Catalogue migration approach
Begin with one domain and ingest repositories automatically. Reconcile generated entities with team ownership, then establish validation rules. Avoid asking every team to manually populate dozens of fields before the catalogue demonstrates value.
Introduce required fields gradually: owner, lifecycle, system, criticality and documentation. Create an orphan queue for unresolved services. Link catalogue quality to operational workflows—for example, a production deployment may require valid ownership—only after the metadata process is reliable.
Business case example
Suppose two hundred engineers each lose one hour per week finding ownership, creating standard infrastructure or navigating delivery tools. The theoretical recovered time is useful but should not be presented as guaranteed cash savings.
Build the case around reduced onboarding time, fewer manual tickets, higher deployment success, faster incident routing and consistent control evidence. Track adoption and realised workflow improvement. The most credible platform business case combines developer time, operational risk and speed of product change.
