Backstage demos beautifully. You get a software catalogue, tech docs, a scaffolder and a plugin ecosystem, and within a day you have something that looks like the developer portal in the conference talk.
Then nobody uses it. Not out of hostility, but because it does not yet do anything they could not do faster another way. This is the single most common failure mode we have seen, and it is not a technical one.
A catalogue of nothing useful is worse than no catalogue
The first instinct is to import every service into the catalogue so the portal looks populated. What you get is a directory of stale entries, most of which have an owner who left, and engineers learn within a week that the portal cannot be trusted.
Trust is the whole asset. Once an engineer has been wrong twice because the portal told them something out of date, you will not get them back cheaply. It is better to launch with twenty services that are unquestionably accurate than four hundred that are mostly right.
The way to keep it accurate is to make the catalogue a byproduct of something people already have to do, rather than a thing they must remember to update. If registration happens as part of provisioning, the entry exists because the service exists.
Ask what job the developer is hiring the portal to do
Nobody wants a portal. They want to answer a question, and right now they answer it by asking a person in chat. Those questions are your roadmap:
- Who owns this service, and who do I page at two in the morning?
- Where do I get a new environment, and how long will it take?
- Is this dependency safe to upgrade, and who else uses it?
- What is deployed in production right now, and which commit is it?
Pick the question people ask most and make the portal answer it better than chat does. One question answered properly buys you more adoption than a dozen half-finished plugins.
The scaffolder is the part that earns its keep
Everything else in a portal is reference material, and engineers are content to find reference material in a repository. The scaffolder is different, because it does something for them.
A portal that only tells you things is a wiki with a build step.
This is why the ordering we recommend puts provisioning before the portal. If the machinery underneath can already create a working service, the portal becomes the pleasant way to reach it. If the machinery does not exist, the portal is a form that files a ticket, and everyone can feel the difference.
Budget for it like a product, because it is one
Backstage is a React application that you will be maintaining. It has upgrades, dependencies, a plugin surface that drifts, and an authentication integration that breaks when your identity provider changes. None of this is unreasonable, but a team that adopted it expecting an install will be unpleasantly surprised at the first major version bump.
The teams we have seen succeed treated it as a product with a named owner, a backlog driven by developer complaints, and adoption metrics they actually looked at. The teams that struggled treated it as infrastructure that would sit still once configured.
How to tell whether it is working
Not visits. Visits go up when you send an email about it. Look for time to first deploy for a new service, what proportion of new services were created through the scaffolder rather than by copying an existing repository, and whether the questions the portal answers have stopped appearing in chat.
That last one is the real signal. A portal is working when it has quietly removed a category of interruption, not when it has a high monthly active user count.
