A golden path is the supported route to creating a new service: a written procedure that produces a repository which already builds, deploys, is monitored and is governed — without anyone opening a ticket. It is the difference between a platform team that reviews pull requests and a platform team that provisions things for people, and the second one does not scale past about a dozen services.
This post is the mechanics: what the path has to contain, what the new-repository flow actually looks like when it is real, the guards that catch mistakes before a human reviews them, and the eighteen pitfalls that turn a two-hour task into a two-day one.
Why does a platform team become a ticket queue?
#Not because it is understaffed. Because of a structural fact: every new service needs things that live in accounts the service team cannot write to.
A deploy role in an automation account. A container registry in a shared artifacts account. A parameter in the landing zone. An environment protection rule. A network decision. If the only way to obtain any of those is to ask, then all of them become requests, and the requests arrive at one team.
The queue is the architecture working exactly as drawn. Adding engineers to it shortens the wait without changing the shape, which is why platform teams that hire their way out of the queue find themselves back in it a year later with a bigger salary bill.
The fix is not “say no more often”. It is to convert each request into a reviewable change: the service team opens a pull request against the platform repository, and a code owner approves it. The platform team still decides. It just decides in a diff, in minutes, instead of in a ticket, in days.
What does a golden path have to include?
#A template repository is not a golden path. A template gives you files. What teams get stuck on is everything that has to be true around the files.
| The path must provide | Why it is on the list | What happens without it |
|---|---|---|
| A repository layout with working examples | The first question is always “where does this go” | Every service invents a different structure, and nothing is reviewable across teams |
| A deploy identity, obtained by pull request | The service cannot create its own permissions | A ticket, then a broad role granted to make the ticket go away |
| A place for build artifacts | Images have to live somewhere the workload accounts can pull from | A registry per team, with inconsistent scanning and retention |
| Pipelines that already work | Copying a workflow from another repository copies its assumptions too | Five variants of the same pipeline, four of them subtly wrong |
| Environment protection with real reviewers | Production needs a gate that is not a convention | A gate that exists in a wiki |
| Secret delivery | Applications need configuration they must not hold | A secret in a pipeline variable, which nobody can rotate |
| Network and DNS by default | Reachability is not the service team’s specialty | Either an overly open security group or a week of debugging |
| Guards that fail fast | The document cannot anticipate everything | The reviewer becomes the guard, which does not scale and is unreliable |
| A verification checklist | “Done” needs a definition | Services that are 80 percent onboarded, permanently |
Everything above is a one-time decision that the platform team makes once and encodes. That is the entire economic argument for a golden path: the decisions do not get cheaper by being made repeatedly.
What does the new-repository flow actually look like?
#Here is the shape it takes in a real implementation — the AWS Enterprise Baseline and the BuiltForProd Blueprints — described as a worked example rather than as the only way to arrange it.
A new service is two repositories and three registrations. The infrastructure repository owns the service’s own cloud resources; the code repository owns the application and its delivery. The registrations are pull requests against the platform repository, reviewed by the code owners of the paths they touch.
The infrastructure repository, in order. Create the repository and copy the scaffolding from the smallest existing example — the guard scripts, the pre-commit configuration, the root and common configuration, and an ignore file that excludes the generated directories. Lay out modules, unit definitions, stack templates and per-environment folders. Write the stack template and the environment stage file. Set the state key prefix and the default tags in the root configuration and change nothing else, so the version pins stay as delivered. Fill in the common values: home region, namespace, account identifiers. Then register the deploy role in the platform repository — one map entry, which produces a role named after the repository. Set exactly one repository secret, the deploy role identifier. Copy the plan and apply workflows. Create the access groups. Run the first apply.
The code repository, in order. Choose the template that matches the runtime. Create the repository. Register a container registry entry in the platform repository — immutable tags, scan on push, a lifecycle policy, pullable from the workload accounts and pushable only from automation. Register a second deploy role scoped to that registry. Set the secrets and create the environments, with required reviewers on production and none on the earlier stages. Wire the workflow variables, which ship empty on purpose. Add the delivery configuration — for a Kubernetes service, a chart plus a per-stage values file that holds only the image reference. Add any public routing. Then run it: a pull request builds, tests and scans and pushes nothing; a merge pushes an image and opens a deploy pull request for development; a release promotes to staging; production is separate and gated.
Two properties of that flow matter more than the step count. Nothing in it is a request. And the first apply is the acceptance test — if the path is broken, it is broken before anybody depends on it.
What sits at the end of that flow depends on the runtime. For a containerized web service it is a cluster with a GitOps controller and an approval-gated promotion path, described in an EKS platform without a platform team; for a data workload it is a governed lake with tag-based access. The registrations are the same shape either way, which is the point of having a path rather than a runbook per team.
Guards catch what review cannot
#Code review is good at finding wrong code and bad at finding absent code. Nobody notices the missing tag, the dependency with no mock, the unit nobody references. So the conventions that the path depends on become scripts, and the scripts run both as pre-commit hooks and in the pipeline — so skipping the hook does not skip the check.
The Baseline runs six, and the useful thing about them is their provenance: each was written after its convention broke once.
| Guard | What it rejects | Why it exists |
|---|---|---|
| No hardcoded CIDRs | A private address range literal in configuration, outside comments, default routes and mocks | Addresses come from the address map, so a typed CIDR is an overlap waiting for a future region |
| Address map check | Malformed subnet keys, bad masks, subnets outside their VPC, overlapping VPCs | The map is the source of truth, and a broken map fails late and loudly |
| Mock completeness | A dependency with no mocks, or a mock missing an attribute the unit reads | Without complete mocks, a brand-new environment cannot be planned before it exists |
| Stack layout | A stage folder with no stack file, a checked-in configuration where one should be generated, a unit definition no stack references | Layout mistakes produce plans that are confusing rather than failing |
| Module version pins | A module whose version constraints do not match the root configuration | Unpinned providers turn a re-run into a different plan |
| Required inputs | A unit that does not supply a required variable of its module | Otherwise the failure surfaces partway through a multi-account apply |
If you take one thing from this section: the mock completeness guard is the one that protects the property everyone actually wants, which is planning an entire environment before it exists. Mocks use deliberately obvious sentinel values — account identifiers made of zeros, resource identifiers containing the word mock, addresses from a reserved range — so that if one ever reached a real plan, it would be unmistakable.
The eighteen pitfalls
#These are the mistakes that turn a two-hour onboarding into a two-day one. They are worth reading before your first service, not after.
| # | The pitfall | What you see | The fix |
|---|---|---|---|
| 1 | The generated directory is committed | Plans that make no sense and do not match the code | Ignore the generated and cache directories from the first commit |
| 2 | Running the tool from the repository root | The generator writes into your unit catalog | Run from the stage folder, and delete the stray generated tree |
| 3 | Editing a file inside the generated tree | The change disappears on the next run | Edit the definition or the template; the tree is output |
| 4 | Renaming a unit’s path | The next plan proposes to create everything again | The path is the state key. Choose it once; moving it is a deliberate state operation |
| 5 | Naming a module after its function | s3-data-lake cannot be reused for anything else | Name modules after the resource type: s3, lambda, eks |
| 6 | A relative source path in a template | The source does not exist when the template is evaluated | Anchor sources at the repository root; templates are copied before they are read |
| 7 | A unit definition no stack file references | Code that is never planned and slowly rots | The layout guard rejects it; keep it that way |
| 8 | Reading dependency outputs in locals | Empty values, or an error that blames the wrong thing | Locals are evaluated before dependencies. Outputs belong in inputs |
| 9 | A dependency with no mocks, or a partial mock | A new environment cannot be planned | Mock every attribute the unit reads. A partial mock is no better than none |
| 10 | Using the exclusion mechanism as a feature switch | Resources orphaned in the cloud with no code managing them | Excluded units are skipped by every command, including destroy. Use a module-level count toggle, so off means destroyed |
| 11 | Forgetting a shared definition is shared | A change lands somewhere nobody was looking | Plan every account and stage that references the definition |
| 12 | A workload role created without the exemption tag | Access denied, or an internal error, with nothing in the message naming the cause | Tag every role the policy expects to exempt, in the module that creates it |
| 13 | The deploy role secret has the wrong name | Federated sign-in fails on the first pipeline run | The name is exact. Copy it rather than typing it |
| 14 | Referencing a registry that does not exist yet | The platform plan fails on a lookup | Merge the registry registration first. Order matters between the two pull requests |
| 15 | A deploy role missing state access, or the wrong key prefix | Access denied on state, after everything else worked | Copy the existing role entry rather than composing a new one |
| 16 | A code deploy role without registry permissions | Push denied at the end of a green build | Scope the role to the registry when you create it, not after the first failure |
| 17 | The trusted-subject list replaced instead of extended | The role stops trusting the subjects it used to | Setting the list per role overrides the default. Include everything you still need |
| 18 | A job that declares an environment, restricted by branch | The subject presented is the environment, not the branch | Put the branch restriction in the environment’s own deployment branch policy |
Eleven of the eighteen are structural: a path, a name, an ordering. That is the pattern worth noticing. Golden paths fail on plumbing, not on judgment, which is exactly why they can be fixed by scripts and documentation rather than by seniority.
How do you know it is working?
#Three measures, and they should move together.
Time to first deploy, unaided. Hand the document to an engineer who has not seen it and time them. Do not help. The places they stop are the backlog.
Coverage. What share of live services were created through the path? A path used by a third of your services is a suggestion, and the other two thirds are where your incidents come from.
Ticket composition. Count platform requests that are provisioning or access, versus genuine design questions. The first category should shrink toward zero; the second is the work you actually wanted your platform team doing.
There is a fourth signal that is qualitative and reliable: whether people improvise. If teams are standing up their own registries and roles, the path is slower than going around it, and no policy will fix that.
Where to start, if you have a queue and no path
#- Read your last twenty platform tickets and sort them into provisioning, access and design. The first two categories are your path’s scope, already written by your users.
- Pick the single most common request and turn it into a pull request against a file, with code owners. One request type, converted, is worth more than a strategy.
- Write the procedure as you do it for the next service, in order, with the commands. Not a design document — a procedure someone can follow.
- Have someone else follow it without help. Fix what stops them.
- Turn the first thing they got wrong into a guard script. Then the second.
That loop, run for a quarter, produces a usable path. It is also the work that never gets prioritized, because the queue is always more urgent — which is the honest reason most platform teams stay queues. If it is the work your team does not have room for, it is the shape of work BuiltForProd Managed does through your own pull requests, and the BuiltForProd Baseline arrives with the path, the guards and the procedures already written and handed over with the repositories.