Golden paths for platform teams

Every platform team has a golden path. It lives in a Confluence page titled "How we ship services," it was last edited eight months ago, and three teams have already drifted off it because the page didn't run anything — it just described what someone hoped would happen.

The problem with a golden path written as prose is that it has no teeth. Nothing stops a team from skipping the license scan, hand-rolling their own retry logic, or deploying without the canary step. By the time you find out, it's an incident review.

A golden path should be executable and shared — one artifact every team imports, not copies. In OrchStep that artifact is a module: a workflow your teams call as a step, versioned like any dependency.

The sanctioned path, as a module

Put the build-verify-deploy steps in a module once. The mandatory scan, the standard test gate, the approved deploy pipeline — they live in ship-path and nowhere else.

name: golden-paths
defaults:
  service: "checkout"
  target: staging

# The golden path lives in a module so every team ships the same way.
modules:
  - name: ship
    source: "./modules/ship-path"

tasks:
  # `orchstep run release --var service=payments`
  release:
    steps:
      - name: build
        module: ship
        task: build
        with:
          service: "{{ vars.service }}"
      - name: verify
        module: ship
        task: verify
        with:
          service: "{{ vars.service }}"
      - name: deploy
        module: ship
        task: deploy
        with:
          service: "{{ vars.service }}"
          target: "{{ vars.target }}"

A team's whole release surface is now the three module: calls in the top file. They don't get to redefine "verify." If you add a mandatory SBOM step to ship-path, every team that imports it gets it on their next run — no PR to twelve repos, no migration guide.

The point: one place to change

The reason prose golden paths drift is that improving them is expensive — you have to convince every team to re-copy the new version. A module inverts that. The scan, the gate, the deploy mechanics are defined once and consumed everywhere.

# team-a/orchstep.yml — copied from the wiki in March
tasks:
  release:
    steps:
      - name: build
        func: shell
        do: echo "building service-a"
      # scan step? someone deleted it to make CI faster
      - name: deploy
        func: shell
        do: echo "deploying service-a"

# team-a/orchstep.yml — imports the sanctioned path
modules:
  - name: ship
    source: "@platform/ship-path"
tasks:
  release:
    steps:
      - { name: build,  module: ship, task: build }
      - { name: verify, module: ship, task: verify }   # cannot be skipped
      - { name: deploy, module: ship, task: deploy }

The left version is what "standardization by documentation" actually produces. The right version makes the sanctioned path the path of least resistance — which is the only way standardization sticks.

Prove it before it ships

Because the golden path is just a workflow, a dry run shows any team the exact plan they'll execute — resolved variables, every module step, in order — without running a thing:

orchstep run release --var service=payments --dry-run

That's how a platform team reviews adoption: not by asking "did you follow the doc?" but by reading the resolved plan. Full tour: Previewing with Dry Run.

What you actually gained

This isn't a fit for everything. If a team genuinely needs a bespoke pipeline, let them — a golden path is a default, not a cage. But for the 80% of services that just need to ship the normal way, the normal way should be one import.

Where to go next

• Modules — package and share reusable workflows
• Variables & Outputs — how with: passes inputs to a module task
• Previewing with Dry Run — review a plan before it runs

Have a golden path that's really a wiki page? Turn the steps into a module and let orchstep run release --dry-run show a team exactly what they'd get.