Paved Roads and Golden Paths

What it is

A golden path (or paved road) is a pre-built, platform-supported workflow for a common software engineering task. Where a blank-canvas approach gives developers access to raw tools and requires them to configure everything themselves, a golden path provides a curated, tested, documented, end-to-end workflow that works without configuration. The most common examples: a Backstage Software Template that scaffolds a new microservice (creates the GitHub repo, adds a standard project structure, sets up CI/CD, registers the service in the catalog, provisions a Kubernetes namespace and default observability), and shared CI/CD pipeline templates (reusable GitHub Actions workflows that implement the standard build → test → scan → publish → deploy flow for each supported language stack, with no per-team configuration).

The critical design principle distinguishing a golden path from a mandate is the presence of escape hatches — documented mechanisms for teams to deviate from the golden path when they have legitimate, specialised requirements. Netflix's famous "paved road" framing explicitly addresses this: the paved road is the supported, fast path; teams are free to go off-road, but they accept responsibility for the unpaved terrain (no platform team support, no compliance guarantees, no cost tooling integration). This model creates positive incentives for golden path adoption without creating resentment through forced standardisation.

Why it exists

Without golden paths, every team independently solves the same problems: setting up a CI pipeline, configuring Kubernetes manifests, adding linting and security scanning to their build. Across 20 teams, this represents 20 different CI configurations, 20 different approaches to image building, and 20 different levels of security scanning coverage. The result is organisational entropy: inconsistent security posture (some teams run SAST, others don't), inconsistent operational practices (some teams have runbooks, others don't), and massive duplication of effort. Golden paths solve this by solving the problem once, correctly, and making the correct solution so frictionless that teams adopt it voluntarily.

The economics are compelling: a platform team that invests 3 engineer-weeks building a golden path for Python microservices saves 3 engineer-weeks across every team that subsequently creates a Python microservice using the template. With 10 new services per year across 8 teams, the investment pays back within a quarter and compounds indefinitely. Additionally, golden paths created by the platform team encode hard-won knowledge about cloud-specific pitfalls, security configurations, and operational requirements that most application teams lack — the template is not just a time saver but a quality accelerator.

When to use

• Create a golden path for any workflow performed by 3+ teams more than 2–3 times per year — the amortisation math makes investment worthwhile.
• Use Backstage Software Templates for new service creation workflows — templates run interactively (developer fills in service name, team, type) and generate a complete repository from a cookiecutter-style template.
• Use shared GitHub Actions reusable workflows (uses: org/platform/.github/workflows/python-build.yml@v2) for CI pipeline golden paths — all teams get updated automatically when the platform team improves the shared workflow.
• Create language/framework-specific golden paths for the 3–4 most common technology stacks (Python, Java, Node.js, Go) rather than one generic golden path that works poorly for all.
• Define "mandated" vs "recommended" golden path tiers clearly: some standards (image scanning, SBOM generation) must be in every CI pipeline; others (specific linters, test frameworks) are recommended but teams may substitute alternatives.

When not to use

• Over-prescribing the golden path: Including opinionated choices about application architecture, ORM libraries, or API framework in a golden path goes beyond the platform team's remit and creates resistance from teams with different technical preferences.
• No escape hatch: If the golden path is the only permitted workflow, it becomes a bottleneck; teams with specialised requirements (ML pipelines, data engineering, mobile apps) cannot use standard golden paths and need explicit exemption processes.
• Stale golden paths: A golden path that is two major versions behind (e.g., still scaffolding Python 3.9 in 2025) is worse than no golden path — teams distrust and bypass it; golden paths require active maintenance with a designated owner.
• Building before understanding: A golden path built without observing how developers currently work often misses critical steps or includes unnecessary complexity; shadow developers creating a new service before building the template.

Typical architecture

Golden Path: New Python Microservice
──────────────────────────────────────────────────────────
  1. Developer opens Backstage → Software Templates
     └── Selects "Python REST API Service"
     └── Fills in: service-name, team, description, tier

  2. Backstage Software Template runs (Nunjucks + actions)
     ├── Creates GitHub repo: org/service-name
     │   ├── src/                 (FastAPI skeleton)
     │   ├── tests/               (pytest setup)
     │   ├── Dockerfile           (distroless base image)
     │   ├── .devcontainer/       (devcontainer config)
     │   ├── .github/workflows/
     │   │   └── ci.yml → uses: org/platform/.github/
     │   │                   workflows/python-service.yml@v3
     │   └── catalog-info.yaml   (registers in Backstage)
     ├── Provisions Kubernetes namespace: service-name
     │   └── (via PostgresDatabase CRD if selected)
     ├── Registers service in PagerDuty (via API action)
     └── Creates default Grafana dashboard (via template)

  3. Developer clones repo, opens in devcontainer
     └── Local environment ready in <5 minutes

  Shared CI Pipeline (python-service.yml@v3)
  ├── lint       (ruff, mypy)       [always]
  ├── test       (pytest + coverage) [always]
  ├── sast       (semgrep)           [always, mandated]
  ├── sca        (pip-audit)         [always, mandated]
  ├── build      (docker buildx)     [on main + PR]
  ├── sbom       (syft)              [on main, mandated]
  ├── sign       (cosign)            [on main, mandated]
  └── deploy     (ArgoCD image tag)  [on main]

Pros and cons

Implementation notes

Design golden paths iteratively by shadowing developers through the current workflow, timing each step, and identifying friction points. A 30-minute shadowing session is worth weeks of speculative design. Build the template to address the top 3–5 friction points and validate with 2–3 volunteer teams before broad rollout. For Backstage Software Templates: use the built-in fetch:template action to copy scaffolding files (with Nunjucks variable substitution), the publish:github action to create the repo, and custom actions (written in TypeScript) for API integrations (Kubernetes namespace creation, PagerDuty team registration). Pin template versions using GitHub tags so teams can choose when to upgrade their generated services.

For measuring golden path adoption: track the percentage of new services created via golden path templates (vs created manually) each quarter. Use Backstage analytics (golden path template usage metrics) or GitHub insights (repo count with standard CI workflow) to measure this. Target 80%+ adoption for the primary supported stacks within 6 months. For the remaining 20% (off-path), track the reasons: legitimate niche stack, team preference, or missing golden path features. Use this data to prioritise golden path improvements. Define a clear "off-path registration" process so that teams who legitimately go off-path are still known to the platform team (registered in catalog, security posture reviewed).

Common failure modes

• Golden path stagnation: Platform team creates a Python service template, ships it, and moves on; 18 months later the template generates Python 3.10, uses a deprecated FastAPI pattern, and references a Docker base image with 40 CVEs; developer trust drops and teams stop using templates; appoint a template owner and schedule quarterly reviews.
• Mandate without quality: Engineering leadership mandates all new services use the golden path; the golden path is poorly documented and breaks on Edge cases; teams comply but resentfully, filing bugs, and the platform team drowns in support tickets; earn adoption through quality, not mandates.
• Shared CI workflow breaking change: Platform team updates shared workflow to change a runner label; all 60 consuming services break simultaneously; PR review process fails to catch the scope of impact; use semantic versioning for shared workflows and maintain N-1 compatibility in minor versions.
• Template sprawl: Every team contributes their own Backstage template; catalog fills with 40 templates, 30 of which are unmaintained; developers cannot find the authoritative template; limit template creation to the platform team (with a community contribution process), and prominently mark official vs community templates.
• Escape hatch becomes the default: The off-path process is as easy as opening a Jira ticket; most teams use it to avoid the golden path; the paved road has no traffic; raise the bar for escape hatch approval (requires architecture review) and investigate root causes of escape hatch usage.

Decision checklist

• Is each golden path template owned by a named platform team member who reviews and updates it quarterly?
• Does the golden path include escape hatches with a documented, non-onerous process for legitimate off-path use?
• Is golden path adoption rate (% of new services using templates) tracked monthly and used to prioritise improvements?
• Are shared CI pipeline workflows semantically versioned with a deprecation policy for old versions?
• Does the golden path embed mandated security controls (image scanning, SBOM, signing) that cannot be bypassed even on the paved road?
• Have at least 2–3 volunteer teams validated each new golden path before broad rollout?

Example use cases

• Accelerating new service launch: E-commerce company creates Backstage templates for REST API, event consumer, and cron job service types; 12 teams use templates to create 40 new services in a year; average time from "start new service" to first production deploy drops from 8 days to 4 hours; CI pipeline setup time eliminated.
• Embedding security compliance: FinTech with PCI-DSS requirements adds mandatory SAST, SCA, SBOM generation, and image signing to the shared CI pipeline template; 100% of services built on the golden path are automatically compliant; compliance audit scope reduced as evidence is automatically generated and stored in an audit S3 bucket.
• Managing language diversity: Startup with 6 teams uses Python, TypeScript, and Java; platform team creates golden paths for all three; team using Rust for a high-performance service goes through the off-path registration process, accepts responsibility for their own CI setup, and their service is flagged in the catalog as "non-standard pipeline".

Related patterns

• Internal Developer Platform — the IDP is the product context in which golden paths are delivered and maintained.
• Developer Experience — golden paths are measured by their impact on DX metrics: onboarding time, inner loop speed, developer satisfaction.
• Platform Observability — golden path adoption metrics are tracked through platform observability tooling.

Further reading

• Writing Backstage Software Templates — Backstage Docs
• Reusing GitHub Actions Workflows — GitHub Docs
• Full Cycle Developers at Netflix — Netflix Tech Blog