Internal Developer Portal Backstage

Platform Engineering: Spotify Backstage & Golden Path Scaffolding

When to Use This Skill

Triggers — load this skill when:

• A platform team needs a catalog, scaffolder template, or golden path defined
• Service onboarding and ownership metadata must be standardized
• Platform adoption or DevEx needs to be measured as a product

Route elsewhere when:

• Underlying delivery automation -> cicd-pipeline-design and gitops-multi-cluster-argo-flux
• Delivery performance measurement -> devops-metrics-dora-kpis

1. Backstage Software Template Definition (template.yaml)

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: springboot-microservice-template
  title: Production Spring Boot Microservice
  description: Scaffolds a 12-factor Spring Boot service with CI/CD, Helm charts, and OpenTelemetry
spec:
  owner: platform-team
  type: service

  parameters:
    - title: Service Configuration
      required: [component_id, description, owner]
      properties:
        component_id:
          title: Unique Service Name
          type: string
          pattern: '^[a-z0-9-]+$'
        description:
          title: Description
          type: string
        owner:
          title: Owner Team
          type: string
          ui:field: OwnerPicker

  steps:
    - id: fetch-base
      name: Fetch Template Skeleton
      action: fetch:template
      input:
        url: ./skeleton
        values:
          component_id: ${{ parameters.component_id }}
          owner: ${{ parameters.owner }}

    - id: publish-github
      name: Publish Repository to GitHub
      action: publish:github
      input:
        repoUrl: github.com?owner=my-org&repo=${{ parameters.component_id }}
        defaultBranch: main

    - id: register-catalog
      name: Register in Backstage Catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['publish-github'].output.repoContentsUrl }}
        catalogInfoPath: '/catalog-info.yaml'

2. Platform Engineering Golden Rules

• Paved Road over Mandates: Build self-service workflows that make the secure and reliable way the easiest way for product engineers.
• Treat the Platform as a Product: Measure internal customer Net Promoter Score (NPS), Time to 10th Deployment, and lead time for changes (DORA).
• Service Ownership via Catalog: Require clear team ownership, on-call links, and API specifications for every registered component.

3. TechDocs as the Documentation Plane

TechDocs renders docs-as-code from each service's own repository into the portal, so documentation lives beside the code it describes and is reviewed in the same PR:

# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payments-api
  annotations:
    backstage.io/techdocs-ref: dir:.        # mkdocs.yml at the repo root
    backstage.io/source-location: url:https://github.com/acme/payments-api
spec:
  type: service
  lifecycle: production
  owner: group:payments
  system: checkout

# mkdocs.yml
site_name: Payments API
nav: [Overview: index.md, Runbook: runbook.md, API: api.md]
plugins: [techdocs-core]

Build docs in CI and publish to object storage (the external build pipeline), not on the Backstage server — in-server builds make the portal slow and couple its uptime to doc rendering. Make the scaffolder template emit mkdocs.yml, an index.md and a runbook.md stub so every new service starts with a documentation surface, and treat a missing runbook annotation as a catalog lint failure rather than a suggestion.

4. Anti-Patterns