A golden path competes for adoption. That framing is the whole article, and most of the ways these projects fail come from forgetting it.
The term comes from Spotify's engineering blog, where it described a supported and opinionated route through the company's tooling. The important word in the original framing is supported, not required. A team that takes the path gets a faster route to production and someone who maintains it. A team that goes around it gets to solve its own problems, which is sometimes the right call.
That means a golden path lives or dies the same way a product does. If the alternative is easier, teams take the alternative, and no amount of internal advocacy changes that arithmetic.
What a golden path is, and three things it gets confused with
Not a mandate
A path that needs a policy to get adoption has already lost the argument on merit. Mandates do work in the narrow sense that usage numbers go up, and they hide the signal you most need, which is whether the path is actually better than what teams would have chosen. When adoption is compulsory you can no longer tell.
The useful test is to ask what happens if you remove the requirement tomorrow. If the honest answer is that half the teams would leave, the path has a quality problem that the mandate was covering.
Not a wiki page
A document describing how to set up a new service is documentation. It goes stale within a quarter, because the steps drift and the page does not, and nothing forces anyone to notice. A golden path performs the steps. It takes parameters and produces a running service, which means it cannot silently drift: if it breaks, someone's provisioning breaks, and it gets fixed.
The forcing function is the whole difference. Usage is what keeps a path honest. The DORA research has been pointing at the same thing for years under documentation quality: what helps delivery is knowledge encoded in something that runs, rather than described in something that does not.
Not a run-once wizard
A generator that scaffolds a service and then has no further relationship with it solves the first hour and none of the following two years. The service it produced still needs pipeline updates when the base image changes, policy updates when a control is added, and dependency bumps when a library goes end of life.
We see this most clearly on the release side. When we built the delivery pipeline for Digital Health Outcomes' React Native app, the pipeline was not finished when it shipped. App Store and Google Play change their policies, and those changes break automated release flows. We still step in when they do. A path that is maintained like software carries that forward. A wizard hands you a snapshot and walks away.
The anatomy of a golden path
A golden path bundles several layers. The exact list varies by organisation, and the principle does not: every layer you leave out is a layer the developer assembles by hand, usually under time pressure and usually differently from the team next door.
Each missing layer becomes work that lands on the developer, and drift that lands on the platform team later.
Layer | What it provisions | What happens when it is missing |
|---|---|---|
Service scaffolding | Repository, skeleton, catalog registration, ownership metadata | Every service is laid out differently, and nobody can find who owns what |
Pipeline defaults | CI, container build, deploy configuration | Each team reinvents CI/CD slightly differently and none of them are maintained |
Infrastructure defaults | Database, queue, bucket, with sane sizing and backups | Provisioning goes back to a ticket, or to a script nobody owns |
Observability defaults | Metrics, logs, traces, a dashboard, alert routing | Services reach production unmonitored until an incident forces the work |
Policy | Resource limits, network policy, image provenance, secret delivery, RBAC | Controls are applied inconsistently and audited retroactively |
The point of the bundle is what arrives at the end of it. A new service reaches production with monitoring, CI/CD and guardrails already wired in, rather than bolted on later by whoever is on call when the gap is discovered.
Observability is the layer teams skip most often, and it is the most expensive omission. A service without a dashboard is invisible until it fails, and the work to add monitoring is always done at the worst possible moment.
How it actually executes
The template as code
A golden path is a template that takes parameters and runs a sequence of actions. The parameters are small in number and answerable by the person creating the service. Everything else is a decision the path has already made.
The last step matters more than it looks. When the path opens a pull request rather than pushing to main, the developer sees exactly what they are getting before it exists, and the platform team gets a reviewable artifact for every service ever created.
What comes out is a repository the developer can read end to end:
What the path emits into the delivery system
Scaffolding a repository is half of it. The other half is that the service starts reconciling without anyone doing anything else, which is a coordination job the reconciler owns rather than a script beside it, a distinction we drew in reconciliation versus delivery coordination in Argo CD. In a GitOps setup that means the path emits the delivery object too, keyed on the service it just created:
Two properties come from that object rather than from the template. prune: true means resources deleted from Git are deleted from the cluster, which is what makes teardown work later. selfHeal: true means a manual change in the cluster is reverted, which is what stops a service drifting away from the path it was generated on. Both are documented in the automated sync policy reference, and both are worth setting deliberately rather than inheriting.
The path must be inspectable
Developers do not adopt what they cannot read. A path that provisions a database through an opaque process is a path that gets abandoned the first time someone needs to know how that database is configured, because the fastest way to find out becomes going around the path entirely.
Inspectable means the template is in a repository the developer can read, the resources it produces are manifests they can look at, and the actions it takes are described somewhere other than in the head of the person who wrote it.
The strongest version of this is a client who no longer needs you. After we containerised the Node.js stack for Digital Health Outcomes and moved environment provisioning into Terraform and Helm on EKS, their team took full ownership of the infrastructure and has continued to evolve it without us. That outcome is only possible when nothing in the path is opaque.
Which tools, and why we do not prescribe them
The category of tool matters less than the property. Scaffolding tools such as Backstage Scaffolder or Cookiecutter generate the skeleton, infrastructure as code renders the resources, and a GitOps reconciler such as Argo CD applies them.
Our own engagements bear this out. For Greenstep we run Argo CD with Helm on managed Kubernetes, with GitHub Actions as the trigger. For Digital Health Outcomes we built provisioning on Terraform with Helm charts on AWS EKS. Same principles, different stacks, because the right combination depends on what the organisation already runs.
What a self-service action actually provisions
The gap between a portal and a platform is that a self-service action terminates in the thing you asked for rather than in a request for it. That is easy to state and specific to build, so here is one we built.
Greenstep's SaaS products shared a single staging environment. Showing a work-in-progress feature to a product manager meant waiting for a free slot, and one unfinished feature could hold up testing for everyone. Validation had become a queue.
The path we built gives every change request its own complete copy of the platform, provisioned in about fifteen minutes:
Its own database. A CloudNativePG cluster per environment, seeded from a synthetic copy of the test dataset so reviewers see realistic volumes rather than placeholder rows.
Its own file storage. Nothing shared, so no preview can read or overwrite another one's objects.
Its own mail handling. Outbound email is captured inside the environment and never delivered, so a preview cannot reach a real recipient.
Access control. Each preview is reachable only by authenticated Greenstep staff.
A lifetime tied to the review. The environment lives as long as the change request and is destroyed with the branch.
Four previews now run side by side with no contention, and there are no slots to wait for. The economics matter as much as the mechanics: previews run on Hetzner in the EU rather than on a hyperscaler, and they live for hours or days. The cost difference is what makes opening one for every idea a reasonable default rather than a privilege.
Every piece of that is a manifest keyed on the change request, which is why teardown is a cascade rather than a cleanup job. We wrote about that boundary in more depth in preview environments beyond a namespace per pull request.
Escape hatches decide adoption
The happy path gets the attention. The escape hatch decides whether teams stay.
Cover the common case
A path that tries to handle every case becomes a configuration language with worse ergonomics than the thing it wraps. Cover what most services need, and make the exit for the rest supported rather than shameful.
The failure to avoid is a path that handles ninety percent of a team's requirements and has no answer for the last ten, because that team now has to choose between the path and their actual requirement. They will choose the requirement, and you will have lost the ninety percent as well.
Fork or framework
Two shapes of escape hatch, with a real trade-off between them.
The exotic requirement is where the two diverge. One accommodates it and lets drift in, the other keeps consistency and pushes the requirement outside the model.
Template fork | Framework enforcement | |
|---|---|---|
How a team deviates | Takes the generated code and changes it | Extends within the framework's extension points |
Drift over time | Yes, and it accumulates silently | Minimal, the path stays the path |
Exotic requirements | Accommodated, the team is on its own afterwards | Fall outside the model entirely |
Upgrade story | Each fork upgrades itself, or does not | Central upgrades reach everyone |
Fits best | Heterogeneous estates, autonomous teams | Homogeneous estates, strong platform ownership |
Neither wins in general. What matters is knowing which one you chose, because the failure modes are different and so are the mitigations.
The mechanics of a fork that stays supportable
Deciding to allow forks is the easy half. The half that determines whether the estate is maintainable in two years is how a fork stays connected to the template it came from.
The minimum is a version marker in the generated repository, written at creation and never edited by hand:
That single file makes three otherwise impossible things possible. You can query the estate for which services are on which version. You can open an automated pull request against every repository below a given version when the template changes. And a developer looking at a service can tell whether its oddities are deliberate or simply old.
What you do with that marker is a policy choice, and it is worth writing down:
Additive template changes go out as automated pull requests to every service below the current version. The team reviews and merges on its own schedule.
Breaking template changes go out with a migration note and a deadline, and the platform team does the first three migrations itself rather than sending forty teams to read a changelog.
Deliberate divergence is recorded in the repository, so the next automated pull request does not try to undo it and the next engineer does not assume it was an accident. The same discipline applies to the secret layer, where one committed default plus a short exception list beats four half-adopted mechanisms, as we argued in secrets in GitOps.
A service more than two majors behind is a maintenance signal, not a violation. It usually means the path stopped fitting that team, which is information about the path.
Without the marker, none of this is available and the first breaking template change becomes an all-hands migration.
Progressive adoption
Existing services are the larger part of most estates, and a path designed only for new services quietly declares them out of scope. Partial adoption is worth supporting: a legacy service that takes the observability defaults and the policy layer, without the scaffolding it will never use, is a real improvement.
Scorecards that measure per layer rather than as a single pass or fail make this visible, and they give teams a route in that does not start with a rewrite. A usable scorecard is small enough to read in one screen:
Service | Scaffolding | Pipeline | Infra | Observability | Policy |
|---|---|---|---|---|---|
payments-api | on path 4.2 | on path 4.2 | on path 4.2 | on path 4.2 | on path 4.2 |
billing-worker | forked 3.1 | on path 4.2 | on path 4.2 | none | on path 4.2 |
legacy-reports | none | none | manual | dashboard only | partial |
notifications | on path 4.0 | on path 4.0 | on path 4.0 | on path 4.0 | on path 4.0 |
Read column by column rather than row by row. If the observability column is the emptiest one across the estate, that is a statement about your defaults rather than about four teams independently making the same mistake.
Day two: when the template changes and forty services already exist
Everything above describes creating a service. The harder problem, and the one most write-ups skip, is what happens on the four hundredth day, when the template has moved and the estate has not.
This is where paths quietly die. The template gains a new security control, forty repositories do not have it, nobody owns the migration, and within two quarters the generated services and the current template have nothing in common. At that point the path is documentation again.
Three things keep an estate current.
Know the distribution before you change anything. The version marker gives you a count per template version. If seventy percent of services are on the current major, a breaking change is a campaign. If seventy percent are two majors behind, the problem is not the change you are about to make.
Ship template changes the same way you ship code. Version the template, write a changelog entry a developer can act on, and open the pull requests automatically. A template change that arrives as a Slack message is a template change that reaches the teams who were paying attention that day.
Reconcile what the reconciler can reconcile. Anything the path emitted into the delivery system stays current on its own, because selfHeal reverts drift and prune removes what was deleted. Anything that lives only in the generated repository has to be migrated deliberately. Knowing which of your five layers falls in which category tells you how much day-two work you have signed up for.
The honest conclusion is that a golden path has a running cost, and organisations that do not budget for it get one good quarter and then a slow decline. Staffing that maintenance is the difference between a path and a project.
Why golden paths fail
When a path is not landing, it is usually one of four recognisable patterns. Each has a direct fix.
Failure | What it looks like | The fix |
|---|---|---|
Too rigid | Teams with slightly different needs go around it entirely | Build supported escape hatches so the path bends rather than breaks |
Unmaintained | The path falls behind the stack and generates services that need immediate fixing | Staff its maintenance as product work, not as a side task |
Opaque | Developers cannot see what it does, so they do not trust it | Make the template and its output readable, and keep the actions explicit |
Mandated | Adoption is high and satisfaction is low | Remove the mandate, find out why teams avoided it, and fix that instead |
The fourth is the one worth dwelling on. Compulsory adoption removes your only reliable feedback signal. When teams avoid a path, that avoidance is information about the path, and a policy that forces usage deletes the information without solving the underlying problem.
Measuring whether it worked
Voluntary adoption is the primary signal
The share of eligible new services that start on the path, measured when nothing compels them, is the number that tells you whether it is working. The direction matters more than the level: a path at forty percent and climbing is healthier than one at seventy and flat.
Being able to state that number at all is itself a maturity signal. A platform team that cannot say what its adoption rate is does not have a way to manage it. The CNCF platform engineering maturity model uses the same idea as its axis: measurement is what separates a platform being run as a product from one being run as a project.
Where the number comes from
Adoption is measurable without new tooling, from artifacts the path already produces:
Template run logs. Every execution, its parameters, whether it completed, and whether a human intervened. This is your success rate as well as your adoption count.
The version marker in each repository. A scan across the estate gives you both coverage and the version distribution you need for day-two planning.
Catalog entries created by the path versus catalog entries created by hand. The gap between them is the set of services that chose the dirt road.
Provisioning requests still reaching the platform team. Tagged by what was requested, this tells you which layer of the path is not doing its job.
None of these requires a survey, and all of them are harder to argue with than one.
The supporting metrics
Time to first deploy is the metric everyone reaches for, and it needs a caveat. A path is usually added on top of an architecture that already exists, so the comparison is rarely clean. If elapsed time comes out roughly the same, that is a legitimate result, and the question becomes what the path bought instead: manual steps removed, fewer hand-made decisions, more repeatable outcomes between teams.
When the before-and-after is clean, it is worth stating plainly. Provisioning an isolated client environment for Digital Health Outcomes took up to a full day of manual work before we automated it, and takes minutes afterwards from a single script. What changed was not only elapsed time. Every deployment became consistent regardless of where it ran, which is the property that let them onboard clients without growing their operations burden.
Self-service success rate is more direct. Of the runs a developer starts, how many complete without a platform engineer intervening? A path with a fifty percent success rate is a ticket queue with a nicer front end.
The drop in provisioning requests reaching the platform team is the one leadership understands, and it is honest as long as you check that the requests moved into self-service rather than into teams giving up and building their own.
Closing
Make the right way the easy way, then measure whether they take it. Both halves are required. A path nobody adopted is a project that shipped, and a mandate that produced adoption is a number that tells you nothing.
The practical starting point is narrower than most teams expect. Pick one path, the most common type of new service in the organisation, and make that route genuinely better end to end, including the observability and policy layers that are usually deferred. Emit a version marker from day one, because retrofitting one across forty repositories is the tax you pay for skipping it. Measure voluntary adoption on that one path for a quarter before adding a second.
If you are somewhere between a scaffolding tool and a real paved road, and not sure which part is holding adoption back, that gap is the work. It is what we spend a lot of our time on at Amoniac, and it is usually more tractable than it looks.
SHARE ON SOCIAL MEDIA
