Backstage is the developer portal Spotify built and open-sourced: one place for every service, who owns it, its documentation and its pipelines. Its most powerful feature is also the least talked about: Software Templates.
A template turns "create a new service" into a form. Someone fills it in, and Backstage creates the repository, applies the organisation's standards and adds it to the catalog. No copying an old repo, no checklist to forget.
I built one: a golden path for new infrastructure repositories. Four fields in, and out comes a repository that is protected, documented and owned from its first commit, and checked by infradoctor, a GitHub Action I built and published on the Marketplace.
Here is what it looks like.
The template
The template is called Platform service. It asks four things: a name, an owner, an environment and a VPC range. Backstage does the rest. It creates the repository, sets it up and adds it to the catalog, and a few seconds later the new service is ready, with links to everything it created:
Configured, not just created
The new repository is not just created, it is configured. main is protected, so changes only go in through pull requests. The network check is required, so nothing merges until it passes. Merges are squash-only, and the repository is labelled with its environment and how it was created.
Every repository gets the same rules, and nobody sets them by hand:
A guardrail from the first commit
The required check is infradoctor, a GitHub Action I built and published on the Marketplace. It reads the Terraform in the repository and makes sure its VPC ranges do not overlap each other, or any range already used elsewhere in the company.
Overlapping networks are easy to create and painful to fix once they need to talk to each other.
The template adds the check, and the branch protection makes it required. So if someone changes a new service to a range another team already uses, the pull request cannot be merged:
And it says exactly why, so whoever opened the pull request knows what to change:
Nobody had to review the network by hand. The template added the check, the branch protection made it required, and the problem was caught before anything reached the cloud.
The catalog
Backstage keeps track of every service in the organisation. Any repository with a catalog file is picked up automatically, so new services appear in the portal without anyone registering them:
Each service has its own page: who owns it, what it depends on, and its latest pipeline runs, including the network check. Everything about a service in one place, without opening GitHub:
Documentation from day one
Every new service comes with documentation. It lives in the repository next to the code, so it changes in the same pull requests, and Backstage publishes it in the portal.
The same goes for the tools the platform provides. This is infradoctor's documentation, published from its own repository, with its owner and lifecycle right above it:
infradoctor
infradoctor started as a command-line tool and became a GitHub Action, now on the
Marketplace:
It reads the files platform teams already have and reports what needs fixing, before it is merged:
- Networks: VPC ranges in Terraform that overlap each other, or ranges used by other accounts and the office VPN, or Docker's default network. Overlaps that are intentional can be marked as such.
- Services: version drift and dependency problems across a service inventory.
- Logs and storage: error spikes in access logs, and artifact folders that keep growing.
Problems show up where people look: on the exact line of the pull request, in the run summary, and as a failed check that blocks the merge. Teams can choose whether warnings block too, or only errors.
In Backstage, infradoctor is a component like any other, with an owner, documentation and releases.
Every service created by the template declares that it depends on it, so the portal shows exactly which services rely on the check:
If infradoctor changes, the platform team knows who is affected before releasing it.
Why it matters
Standards that depend on people remembering them do not last. A checklist gets skipped, an old repo gets copied with its mistakes, and the gaps only show up when something breaks.
A golden path turns the standard into the default. The platform team defines it once, and every new service starts with it: protected, documented, owned and checked from its first commit. The easiest way to create a service is also the right way.
And because it all lives in Backstage, the platform team can see the result: every service, who owns it, how it was created, and which ones depend on the tools the team provides.
Links
- infradoctor: the GitHub Action, on the Marketplace
- platform-portal: the Backstage portal
- backstage-templates: the templates
Top comments (0)