Guide

Delivery

Guardrails and scorecards

Scorecards make drift visible. Guardrails make the unsafe path hard for the baselines that prevent company-scale incidents. Mandates should be rare and come with migration help.

91 of 162 · 2 min read

Golden paths stick when the default is easier than a snowflake, and when drift is visible. Two tools support that. Scorecards rate each service on a short checklist. Guardrails make the unsafe path hard, for the few rules that matter most. The skill is knowing which rules are guardrails and which are guidelines.

The big idea

Think of a building's safety systems. The fire doors and sprinklers are not optional, and they are built into the walls. The paint color on the corridor is a guideline, and nobody gets locked out for choosing a different shade. Guardrails are the sprinklers. Guidelines are the paint.

Walking through it

Scorecards rate a service against a short list, such as:

  • The images are signed.
  • The ownership metadata is filled in.
  • The SLO dashboard is linked.
  • The container runs as non-root.
  • The last deploy succeeded.

Publish the score beside the catalog entry, so teams can see where they stand. Do not turn every check into a merge blocker on day one. Start with visibility, then gate the few checks that prevent company-scale incidents, such as unsigned production images.

Guardrails are automated. Admission policies, required CI workflows and organization-wide reusable workflows make the risky path hard. Guidelines are documented preferences, such as the preferred language version or dashboard layout. Confusing the two causes trouble both ways. Guidelines enforced as blockers create rebellion. Guardrails left as wiki pages create theater.

A workable split: guardrail the supply chain and identity baselines, and keep everything else as guidelines.

Example

A platform roadmap for one quarter at a 60-engineer company might contain three items. First, a reusable CI workflow that scans and signs images, with a goal of 80% of deployable repositories adopting it. Second, a software template for the two main languages. Third, a rule that production DNS needs a catalog owner. It deliberately leaves out a custom deploy API and a service mesh. Those may be right later. They are not the bottleneck if half the repositories still paste cloud keys into CI.

Voluntary adoption beats mandates when the path is good. Reserve mandates for security and compliance floors. If you must mandate something, ship the migration tooling and an enabling sprint with the announcement. A wiki link and a deadline are not enough.

Common mistakes

  • Blocking merges on every check at once. Start with visibility, and gate only the critical few.
  • Mandating without migration help. People will comply on paper and work around it.
  • Writing guardrails as guidelines. Supply-chain and identity baselines need to be enforced, not suggested.

Check yourself

  1. Is a preferred dashboard layout a guardrail or a guideline? A guideline. It is a preference, so it should be documented, not enforced.
  2. What should accompany a mandate? Migration tooling and an enabling sprint, so teams can comply without stalling.

Key takeaways

  • Scorecards make drift visible. Publish them beside the catalog entry.
  • Guardrails are automated for the baselines that prevent large incidents, such as supply chain and identity.
  • Mandate rarely, and pair every mandate with migration help.

Further learning

The overall platform view is in platform engineering. The adoption metrics that show whether guardrails work are in platform as a product.

Backstage documentation, what is BackstageWhat is Backstage? | Backstage Software Catalog and Developer Platformbackstage.io

Platform engineering

Internal developer platforms, golden paths and treating infrastructure as a product. Cut cognitive load without building a second Kubernetes.

Golden paths

A golden path is an opinionated, maintained way to create, ship and observe a service. It should be the easy default, not a prison, and the test is whether a new hire can reach production in a day.

Platform as a product

Treat internal engineers as customers, measure adoption and time to a safe production deploy, and choose a thin platform over a thick one until a clear need forces a thicker abstraction.