I spent years watching good developers lose whole days to work that had nothing to do with their feature. They needed a repo, a pipeline, a database, a dashboard. Each one meant a ticket, a wait, and a different answer depending on who picked it up. A platform fixes that. It turns the boring parts of shipping software into a paved road the developer walks alone, in minutes, without asking anyone. This lesson walks one new service down that road, hop by hop, and then shows what happens when the road does not exist, and what happens when there are twenty roads and nobody knows which one to take.
Difficulty: Advanced · Know this first: Lesson 33, Lesson 41
Every hop charges rent in minutes, not milliseconds. The bar below is a worked example for this lesson's scenario, not a measurement from a live system. The shape is the honest part: without a platform, one hop eats the whole budget, and that hop is waiting on a human. Step through the lesson or switch the scenario and watch the bar change.
The budget bar above shows three fixed stories. This simulator lets you write your own. Move a slider and watch the onboarding time, the ticket queue, and the platform team's month change. The numbers are a teaching example, not live measurements. The shape is the lesson: adoption is the lever, and the platform team pays for every point it loses.
How many product teams the platform serves. More teams means more requests, and more tickets when the golden path is not used.
Share of new services that start from the golden path template. The rest are built by hand or copied from an old repo, and each one becomes platform-team work.
Try this: (1) Set adoption to 100 and teams to 40. Onboarding is 150 minutes, tickets are 0, and the platform team gets its month back. (2) Set adoption to 0 and teams to 40. Onboarding is 1,200 minutes, tickets are 240 a month, and the platform team spends 180 hours a month answering them. Same platform, same teams. Only the adoption changed.
Three questions. No score is saved anywhere. This is just you against the material.
I do not measure a platform by how many services it created. I measure it by how many developers chose it when they could have gone around it. Adoption rate is the number. Time to first deploy is the second number. Ticket volume is the third. If adoption is high and time to first deploy is falling, the platform is working. If adoption is high because I banned the alternative, the number is a lie. Measure the voluntary choice, not the forced one.
The platform has users, and the users are developers. I treat them like users. I interview them, I watch them use the portal, and I keep a backlog ordered by their pain, not by my roadmap. A platform team that ships what developers did not ask for is a team building a product nobody ordered. The roadmap comes from the onboarding interviews and the ticket queue, in that order.
A paved road says here is the easy way, and it is fast. A guardrail says you cannot do this dangerous thing, and it stops you. Both matter, and confusing them is the common mistake. A paved road that blocks you is a gate with good marketing. A guardrail that only suggests is a comment nobody reads. I pave the common path and guard the dangerous edge, and I say out loud which one each rule is.
Sprawl starts with a good reason. One team needs a different base image, so someone copies the template and changes one line. Six months later there are twenty templates and nobody knows which one is current. The fix is not a rule against copying. The fix is making the template configurable, so the one difference becomes a parameter, not a fork. Every fork needs an owner and an expiry date, or it becomes permanent.
At 10x the teams, the portal holds and the template catalog breaks. I add search, ownership, and a freshness date on every template. The platform team stops answering tickets one by one and starts fixing the step that creates the tickets. At 100x, the platform is a service with SLOs: time to first deploy, scaffold success rate, and portal uptime. I run it like production, because by then it is production. If the portal is down on a Monday morning, two hundred developers are blocked, and that is an incident, not a backlog item.
# templates/service/template.yaml - the golden path for a web service
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: web-service
title: Web Service (golden path)
description: Repo, pipeline, deploy, and dashboard, wired together.
spec:
owner: platform-team
type: service
parameters:
- title: Service details
properties:
name:
title: Service name
type: string
pattern: ^[a-z][a-z0-9-]{2,30}$
owner:
title: Owning team
type: string
language:
title: Language
type: string
enum: [python, java, go]
steps:
- id: fetch
name: Scaffold from the template
action: fetch:template
input:
url: ./skeleton
values:
name: ${{ parameters.name }}
- id: policy
name: Check the guardrails
action: policy:check
input:
owner: ${{ parameters.owner }}
baseImage: allowed-list-v4
- id: publish
name: Create the repo and pipeline
action: publish:github
input:
repoUrl: org/${{ parameters.name }}
defaultBranch: main
output:
links:
- title: Open the service in the portal
url: ${{ steps.publish.output.repoUrl }}
What the snippet means: the template asks for three things and decides the rest. The name pattern stops bad names at the form, before anything is created. The policy step runs the guardrails and fails fast with a reason. The publish step creates the repo and the pipeline together, so a service can never exist without its pipeline. The owner field is required, because a service without an owner is a service nobody will page for.
A template update pinned a new base image version. The image tag looked right, but the image had never been pulled inside our network, and the registry mirror did not have it. Every new service scaffolded after that update failed its first build with an image pull error. Existing services kept running. Nobody noticed for four days, because the platform team watches running services, not new ones.
Three things. First, every template change now runs a test that scaffolds a fresh service and builds it end to end before the template ships. No test, no merge. Second, the scaffold success rate became a dashboard and an alert. If fresh scaffolds fail twice in an hour, the platform team gets paged, not a chat message. Third, the template versions are pinned and listed in the portal, so a developer can see exactly which version scaffolded their service and roll back to the last good one. The lesson I kept: the platform team was watching the services. Nobody was watching the front door.
Design an internal developer platform for an org with 60 teams and 300 services. Today every team scaffolds by copying an old repo, provisioning takes a week of tickets, and nobody knows who owns half the services. The platform team is four people. What do you build first, and what do you deliberately not build?
Start with the most common service kind and build one golden path for it only. If 200 of the 300 services are web services, one web service template covers two thirds of the org. Four platform engineers can own one template, one portal page, and the three guardrails that matter: owner, no secrets in the repo, allowed base image. Measure time to first deploy before and after. If it drops from a week to a day for that one kind, the platform has earned the right to a second template. Do not build ten templates. Do not build a custom portal. Use the catalog that exists and fix its data first.
One template buys focus and costs coverage; the teams with the odd service wait, and say so. Automating provisioning buys speed and costs control, so keep the guardrails and give up the manual review meeting. Naming owners buys accountability and costs political fights, so start with the services that page someone today. And four people cannot run a platform for sixty teams by answering tickets. Every ticket they answer is a step they did not fix, so the backlog is ordered by ticket volume, not by preference.