Internal Developer Platforms with Backstage: Building the Golden Path

1
2

node --version  # >= 20
yarn --version  # >= 4

1
2
3
4
5

npx @backstage/create-app@latest --name my-backstage

cd my-backstage
yarn install
yarn dev  # Starts on http://localhost:3000

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

# docker-compose.yml
version: '3.8'

services:
  backstage:
    image: my-backstage:latest
    build:
      context: .
      dockerfile: packages/backend/Dockerfile
    ports:
      - "7007:7007"
    environment:
      POSTGRES_HOST: postgres
      POSTGRES_PORT: 5432
      POSTGRES_USER: backstage
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      GITHUB_TOKEN: ${GITHUB_TOKEN}
      AUTH_GITHUB_CLIENT_ID: ${AUTH_GITHUB_CLIENT_ID}
      AUTH_GITHUB_CLIENT_SECRET: ${AUTH_GITHUB_CLIENT_SECRET}
      APP_CONFIG_app_baseUrl: "https://backstage.yourcompany.com"
      APP_CONFIG_backend_baseUrl: "https://backstage.yourcompany.com"
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: backstage
      POSTGRES_USER: backstage
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U backstage"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

volumes:
  postgres-data:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# packages/backend/Dockerfile
FROM node:20-bookworm-slim AS build

WORKDIR /app
COPY . .
RUN yarn install --frozen-lockfile
RUN yarn tsc
RUN yarn build:backend --config ../../app-config.yaml

FROM node:20-bookworm-slim

WORKDIR /app
COPY --from=build /app/packages/backend/dist/bundle.tar.gz .
RUN tar -xzf bundle.tar.gz && rm bundle.tar.gz
RUN yarn install --frozen-lockfile --production

CMD ["node", "packages/backend", "--config", "app-config.yaml"]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

# app-config.yaml
app:
  title: "Acme Developer Portal"
  baseUrl: ${APP_BASE_URL}

organization:
  name: Acme Corp

backend:
  baseUrl: ${BACKEND_BASE_URL}
  listen:
    port: 7007
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}
      database: backstage_plugin_catalog

auth:
  environment: production
  providers:
    github:
      production:
        clientId: ${AUTH_GITHUB_CLIENT_ID}
        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
        signIn:
          resolvers:
            - resolver: usernameMatchingUserEntityName

integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

catalog:
  providers:
    githubOrg:
      id: production
      githubUrl: https://github.com
      orgs: ['your-org']
  locations:
    # Seed with some example entities
    - type: url
      target: https://github.com/your-org/backstage-catalog/blob/main/all.yaml
      rules:
        - allow: [Component, System, API, Group, User, Resource, Location]

techdocs:
  builder: external
  generator:
    runIn: docker
  publisher:
    type: awsS3
    awsS3:
      bucketName: ${TECHDOCS_S3_BUCKET}
      region: us-east-1

scaffolder:
  defaultAuthor:
    name: Backstage Scaffolder
    email: scaffolder@yourcompany.com

proxy:
  '/pagerduty':
    target: https://api.pagerduty.com
    headers:
      Authorization: Token token=${PAGERDUTY_TOKEN}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60

# catalog-info.yaml (in your service repository root)
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payments-api
  title: Payments API
  description: Handles all payment processing including charges, refunds, and webhooks
  annotations:
    # GitHub integration — shows CI status, PRs, contributors
    github.com/project-slug: your-org/payments-api

    # Kubernetes integration — shows pod status, logs
    backstage.io/kubernetes-id: payments-api
    backstage.io/kubernetes-namespace: production

    # ArgoCD integration
    argocd/app-name: payments-api

    # PagerDuty integration — shows active incidents
    pagerduty.com/integration-key: ${PAGERDUTY_PAYMENTS_KEY}

    # TechDocs location
    backstage.io/techdocs-ref: dir:.

    # Runbook URL
    runbook-url: https://wiki.yourcompany.com/runbooks/payments-api

  tags:
    - payments
    - critical
    - go

  links:
    - url: https://grafana.yourcompany.com/d/payments
      title: Grafana Dashboard
      icon: dashboard
    - url: https://payments-api.yourcompany.com/api/docs
      title: API Documentation
      icon: docs

spec:
  type: service
  lifecycle: production
  owner: group:payments-team
  system: checkout-system

  # API this service provides
  providesApis:
    - payments-api-v2

  # APIs this service consumes
  consumesApis:
    - fraud-detection-api
    - notifications-api

  # Other components this service depends on
  dependsOn:
    - resource:payments-postgres
    - resource:payments-redis
    - component:fraud-detection-service

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# systems/checkout-system.yaml
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: checkout-system
  description: All services involved in the checkout flow
  tags: [checkout, critical]
spec:
  owner: group:platform-team
  domain: ecommerce

---
apiVersion: backstage.io/v1alpha1
kind: Domain
metadata:
  name: ecommerce
  description: E-commerce platform components
spec:
  owner: group:engineering-leadership

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

# apis/payments-api-v2.yaml
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: payments-api-v2
  description: Payment processing REST API
  tags: [payments, rest]
spec:
  type: openapi
  lifecycle: production
  owner: group:payments-team
  system: checkout-system
  definition:
    $text: https://payments-api.yourcompany.com/openapi.yaml
    # Or inline:
    # $text: |
    #   openapi: 3.0.0
    #   info:
    #     title: Payments API
    #     ...

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# resources/payments-postgres.yaml
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: payments-postgres
  description: PostgreSQL database for payments service
  tags: [database, postgresql]
spec:
  type: database
  owner: group:platform-team
  system: checkout-system

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

// packages/backend/src/index.ts
import { GithubEntityProvider } from '@backstage/plugin-catalog-backend-module-github';

// In your catalog builder:
const catalogBuilder = await CatalogBuilder.create(env);

catalogBuilder.addEntityProvider(
  GithubEntityProvider.fromConfig(env.config, {
    logger: env.logger,
    scheduler: env.scheduler,
    schedule: env.scheduler.createScheduledTaskRunner({
      frequency: { minutes: 30 },
      timeout: { minutes: 3 },
    }),
  }),
);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# app-config.yaml — discovery rules
catalog:
  providers:
    github:
      your-org:
        organization: 'your-org'
        catalogPath: '/catalog-info.yaml'
        filters:
          branch: 'main'
          repository: '.*'   # All repos; use regex to filter
        schedule:
          frequency: { minutes: 30 }
          timeout: { minutes: 3 }

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154

# templates/go-microservice/template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: go-microservice
  title: Go Microservice
  description: Creates a production-ready Go microservice with CI/CD, monitoring, and Kubernetes deployment
  tags:
    - recommended
    - go
    - kubernetes

spec:
  owner: group:platform-team
  type: service

  # Input form shown to developers
  parameters:
    - title: Service Details
      required: [name, description, owner]
      properties:
        name:
          title: Service Name
          type: string
          description: Lowercase, hyphen-separated (e.g., payment-processor)
          pattern: '^[a-z][a-z0-9-]*$'
          ui:autofocus: true

        description:
          title: Description
          type: string
          description: What does this service do? (shown in the catalog)

        owner:
          title: Owner
          type: string
          description: Team that owns this service
          ui:field: OwnerPicker
          ui:options:
            allowedKinds: [Group]

        system:
          title: System
          type: string
          description: Which system does this service belong to?
          ui:field: EntityPicker
          ui:options:
            catalogFilter:
              kind: System

    - title: Infrastructure
      required: [namespace, replicaCount]
      properties:
        namespace:
          title: Kubernetes Namespace
          type: string
          default: production
          enum: [production, staging, development]

        replicaCount:
          title: Initial Replica Count
          type: integer
          default: 2
          minimum: 1
          maximum: 10

        enableDatabase:
          title: PostgreSQL Database
          type: boolean
          default: false
          description: Provision a PostgreSQL database for this service

        enableRedis:
          title: Redis Cache
          type: boolean
          default: false

    - title: Repository
      required: [repoUrl]
      properties:
        repoUrl:
          title: Repository Location
          type: string
          ui:field: RepoUrlPicker
          ui:options:
            allowedHosts: [github.com]
            allowedOwners: [your-org]

  # Actions that execute when the form is submitted
  steps:
    - id: fetch-template
      name: Fetch Template Files
      action: fetch:template
      input:
        url: ./skeleton
        values:
          name: ${{ parameters.name }}
          description: ${{ parameters.description }}
          owner: ${{ parameters.owner }}
          system: ${{ parameters.system }}
          namespace: ${{ parameters.namespace }}
          replicaCount: ${{ parameters.replicaCount }}
          enableDatabase: ${{ parameters.enableDatabase }}
          enableRedis: ${{ parameters.enableRedis }}
          repoName: ${{ (parameters.repoUrl | parseRepoUrl).repo }}
          orgName: ${{ (parameters.repoUrl | parseRepoUrl).owner }}

    - id: publish
      name: Publish to GitHub
      action: publish:github
      input:
        allowedHosts: [github.com]
        description: ${{ parameters.description }}
        repoUrl: ${{ parameters.repoUrl }}
        defaultBranch: main
        repoVisibility: private
        topics:
          - go
          - microservice
          - ${{ parameters.system }}

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

    # Optionally open a PR to the infrastructure repo for database/redis provisioning
    - id: create-infra-pr
      if: ${{ parameters.enableDatabase or parameters.enableRedis }}
      name: Create Infrastructure PR
      action: publish:github:pull-request
      input:
        repoUrl: github.com?repo=infrastructure&owner=your-org
        title: "Provision resources for ${{ parameters.name }}"
        branchName: provision-${{ parameters.name }}
        description: |
          Auto-generated by Backstage scaffolder.
          Service: ${{ parameters.name }}
          Database: ${{ parameters.enableDatabase }}
          Redis: ${{ parameters.enableRedis }}
        targetPath: services/${{ parameters.name }}

  output:
    links:
      - title: Repository
        url: ${{ steps.publish.output.remoteUrl }}
      - title: Open in Catalog
        icon: catalog
        entityRef: ${{ steps.register.output.entityRef }}
      - title: Infrastructure PR
        url: ${{ steps['create-infra-pr'].output.remoteUrl }}
        if: ${{ parameters.enableDatabase or parameters.enableRedis }}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# skeleton/catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: ${{ values.name }}
  title: ${{ values.name | title }}
  description: ${{ values.description }}
  annotations:
    github.com/project-slug: ${{ values.orgName }}/${{ values.repoName }}
    backstage.io/kubernetes-id: ${{ values.name }}
    backstage.io/techdocs-ref: dir:.
  tags:
    - go
    - ${{ values.system }}
spec:
  type: service
  lifecycle: experimental
  owner: ${{ values.owner }}
  system: ${{ values.system }}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

// skeleton/cmd/server/main.go
package main

import (
	"context"
	"fmt"
	"log/slog"
	"net/http"
	"os"
	"os/signal"
	"syscall"
	"time"

	"github.com/${{ values.orgName }}/${{ values.repoName }}/internal/config"
	"github.com/${{ values.orgName }}/${{ values.repoName }}/internal/server"
)

func main() {
	logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
		Level: slog.LevelInfo,
	}))
	slog.SetDefault(logger)

	cfg, err := config.Load()
	if err != nil {
		slog.Error("failed to load config", "error", err)
		os.Exit(1)
	}

	srv := server.New(cfg, logger)

	httpServer := &http.Server{
		Addr:         fmt.Sprintf(":%d", cfg.Port),
		Handler:      srv,
		ReadTimeout:  10 * time.Second,
		WriteTimeout: 30 * time.Second,
		IdleTimeout:  120 * time.Second,
	}

	go func() {
		slog.Info("starting server", "port", cfg.Port, "service", "${{ values.name }}")
		if err := httpServer.ListenAndServe(); err != nil && err != http.ErrServerClosed {
			slog.Error("server error", "error", err)
			os.Exit(1)
		}
	}()

	quit := make(chan os.Signal, 1)
	signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
	<-quit

	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
	defer cancel()
	if err := httpServer.Shutdown(ctx); err != nil {
		slog.Error("server shutdown error", "error", err)
	}
	slog.Info("server stopped")
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

# skeleton/.github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:

env:
  SERVICE_NAME: ${{ values.name }}
  REGISTRY: ghcr.io
  IMAGE: ghcr.io/${{ values.orgName }}/${{ values.repoName }}

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version-file: go.mod
          cache: true
      - run: go test -race -coverprofile=coverage.out ./...
      - uses: codecov/codecov-action@v4

  build:
    needs: test
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - uses: docker/login-action@v3
        with:
          registry: ${{ "{{" }} env.REGISTRY }}
          username: ${{ "{{" }} github.actor }}
          password: ${{ "{{" }} secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v5
        with:
          push: ${{ "{{" }} github.ref == 'refs/heads/main' }}
          tags: |
            ${{ "{{" }} env.IMAGE }}:latest
            ${{ "{{" }} env.IMAGE }}:${{ "{{" }} github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

  deploy-staging:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/checkout@v4
      - uses: azure/setup-helm@v4
      - name: Deploy to staging
        run: |
          helm upgrade --install ${{ values.name }} ./helm/${{ values.name }} \
            --namespace staging \
            --set image.tag=${{ "{{" }} github.sha }} \
            --wait

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# docs/mkdocs.yml
site_name: "${{ values.name }} Documentation"
site_description: "${{ values.description }}"
repo_url: https://github.com/your-org/${{ values.repoName }}
edit_uri: edit/main/docs/

nav:
  - Home: index.md
  - Architecture: architecture.md
  - API Reference: api.md
  - Runbooks:
    - Overview: runbooks/index.md
    - Incident Response: runbooks/incident-response.md
    - Deployment: runbooks/deployment.md
  - ADRs:
    - ADR-001 Database Choice: adrs/001-database-choice.md

plugins:
  - techdocs-core

markdown_extensions:
  - admonition
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.details

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

<!-- docs/index.md -->
# Payments API

The Payments API handles all payment processing including charges, refunds, and webhook delivery.

## Quick Reference

| Item | Value |
|------|-------|
| Owner | [Payments Team](../../group/payments-team) |
| On-Call | [PagerDuty](https://yourcompany.pagerduty.com/service-directory/payments-api) |
| Grafana | [Dashboard](https://grafana.yourcompany.com/d/payments) |
| SLO | 99.9% availability, p99 < 500ms |

## Getting Started

```bash
# Clone and run locally
git clone git@github.com:your-org/payments-api.git
cd payments-api
task infra:up   # Start local dependencies
task dev        # Start with hot reload

1
2

yarn --cwd packages/app add @backstage/plugin-kubernetes
yarn --cwd packages/backend add @backstage/plugin-kubernetes-backend

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# app-config.yaml
kubernetes:
  serviceLocatorMethod:
    type: multiTenant
  clusterLocatorMethods:
    - type: config
      clusters:
        - url: ${K8S_API_URL}
          name: production
          authProvider: serviceAccount
          serviceAccountToken: ${K8S_SERVICE_ACCOUNT_TOKEN}
          caData: ${K8S_CA_DATA}
          skipTLSVerify: false

        - url: ${K8S_STAGING_API_URL}
          name: staging
          authProvider: serviceAccount
          serviceAccountToken: ${K8S_STAGING_TOKEN}

1

yarn --cwd packages/app add @backstage-community/plugin-github-actions

1
2
3
4
5
6
7

// packages/app/src/components/catalog/EntityPage.tsx
import { EntityGithubActionsContent } from '@backstage-community/plugin-github-actions';

// Add to the service entity page:
<EntityLayout.Route path="/ci-cd" title="CI/CD">
  <EntityGithubActionsContent />
</EntityLayout.Route>

1

yarn --cwd packages/app add @roadiehq/backstage-plugin-argo-cd

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# app-config.yaml
argocd:
  username: ${ARGOCD_USERNAME}
  password: ${ARGOCD_PASSWORD}
  appLocatorMethods:
    - type: config
      instances:
        - name: production
          url: https://argocd.yourcompany.com
          token: ${ARGOCD_TOKEN}

1
2

yarn --cwd packages/app add @pagerduty/backstage-plugin
yarn --cwd packages/backend add @pagerduty/backstage-plugin-backend

1
2
3
4
5
6
7

// packages/app/src/components/catalog/EntityPage.tsx
import { EntityPagerDutyCard } from '@pagerduty/backstage-plugin';

// Add to service overview:
<Grid item md={6}>
  <EntityPagerDutyCard />
</Grid>

1

yarn --cwd packages/app add @backstage/plugin-cost-insights

1
2
3
4
5
6
7
8
9

// packages/backend/src/index.ts
import { SearchIndex } from '@backstage/plugin-search-backend-node';
import { ElasticSearchSearchEngine } from '@backstage/plugin-search-backend-module-elasticsearch';

// Configure search engine (or use the included Lunr for small installations)
const searchEngine = await ElasticSearchSearchEngine.fromConfig({
  logger,
  config,
});

1
2
3

# Generate a new plugin scaffold
yarn backstage-cli new --select plugin
# Enter name: my-deployment-status

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

// plugins/my-deployment-status/src/components/DeploymentStatusCard.tsx
import React from 'react';
import { useEntity } from '@backstage/plugin-catalog-react';
import { InfoCard, Progress, StatusOK, StatusError } from '@backstage/core-components';
import { useApi, configApiRef } from '@backstage/core-plugin-api';
import useAsync from 'react-use/lib/useAsync';

export const DeploymentStatusCard = () => {
  const { entity } = useEntity();
  const configApi = useApi(configApiRef);
  const backendUrl = configApi.getString('backend.baseUrl');

  const serviceName = entity.metadata.name;

  const { loading, value: deployment, error } = useAsync(async () => {
    const resp = await fetch(
      `${backendUrl}/api/proxy/deployments/${serviceName}/status`
    );
    if (!resp.ok) throw new Error('Failed to fetch deployment status');
    return resp.json();
  }, [serviceName]);

  if (loading) return <Progress />;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <InfoCard title="Deployment Status">
      <table>
        <tbody>
          <tr>
            <td>Production</td>
            <td>
              {deployment.production.healthy
                ? <StatusOK>v{deployment.production.version}</StatusOK>
                : <StatusError>Degraded</StatusError>
              }
            </td>
          </tr>
          <tr>
            <td>Staging</td>
            <td>
              {deployment.staging.healthy
                ? <StatusOK>v{deployment.staging.version}</StatusOK>
                : <StatusError>Degraded</StatusError>
              }
            </td>
          </tr>
        </tbody>
      </table>
    </InfoCard>
  );
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# What "good" looks like after 6 months
catalog_completeness:
  services_registered: ">= 90%"
  services_with_owner: ">= 95%"
  services_with_techdocs: ">= 70%"
  apis_documented: ">= 80%"

developer_experience:
  time_to_first_service: "< 30 minutes"  # Was: 2-5 days
  onboarding_time: "< 1 week"            # Was: 2-4 weeks
  incident_mean_time_to_owner: "< 5 min" # Was: 30+ min (searching Slack)

template_usage:
  services_created_via_template: ">= 80%"
  templates_available: ">= 5"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# GitHub Actions workflow to detect orphaned catalog entries
# (services in catalog that no longer have a repository)
name: Catalog Audit

on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday morning

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - name: Find orphaned catalog entries
        run: |
          # Query Backstage API for all components
          curl -H "Authorization: Bearer ${BACKSTAGE_TOKEN}" \
            "https://backstage.yourcompany.com/api/catalog/entities?filter=kind=Component" \
            | jq -r '.[].metadata.annotations["github.com/project-slug"]' \
            | while read slug; do
                if ! gh repo view "$slug" &>/dev/null; then
                  echo "ORPHANED: $slug"
                fi
              done

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

# kubernetes/backstage-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: backstage
  namespace: backstage
spec:
  replicas: 2
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 0
      maxSurge: 1
  selector:
    matchLabels:
      app: backstage
  template:
    spec:
      affinity:
        podAntiAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            - topologyKey: kubernetes.io/hostname
              labelSelector:
                matchLabels:
                  app: backstage
      containers:
        - name: backstage
          image: your-registry/backstage:latest
          resources:
            requests:
              cpu: 500m
              memory: 512Mi
            limits:
              cpu: 2
              memory: 2Gi
          readinessProbe:
            httpGet:
              path: /healthcheck
              port: 7007
            initialDelaySeconds: 30
            periodSeconds: 10
          livenessProbe:
            httpGet:
              path: /healthcheck
              port: 7007
            initialDelaySeconds: 60
            periodSeconds: 30

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# app-config.production.yaml
auth:
  # Require authentication — no anonymous access
  dangerouslyDisableDefaultAuthPolicy: false

backend:
  auth:
    externalAccess:
      # Service-to-service tokens for CI/CD automation
      - type: static
        options:
          token: ${BACKSTAGE_CI_TOKEN}
          subject: ci-cd-pipeline

  # CSRF protection
  csp:
    connect-src: ["'self'", 'https:']
    img-src: ["'self'", 'data:', 'https:']
    script-src: ["'self'"]