Platform Engineering & Developer Experience

Golden Paths & Templates

18 min Lesson 4 of 28

Golden Paths & Templates

Spotify coined the term golden path, but every mature platform engineering team has independently discovered the same idea: the fastest way to improve the developer experience at scale is to make the right way the easy way. A golden path is an opinionated, fully-integrated workflow for building and shipping a service — with CI/CD, observability, secrets handling, networking, and compliance baked in — that a developer can bootstrap in minutes without knowing how any of it works internally. This lesson is about building that scaffolding in production, at big-tech scale.

What a Golden Path Actually Provides

A golden path is not a README with instructions. It is a machine-executable workflow that stamps out a production-ready service skeleton. When a developer runs the path, they get:

A source repository with branch protection, code owners, and security scanning pre-configured.
A CI pipeline that runs tests, lints, builds a container image, signs it, and pushes to the internal registry.
A CD pipeline (typically Argo CD or Flux) that deploys to staging automatically and requires a manual gate for production.
Kubernetes manifests or Helm charts with resource limits, liveness and readiness probes, pod disruption budgets, and network policies already set to platform defaults.
A Datadog (or Prometheus/Grafana) dashboard pre-populated with the four golden signals for the service.
A Vault or AWS Secrets Manager path for the service with least-privilege IAM already attached.
An entry in the internal service catalog (Backstage or equivalent) with ownership metadata filled in.

The developer inputs a service name, a team name, and a language/framework choice. The platform emits a working production service. That is the contract.

The golden path is opinionated by design. Every option you expose is a decision you are delegating to the developer — and a support burden you are accepting. Big-tech platform teams keep the path narrow: one blessed container base image per language, one logging library, one secrets client. You offer escape hatches for the 5% of cases that genuinely need them, but the path does not surface them upfront.

Scaffolding with Cookiecutter and Backstage Software Templates

Two tools dominate golden path scaffolding in 2025: Cookiecutter (Python-based, CLI-driven, Git-native) and Backstage Software Templates (UI-driven, integrates with the service catalog). Most large organizations use both: Backstage for the developer-facing golden path UI, Cookiecutter or a similar engine under the hood.

A Cookiecutter template is a directory tree with {{cookiecutter.variable}} placeholders. The template ships with a cookiecutter.json that declares variables and their defaults, and a hooks/ directory for post-generation scripts.

# cookiecutter.json — defines the inputs for a Go microservice golden path template
{
  "service_name": "my-service",
  "team_name": "platform",
  "language": ["go", "python", "java", "typescript"],
  "database": ["none", "postgres", "mysql", "dynamodb"],
  "cache": ["none", "redis", "memcached"],
  "expose_http": true,
  "enable_grpc": false,
  "aws_region": "us-east-1",
  "k8s_namespace": "{{cookiecutter.team_name}}-services",
  "initial_cpu_request": "100m",
  "initial_memory_request": "256Mi"
}

# Template directory layout:
# {{cookiecutter.service_name}}/
#   .github/
#     workflows/
#       ci.yml        <-- pre-wired CI pipeline
#       release.yml   <-- image build + sign + push
#   k8s/
#     deployment.yaml
#     service.yaml
#     hpa.yaml
#     network-policy.yaml
#   src/              <-- language-specific boilerplate
#   Dockerfile
#   Makefile          <-- make build / make test / make local
#   .golangci.yml     <-- linter config (if Go)
#   catalog-info.yaml <-- Backstage entity descriptor

# Invoke from CLI:
cookiecutter https://github.com/your-org/service-template.git \
  --no-input \
  service_name=payment-processor \
  team_name=fintech \
  language=go \
  database=postgres

The hooks/post_gen_project.sh script runs after the directory is created. This is where the real magic happens: the hook calls your platform APIs to wire everything up.

#!/usr/bin/env bash
# hooks/post_gen_project.sh — runs after cookiecutter generates the tree

set -euo pipefail

SERVICE="{{ cookiecutter.service_name }}"
TEAM="{{ cookiecutter.team_name }}"
NAMESPACE="{{ cookiecutter.k8s_namespace }}"
REGION="{{ cookiecutter.aws_region }}"

echo "[golden-path] Creating GitHub repository..."
gh repo create "your-org/${SERVICE}" \
  --private \
  --template your-org/service-template-empty \
  --confirm

echo "[golden-path] Initializing branch protection..."
gh api repos/your-org/${SERVICE}/branches/main/protection \
  --method PUT \
  --field required_status_checks='{"strict":true,"contexts":["ci/test","ci/lint","security/trivy"]}' \
  --field enforce_admins=true \
  --field required_pull_request_reviews='{"required_approving_review_count":1}'

echo "[golden-path] Pushing scaffold to ${SERVICE}..."
git init && git add . && git commit -m "chore: initial scaffold from golden path"
git remote add origin git@github.com:your-org/${SERVICE}.git
git push -u origin main

echo "[golden-path] Creating Vault path for secrets..."
vault kv enable-secrets-engine -path="secret/${TEAM}/${SERVICE}" || true
vault policy write "${SERVICE}" - <<EOF
path "secret/data/${TEAM}/${SERVICE}/*" { capabilities = ["read"] }
EOF

echo "[golden-path] Registering service in Backstage catalog..."
curl -sf -X POST https://backstage.internal/api/catalog/entities \
  -H "Authorization: Bearer ${BACKSTAGE_TOKEN}" \
  -H "Content-Type: application/yaml" \
  --data-binary @catalog-info.yaml

echo "[golden-path] Done. Service ${SERVICE} is ready."
echo "  Repo:      https://github.com/your-org/${SERVICE}"
echo "  Namespace: ${NAMESPACE}"
echo "  Dashboard: https://grafana.internal/d/${SERVICE}"

The golden path turns 2–5 days of manual platform setup into a sub-10-minute scaffolding step, with every platform concern handled automatically.

Backstage Software Templates: The UI Layer

Backstage Software Templates (the scaffolder plugin) expose golden paths through a guided form UI. A template is a YAML file registered in the catalog. The parameters section defines the form; the steps section defines what runs. Steps are built-in actions (fetch:template, publish:github, catalog:register) plus custom actions you write for your platform's APIs.

# catalog-info.yaml — Backstage Software Template for a Go microservice
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: go-microservice
  title: Go Microservice (Golden Path)
  description: Production-ready Go service with CI/CD, observability, and secrets management
  tags: [go, golden-path, recommended]
spec:
  owner: platform-engineering
  type: service
  parameters:
    - title: Service Details
      required: [serviceName, teamName]
      properties:
        serviceName:
          title: Service Name
          type: string
          pattern: '^[a-z][a-z0-9-]{2,39}$'
          description: Lowercase, hyphen-separated, 3-40 chars
        teamName:
          title: Owning Team
          type: string
          ui:field: OwnerPicker
          ui:options:
            allowedKinds: [Group]
        database:
          title: Database
          type: string
          default: none
          enum: [none, postgres, dynamodb]
        enableGrpc:
          title: Enable gRPC server
          type: boolean
          default: false

  steps:
    - id: fetch-base
      name: Render template
      action: fetch:template
      input:
        url: ./skeleton
        values:
          serviceName: ${{ parameters.serviceName }}
          teamName: ${{ parameters.teamName }}
          database: ${{ parameters.database }}

    - id: publish
      name: Create GitHub repository
      action: publish:github
      input:
        allowedHosts: [github.com]
        repoUrl: github.com?owner=your-org&repo=${{ parameters.serviceName }}
        defaultBranch: main
        requireCodeOwnerReviews: true
        repoVisibility: private

    - id: register
      name: Register in Backstage catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps.publish.output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

    - id: vault-setup
      name: Create Vault secret path
      action: http:backstage:request
      input:
        method: POST
        path: /api/proxy/vault/v1/sys/mounts/secret/${{ parameters.teamName }}/${{ parameters.serviceName }}

  output:
    links:
      - title: Repository
        url: ${{ steps.publish.output.remoteUrl }}
      - title: Open in catalog
        entityRef: ${{ steps.register.output.entityRef }}

Template Versioning and the Drift Problem

Templates age. A golden path scaffolded 18 months ago emits services using an older base image, an outdated CI action version, and a deprecated liveness probe API. After a year, a large org might have 200 services, half of which are running stale templates. This is the template drift problem and it is the most common golden path failure mode in production.

Platform teams at scale address drift with three mechanisms:

Version tags in catalog-info.yaml: Tag every generated service with the template version used (backstage.io/template: go-microservice@v1.4.2). The catalog then lets you query "how many services are on template version older than v1.3.0?"
Renovate or Dependabot on template outputs: Configure Renovate to open PRs in all generated repos when the base image, GitHub Actions version, or Helm chart dependency is updated. This automates the mechanical parts of keeping services current.
Breaking change migration scripts: When a template change is not backward-compatible (e.g., migrating from Helm 2 to Helm 3 manifests), ship a migration script alongside the new template version. Document it clearly in your internal changelog. Give teams a deprecation window (typically 90 days) before the old template version is retired.

Treat your golden path as a product with a changelog. Publish a human-readable changelog for every template version. State what changed, why, and what teams need to do (or don't need to do — "Renovate handles this automatically"). Platform teams that treat templates as a fire-and-forget artifact end up with a museum of divergent services that no one trusts to be current.

Guard-railing Without Blocking: Policy in the Path

A golden path naturally enforces policies — but enforcement must be invisible when the developer is doing the right thing and clear when they are not. The wrong approach is to validate inputs with a hand-written shell script that fails with cryptic error messages. The right approach is schema-driven validation with Backstage's JSON Schema form validation (which gives live feedback as the developer types), combined with OPA/Conftest checks in CI that fail fast with actionable messages.

Three policies every golden path should enforce at scaffold time:

Naming conventions: Service names must match your org's pattern. Non-conforming names break Datadog tagging, Vault paths, and RBAC roles — catching this at scaffold time prevents downstream breakage.
Team ownership is mandatory: A service with no owning team is a support black hole. The template's teamName field must resolve to a real team in the catalog; the Backstage OwnerPicker widget enforces this with a dropdown, not free text.
Resource requests and limits are never zero: The template's Kubernetes manifests must include non-zero CPU and memory requests. Inject sane defaults (100m CPU / 256Mi memory for a typical API service) and document how to tune them, but never scaffold a service with unlimited resource requests — it will Noisy-Neighbor its namespace.

Do not put compliance gates only at deploy time. A common mistake is to run OPA/Gatekeeper admission webhooks in Kubernetes but have no policy enforcement in the scaffolder. This means developers build a service for two days, push to staging, and then get a wall of policy failures they cannot easily interpret. Fail fast: validate in the form UI, in the CI pipeline, and in admission control — catching the earliest possible violation at each layer.

Production Failure Modes

Golden paths fail in predictable ways at large organizations. Knowing these in advance lets you architect around them:

The "happy path only" template: A template that only handles the straightforward case breaks the first time a team needs a non-default database or a monorepo structure. Design for the common cases but document the escape hatches clearly in the template description. Power users need to know when to stop using the golden path and what to do instead.
Hook failures are silent: Post-generation hooks that call platform APIs can fail silently if the API is down or returns an unexpected response. Every hook must check exit codes and emit clear error messages. Partial scaffolding (repository created but Vault path missing) is harder to debug than a clean failure.
Template sprawl: Organizations with multiple platform teams end up with 20+ overlapping templates. Developers spend more time choosing a template than they would have spent setting up manually. Curate ruthlessly: one golden path per language/runtime type, clearly labeled "recommended," with alternatives only when the use case genuinely differs.
Stale base images: A template that bakes in a specific base image tag (golang:1.22 instead of golang:1.22-alpine) will drift. Pin digests in templates that ship to production; use Renovate to update them. A CVE in a base image that is in 300 scaffolded services is a coordinated remediation effort — automate the update path from day one.

Golden paths are the highest-leverage investment a platform team can make in the first year. Every minute a developer does not spend reading Confluence pages about "how to configure branch protection" is a minute they spend building product. At Spotify, the golden path reduced the median time-to-first-production-deploy from 2 weeks to half a day. That compresses across every new service, every new hire, and every team migration — and the platform team that built it is free to work on the next layer of the platform.