Golden Paths and Service Scaffolding

A golden path is the supported, documented, automated way to do a common thing. Service scaffolding is its most visible expression: a new service starts with pipeline, observability, security, and deployment already wired up, so the correct configuration is the default rather than an achievement.

What a scaffolded service should include link

The test of a good template is that a new service is production-ready — not production-deployed, but structurally complete — on day one.

The ownership metadata file is small and carries disproportionate weight:

  apiVersion: catalog/v1
kind: Service
metadata:
  name: payments-api
  description: "Authorises and captures card payments"
spec:
  owner: team-payments
  lifecycle: production
  tier: 1                       # drives alert routing and review requirements
  oncall: payments-primary
  repository: https://github.com/example/payments-api
  runbook: https://docs.internal/runbooks/payments-api
  dependsOn: [ ledger-service, fraud-scoring, postgres-payments ]
  dataClassification: pci
  

This one file feeds incident routing, cost allocation, dependency graphs, compliance scoping, and the service catalogue. Making it mandatory at creation is far cheaper than reconstructing it later across an existing estate.

Templates are code, with all that implies link

flowchart TD
    A[Template repository] --> B[Versioned, reviewed, changelogged]
    B --> C[CI: generate a service from the template<br/>and run its full pipeline]
    C --> D{Generated service<br/>builds, tests, deploys?}
    D -->|No| E[Template is broken —<br/>block the change]
    D -->|Yes| F[Publish new template version]
    F --> G[Existing services notified<br/>of the available update]

Testing the template by generating from it and running the result end to end is non-negotiable. A broken template breaks every service created until someone notices, and the failures appear in the new team’s repository rather than in yours.

The day-two problem link

Scaffolding creates a long-lived obligation. A year after launch you have two hundred repositories generated from templates that have moved on eight versions, and no mechanism to bring them forward.

Three strategies, used together:

Reference rather than copy. Anything that can be a versioned reference should be. A pipeline that says uses: org/templates/go-service@v3 is updated by changing a version string; a pipeline copied inline must be edited in every repo.

flowchart LR
    subgraph "Copied"
    A1[Template v1] -.->|copy| A2[200 repos with<br/>200 divergent copies]
    A2 --> A3["Update = 200 pull requests<br/>written by hand"]
    end
    subgraph "Referenced"
    B1["Template v3<br/>(central, tested)"] <-->|"pinned reference"| B2[200 repos]
    B2 --> B3["Update = bump a version string,<br/>automatable"]
    end

Automated update pull requests. For what genuinely must be copied, run a bot that opens pull requests against every affected repository when the template changes. Teams review and merge on their own schedule; the platform team’s cost is one change, not two hundred.

Conformance checks, not enforcement. Continuously scan repositories against the current standard and publish the result as a scorecard — which services are on the current template, which lack ownership metadata, which have no runbook. Visibility drives voluntary convergence far better than a blocking gate, and it gives you an honest picture of the estate.

Designing the extension points link

Every template will meet a service that needs something different. Where that difference lands determines whether the template survives.

• Explicit extension points. A named place to add an extra pipeline stage or an extra manifest, which continues to work across template versions.
• Escape without a fork. A team should be able to opt out of one piece without abandoning the whole template.
• Forks are a signal, not a betrayal. When several teams fork for the same reason, that reason belongs in the template. Track forks as product feedback.

Making the path genuinely golden link

A template that produces a service nobody can run locally is not a golden path. Some concrete markers of one that works:

• One command to run locally. make dev or equivalent, with dependencies stubbed or containerised.
• A working example, not an empty skeleton. A generated service should have one real endpoint with a real test, so the team sees the intended pattern rather than inventing one.
• Documentation generated alongside the code, with the service’s own name in it. Generic docs get ignored.
• Fast time to first deploy. If a new service cannot reach a real environment on day one, teams will build up a large first change and lose the feedback advantage entirely.

Measuring whether it works link

The last row is the honest one. If the same setup question keeps arriving, the golden path has a gap — the answer belongs in the template, not in a reply.

Adoption checklist link

• Scaffolded services include pipeline, health endpoints, logging, metrics, tracing, scanning, and manifests by default.
• Ownership metadata is mandatory at creation and feeds the service catalogue.
• Templates are versioned and tested by generating and running a real service.
• Shared logic is referenced by version, not copied.
• A bot opens update pull requests for the parts that must be copied.
• A conformance scorecard shows which services are current.
• Extension points are explicit; forks are tracked as product feedback.
• A generated service runs locally with one command and deploys on day one.