DevOps Internal Developer Platform Playbook 2026

# Create a new project using the Backstage CLI
npx @backstage/create-app@latest --skip-install

# Resulting directory structure
my-backstage/
├── app-config.yaml           # Core configuration file
├── app-config.production.yaml
├── packages/
│   ├── app/                  # Frontend (React)
│   └── backend/              # Backend (Node.js)
├── plugins/                  # Custom plugins
├── catalog-info.yaml         # Catalog registration for this project itself
└── package.json

# Install dependencies and run
cd my-backstage
yarn install
yarn dev
# Access at http://localhost:3000

# app-config.yaml
app:
  title: 'MyOrg Developer Platform'
  baseUrl: http://localhost:3000

organization:
  name: 'MyOrg'

backend:
  baseUrl: http://localhost:7007
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}

# GitHub integration (automatic service catalog discovery)
integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

# Software Catalog settings
catalog:
  import:
    entityFilename: catalog-info.yaml
  rules:
    - allow: [Component, System, API, Resource, Location, Group, User]
  locations:
    # Automatically discover catalog-info.yaml from all repositories in the organization
    - type: github-discovery
      target: https://github.com/my-org/*/blob/main/catalog-info.yaml
    # Manual registration
    - type: file
      target: ./catalog-entities/all-systems.yaml

# Authentication (GitHub OAuth)
auth:
  environment: development
  providers:
    github:
      development:
        clientId: ${GITHUB_OAUTH_CLIENT_ID}
        clientSecret: ${GITHUB_OAUTH_CLIENT_SECRET}

# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  description: 'Order processing microservice'
  annotations:
    github.com/project-slug: my-org/order-service
    backstage.io/techdocs-ref: dir:.
    datadoghq.com/dashboard-url: https://app.datadoghq.com/dashboard/abc-123
    pagerduty.com/service-id: PXXXXXX
    argocd/app-name: order-service-prod
  tags:
    - java
    - spring-boot
    - tier-1
  links:
    - url: https://order.internal.example.com
      title: Production URL
    - url: https://grafana.internal.example.com/d/order-service
      title: Grafana Dashboard
spec:
  type: service
  lifecycle: production
  owner: team-commerce
  system: commerce-platform
  dependsOn:
    - component:payment-service
    - resource:orders-database
  providesApis:
    - order-api
  consumesApis:
    - payment-api
    - inventory-api
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: order-api
  description: 'Order REST API'
spec:
  type: openapi
  lifecycle: production
  owner: team-commerce
  definition:
    $text: ./docs/openapi.yaml

# templates/spring-boot-service/template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: spring-boot-service
  title: 'Spring Boot Microservice'
  description: 'Creates a Spring Boot service with auto-configured CI/CD, monitoring, and catalog registration'
  tags:
    - java
    - spring-boot
    - recommended
spec:
  owner: team-platform
  type: service
  parameters:
    - title: Service Information
      required:
        - serviceName
        - ownerTeam
        - tier
      properties:
        serviceName:
          title: Service Name
          type: string
          pattern: '^[a-z][a-z0-9-]*$'
          description: 'Only lowercase letters, numbers, and hyphens allowed'
        ownerTeam:
          title: Owner Team
          type: string
          ui:field: OwnerPicker
          ui:options:
            catalogFilter:
              kind: Group
        tier:
          title: Service Tier
          type: string
          enum: ['tier-1', 'tier-2', 'tier-3']
          enumNames: ['Tier 1 (99.99% SLO)', 'Tier 2 (99.9% SLO)', 'Tier 3 (99% SLO)']
        javaVersion:
          title: Java Version
          type: string
          default: '21'
          enum: ['17', '21']

    - title: Infrastructure Settings
      properties:
        database:
          title: Database
          type: string
          default: 'postgresql'
          enum: ['postgresql', 'mysql', 'none']
        messageQueue:
          title: Message Queue
          type: string
          default: 'none'
          enum: ['kafka', 'rabbitmq', 'none']
        replicaCount:
          title: Default Replica Count
          type: integer
          default: 3
          minimum: 1
          maximum: 20

  steps:
    # 1. Generate repository from template
    - id: fetch-template
      name: Generate Template Code
      action: fetch:template
      input:
        url: ./skeleton
        values:
          serviceName: ${{ parameters.serviceName }}
          ownerTeam: ${{ parameters.ownerTeam }}
          tier: ${{ parameters.tier }}
          javaVersion: ${{ parameters.javaVersion }}
          database: ${{ parameters.database }}
          replicaCount: ${{ parameters.replicaCount }}

    # 2. Create GitHub repository
    - id: publish
      name: Create GitHub Repository
      action: publish:github
      input:
        allowedHosts: ['github.com']
        repoUrl: github.com?owner=my-org&repo=${{ parameters.serviceName }}
        defaultBranch: main
        repoVisibility: internal
        protectDefaultBranch: true
        requireCodeOwnerReviews: true

    # 3. Register ArgoCD application
    - id: register-argocd
      name: Register ArgoCD Application
      action: argocd:create-resources
      input:
        appName: ${{ parameters.serviceName }}-prod
        argoInstance: main
        namespace: ${{ parameters.serviceName }}
        repoUrl: https://github.com/my-org/${{ parameters.serviceName }}
        path: k8s/overlays/production

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

  output:
    links:
      - title: Repository
        url: ${{ steps['publish'].output.remoteUrl }}
      - title: Catalog
        icon: catalog
        entityRef: ${{ steps['register-catalog'].output.entityRef }}

# mkdocs.yml (root of each service repository)
site_name: order-service
nav:
  - Home: index.md
  - Architecture: architecture.md
  - API Reference: api.md
  - Runbook: runbook.md
  - ADR:
      - adr/001-database-choice.md
      - adr/002-event-schema.md

plugins:
  - techdocs-core

<!-- docs/runbook.md -->

# Order Service Operations Runbook

## Incident Response

### Order Processing Delay (P95 > 500ms)

1. Check Grafana dashboard: [Link]
2. Check DB connection pool status:
   ```bash
   kubectl exec -it deploy/order-service -- curl localhost:8080/actuator/metrics/hikaricp.connections.active
   ```

## Play 7: Self-Service Infrastructure Provisioning

Enable developers to provision databases, message queues, caches, and more directly from the Backstage UI. Actual infrastructure creation is handled via Terraform + GitOps.

```yaml
# templates/provision-postgresql/template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: provision-postgresql
  title: 'PostgreSQL Database Provisioning'
  description: 'Self-service provisioning of RDS PostgreSQL instances'
spec:
  owner: team-platform
  type: resource
  parameters:
    - title: Database Settings
      required:
        - dbName
        - environment
        - instanceClass
      properties:
        dbName:
          title: DB Name
          type: string
          pattern: '^[a-z][a-z0-9_]*$'
        environment:
          title: Environment
          type: string
          enum: ['dev', 'staging', 'production']
        instanceClass:
          title: Instance Size
          type: string
          default: 'db.r7g.large'
          enum:
            - 'db.t4g.medium'
            - 'db.r7g.large'
            - 'db.r7g.xlarge'
            - 'db.r7g.2xlarge'
          enumNames:
            - 'Small (2 vCPU, 4GB) - dev/staging'
            - 'Medium (2 vCPU, 16GB) - production'
            - 'Large (4 vCPU, 32GB) - production'
            - 'XLarge (8 vCPU, 64GB) - high traffic'
        storageGb:
          title: Storage (GB)
          type: integer
          default: 100
          minimum: 20
          maximum: 16000
        multiAz:
          title: Multi-AZ Deployment
          type: boolean
          default: false

  steps:
    - id: create-terraform-pr
      name: Create Terraform PR
      action: publish:github:pull-request
      input:
        repoUrl: github.com?owner=my-org&repo=infrastructure
        branchName: provision-db-${{ parameters.dbName }}
        title: 'DB Provisioning: ${{ parameters.dbName }} (${{ parameters.environment }})'
        description: |
          Automatically generated DB provisioning request.

          - DB Name: ${{ parameters.dbName }}
          - Environment: ${{ parameters.environment }}
          - Instance: ${{ parameters.instanceClass }}
          - Storage: ${{ parameters.storageGb }}GB
          - Multi-AZ: ${{ parameters.multiAz }}
        targetPath: terraform/rds/${{ parameters.environment }}/${{ parameters.dbName }}
        sourcePath: ./terraform-template

# platform_metrics.py - Platform KPI dashboard data collection
import requests
from datetime import datetime, timedelta

class PlatformMetrics:
    def __init__(self, github_token: str, backstage_url: str):
        self.github = github_token
        self.backstage = backstage_url

    def service_creation_lead_time(self) -> dict:
        """New service creation lead time (target: under 30 minutes)"""
        # Extract from Backstage scaffolder logs
        response = requests.get(
            f"{self.backstage}/api/scaffolder/v2/tasks",
            params={"createdAfter": (datetime.now() - timedelta(days=90)).isoformat()}
        )
        tasks = response.json()["items"]

        lead_times = []
        for task in tasks:
            if task["status"] == "completed":
                start = datetime.fromisoformat(task["createdAt"])
                end = datetime.fromisoformat(task["completedAt"])
                lead_times.append((end - start).total_seconds() / 60)

        return {
            "median_minutes": sorted(lead_times)[len(lead_times) // 2],
            "p95_minutes": sorted(lead_times)[int(len(lead_times) * 0.95)],
            "total_services_created": len(lead_times),
        }

    def golden_path_adoption_rate(self) -> dict:
        """Golden path adoption rate (target: 80% or above)"""
        # Query reusable workflow usage from the GitHub API
        repos = requests.get(
            "https://api.github.com/orgs/my-org/repos",
            headers={"Authorization": f"token {self.github}"},
            params={"per_page": 100, "type": "internal"}
        ).json()

        using_golden_path = 0
        total_active = 0

        for repo in repos:
            if repo["archived"]:
                continue
            total_active += 1
            # Check for golden path references in CI workflows
            workflows = requests.get(
                f"https://api.github.com/repos/my-org/{repo['name']}/actions/workflows",
                headers={"Authorization": f"token {self.github}"}
            ).json()

            for wf in workflows.get("workflows", []):
                if "golden" in wf.get("path", "").lower():
                    using_golden_path += 1
                    break

        return {
            "adoption_rate": using_golden_path / max(total_active, 1),
            "using_golden_path": using_golden_path,
            "total_active_repos": total_active,
        }

    def developer_nps(self) -> dict:
        """Developer satisfaction NPS (target: 30 or above)"""
        # Quarterly survey results (Google Forms / Typeform, etc.)
        # Integrate via API directly, or enter manually
        return {
            "nps_score": 42,
            "promoters_pct": 55,
            "detractors_pct": 13,
            "response_rate": 0.72,
            "top_complaints": [
                "Build times are slow",
                "Log search UI is inconvenient",
                "Insufficient permission request automation",
            ]
        }

WARN: Entity refresh for component:order-service took 45s (threshold: 10s)

# Solution: Limit scan scope + configure caching
catalog:
  providers:
    github:
      myOrg:
        organization: 'my-org'
        catalogPath: '/catalog-info.yaml'
        filters:
          repository: '^(?!archived-).*$' # Exclude repositories with archived- prefix
          topic:
            include: ['backstage-enabled'] # Topic-based filtering
        schedule:
          frequency: { minutes: 30 } # 30-minute interval (default is 5 minutes)
          timeout: { minutes: 5 }

Error: Resource not accessible by integration
HttpError: 403 - Resource not accessible by integration

# Check GitHub App permissions
# Settings > Developer settings > GitHub Apps > [App Name] > Permissions
# Required permissions:
# - Repository: Administration (Read & Write)
# - Repository: Contents (Read & Write)
# - Organization: Members (Read)

# Or when using a Personal Access Token (PAT), required scopes:
# repo, workflow, admin:org

mkdocs build failed: No module named 'techdocs_core'

# Solution: Install the plugin in the TechDocs build environment
pip install mkdocs-techdocs-core

# When using Docker build
docker run --rm -v $(pwd):/content \
  spotify/techdocs:latest \
  build --site-dir /content/site

# Configure build method in app-config.yaml
techdocs:
  builder: 'external'          # Build in CI
  publisher:
    type: 'awsS3'
    awsS3:
      bucketName: 'my-org-techdocs'
      region: 'ap-northeast-2'