Practice: Self-service platforms: golden paths, templates and developer tooling
Generated by Claude through GigAI 0.1.11.10 on 2026-10-12.
Main tool: Backstage · Backstage combines a software catalog, scaffolder templates and docs in one open source portal that runs on a laptop, so every part of a golden path can be practised end to end in one place. · Alternatives: Cookiecutter or Copier give project templating from a command line with no catalog or portal; Terraform modules and Crossplane compositions offer self-service infrastructure but no developer-facing storefront; Argo CD ApplicationSets and Helm charts standardise deployment only; hosted developer portals trade Backstage's plugin flexibility for less operational work.
Every step links into the tool's own documentation; links were checked on 2026-10-12 · version 1
Setup (one time)
1. Check the prerequisites for Software Templates: a supported Node.js and Yarn toolchain, a standalone Backstage app, and a source control integration with a personal access token from a free account.
The scaffolder publishes real repositories, so a missing integration or token is the most common reason a first template run fails. No paid cloud or GPU is needed.
Explained in: Backstage Software Templates | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: You can list each prerequisite and show that the toolchain versions and the integration token are in place.
2. Start the Backstage app locally and open the Software Catalog in your browser.
The catalog is the home page of the portal and the thing every later step reads from or writes to.
Explained in: Backstage Software Catalog | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: The local Backstage app loads in the browser and the catalog page lists the example components.
3. Install the scaffolder action module for your source control provider and list the actions that are available.
Templates are built only from installed actions, so you need to know which building blocks your instance offers before you design a golden path.
Explained in: Builtin actions | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: The installed actions page in your instance shows the publish action for your provider along with the built-in fetch and catalog actions.
Steps
1. Run the built-in example template from the Create page, filling in the form and reviewing the inputs before you launch it.
Experiencing the golden path as a consumer first shows what self-service feels like: a form, a review and a working repository with no ticket filed.
Explained in: Backstage Software Templates | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: The task page shows every step completed and links to a new repository and a new catalog entry.
2. Query the Software Catalog for the component you just created, filtering by kind, owner and tag, then open its entity page.
The catalog is the developer portal's source of truth, and finding things by ownership and metadata is what makes it useful to teams.
Explained in: Backstage Software Catalog | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: You can find the new component through at least two different filters and see its owner and source location on its page.
3. Write a one-page product brief for your platform that names its users, the ticket-driven task you will replace first, and which of the listed Backstage benefits each user group should get.
Treating the platform as a product means starting from users and outcomes, not from features. The brief sets the scope for the template you build next.
Explained in: What is Backstage? | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: You have a short brief with named user groups, one target journey and a benefit mapped to each group.
4. Write a new template definition for an ML training project, starting with a parameters form that asks only for project name, description, owner and repository location.
A golden path encodes the platform team's opinions, so the form should ask for the few choices that vary and fix everything else.
Explained in: Writing Templates | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: Your template file has a multi-page form with required fields and validation for the project name.
5. Write the template's steps so it fetches a skeleton with a training script, an MLflow tracking config, a CI workflow, a docs folder and a catalog descriptor, publishes the repository and registers it in the catalog.
This is the anatomy of an ML golden path: one run produces code, pipeline, docs and catalog metadata that are compliant by default. MLflow and CI here are only files in the skeleton, run locally.
Explained in: Writing Templates | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: The template defines fetch, publish and register steps plus outputs that link to the repository and the catalog entity.
6. Configure a form decorator on your template so submitted form data is enriched before the steps run.
Decorators show how the template object model separates what the user types from what the platform adds, which keeps forms short. The feature is experimental, so check its status first.
Explained in: Experimental Features | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: The template spec lists a decorator and a run shows the decorated value reaching the steps.
7. Configure the owner field with the OwnerPicker so it offers only groups that exist in the catalog.
Enforced ownership at creation time is what keeps the catalog trustworthy and makes later adoption numbers attributable to teams.
Explained in: ui:options Examples | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: The owner field shows a dropdown of catalog groups and rejects free text that is not a known group.
8. Load your template directory into the Template Editor and run a dry run until the generated file tree looks right.
A fast local feedback loop lets you iterate on the golden path without creating throwaway repositories on every attempt.
Explained in: Writing Templates | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: The editor renders your form and the dry run output shows the expected files with your parameter values substituted.
9. Register the template in the catalog through static catalog configuration so it appears on the Create page for every user.
Registration is the promotion step that turns a local file into a discoverable golden path. Keeping the location in config makes it reviewable.
Explained in: Backstage Software Catalog | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: After a restart the ML template appears on the Create page and as a Template entity in the catalog.
10. Configure a default environment and publishing defaults for the scaffolder in the app config, then rerun the template without typing those values.
Pinning shared values in config makes every run reproducible and lets the platform team change a default in one reviewed place.
Explained in: Software Template Configuration | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: A new run produces a repository with the configured defaults applied and the form no longer asks for them.
11. Query the scaffolder audit events after several template runs and count task creations, completions and failures per template.
Adoption and failure rates are the platform's product metrics. Failed tasks tell you where the golden path needs fixing before users give up on it.
Explained in: Audit Events | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: You have a small table of runs, successes and failures for your ML template taken from the backend audit log.
12. Create a templating extension module with the Backstage CLI, add a custom filter that enforces your naming convention, and use it in the ML template.
Shipping platform rules as a versioned backend module is how a production instance keeps many templates consistent. It closes the loop by turning what you learned from the metrics into a shared, tested rule.
Explained in: Templating Extensions | Backstage Software Catalog and Developer Platform (backstage.io), checked 2026-10-12
Done when: The backend starts with your module installed and a template run produces a repository name shaped by your custom filter.
Back to Self-service platforms: golden paths, templates and developer tooling