Platform Engineering with Backstage: Build a Useful Developer Portal

Backstage projects fail when they become a link directory. A productive portal must shorten time-to-ship through scaffolding, ownership visibility, and policy-aligned golden paths.

What a Useful Portal Must Do#

• Create new services from approved templates.
• Show service ownership and on-call metadata.
• Surface quality checks (SLO status, vulnerabilities, missing docs).
• Link runbooks and deployment history in one place.

Example: Service Template for a New API#

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: node-api-template
spec:
  owner: platform-team
  type: service
  parameters:
    - title: Service Metadata
      required: [name, owner]
      properties:
        name:
          type: string
        owner:
          type: string
  steps:
    - id: fetch-base
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
    - id: publish
      action: publish:github
      input:
        repoUrl: github.com?owner=org&repo=${{ parameters.name }}

This enforces baseline structure and removes one-off repo setup work.

Example: Catalog Entity With Ownership#

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: billing-api
  annotations:
    github.com/project-slug: org/billing-api
spec:
  type: service
  owner: team-finance-platform
  lifecycle: production

Now on-call and accountability are obvious during incidents.

Example: Scorecard Checks#

Use scorecards for concrete standards:

• Has production runbook.
• Has SLO and alert route.
• Has dependency scan passing.
• Has pager ownership defined.

Teams should see failures directly in the portal, not in an unrelated dashboard.

Rollout Strategy#

1. Start with 3-5 high-impact templates.
2. Integrate one identity source and one CI source first.
3. Add scorecards after metadata quality is stable.

Backstage succeeds when it becomes the fastest path to production, not an extra process layer.