Written by Nelson Koning
on 

Designing golden paths for developers with Backstage’s revamped Scaffolder

Golden paths are the company-approved routes that let developers create, operate, and ship software without repeatedly wrestling with platform decisions. When executed well they feel like a well-marked trail through a city: obvious, fast, and safe. Backstage’s recent evolution of the Scaffolder, the growing ecosystem of template tooling (visual editors, field extensions), and richer integrations with GitOps tools mean platform teams can craft golden paths that are both opinionated and flexible — guiding developers while reducing costly toil. This article walks through the practical design patterns that make those golden paths reliable, pleasant, and maintainable.

Why the Scaffolder matters for golden paths

Key platform tooling that changed the game (short)

Design goals for golden paths in Backstage Think in terms of developer experience, correctness, and evolvability:

Practical patterns and examples

1) Make the form the product The form is where most friction lives. Replace free-text boxes with constrained inputs:

Backstage’s FormFieldBlueprint API makes it straightforward to build and register custom form field extensions for these needs, which then show up in the Scaffolder UI and enforce schema-level constraints. That reduces bad inputs and clarifies the golden path. (backstage.io)

2) Validate early, clearly, and locally Validation should run before any long-running actions:

Because the scaffolder model keeps the form and pipeline separate, include a lightweight pre-step that synthesizes a dry-run check and returns deterministic errors to the user — fewer partial runs; faster learning loops.

3) Separate secrets from inputs A golden path often requires credentials (cloud service tokens, container registry credentials). Use the Scaffolder’s secret-handling features (and recent v2 action invocation/secrets schema support) to present secrets fields safely and let platform-managed secrets be injected by the backend rather than typed into public forms. That keeps auditability and reduces accidental secret leakage. (github.com)

4) Make templates idempotent and observable

5) Keep templates updatable — plan for change Template updates are inevitable: dependencies change, CI steps evolve, policy tightens. The golden-path design must balance:

Tooling and patterns to support this:

6) Integrate with GitOps for a clean handoff A golden path should produce the right Git materials so a GitOps controller (Argo CD, Flux) can take over. Many Backstage setups use plugins or actions that create repos, push starter code, and then register an Argo CD application. The developer flow remains simple: fill the form, click create, watch the portal show build & sync links. Examples and plugins already exist to make that integration smoother. (npmjs.com)

A minimal template example (conceptual) Below is a compact, conceptual scaffolder template showing the shape of an opinionated golden path. It demonstrates: parameters with a custom field, a step that uses secrets, and outputs linking to the catalog.

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: opinionated-service
spec:
  owner: platform-team@example.com
  title: Opinionated Service
  parameters:
    - title: Service info
      required:
        - name
        - team
      properties:
        name:
          type: string
          description: "Kebab-case name for your service"
        team:
          type: string
          description: "Team responsible"
          'x-field':
            # this is a custom field extension registered in the app
            'ui:field': team-selector
  steps:
    - id: create-repo
      name: Create Git repository
      action: github:create-repository
      input:
        repoName: ''
        description: 'Scaffolded by the platform'
    - id: add-ci
      name: Add CI and infra
      action: repo:apply-template
      input:
        repo: ''
        # secrets are handled via the action's secret schema (not in parameters)
  output:
    links:
      - url: ''
        title: "Repository"
      - url: '/catalog/'
        title: "Catalog Entry"

This snippet is illustrative; the real scaffolder YAML will reference registered actions, field extensions, and secret schemas. The important part for a golden path is that the template is the single source of truth for developer-facing choices, automation steps, and the outputs that connect people back to platform observability.

Operational concerns and governance

UX is not an afterthought The best golden paths don’t just eliminate steps — they replace them with clarity. A good Scaffolder form:

Design for the common case and surface the uncommon choices progressively; that’s how you get both speed and safety.

Closing analogy Think of a developer’s first project creation as a concert’s soundcheck. The roadies (platform), stage design (infrastructure), and song sheets (templates) need to be set up so the band (developers) can hit the first chord without errors. Backstage’s renewed Scaffolder, the growing visual authoring tools, and richer integrations let platform teams set up that soundcheck once and have it work reliably for every team that shows up — while still allowing the band to riff when they need to.

Selected references and reading

If the portal is the trailhead, the template is the map: keep it readable, mark the hazards, and make the path the obvious, enjoyable route.