Scaffolder: Golden Path Templates

golden-path-go-service/
├── template.yaml              # Scaffolder template definition
├── skeleton/                  # Files to render (Nunjucks templates)
│   ├── .github/
│   │   ├── workflows/
│   │   │   ├── ci.yaml.njk
│   │   │   └── cd.yaml.njk
│   │   └── dependabot.yaml.njk
│   ├── manifests/
│   │   ├── base/
│   │   │   ├── deployment.yaml.njk
│   │   │   ├── service.yaml.njk
│   │   │   ├── servicemonitor.yaml.njk
│   │   │   └── kustomization.yaml.njk
│   │   └── overlays/
│   │       ├── preview/
│   │       │   └── kustomization.yaml.njk
│   │       └── production/
│   │           └── kustomization.yaml.njk
│   ├── Dockerfile.njk
│   ├── devcontainer.json.njk
│   ├── Tiltfile.njk
│   ├── RUNBOOK.md.njk
│   ├── ARCHITECTURE.md.njk
│   ├── .golangci.yaml.njk
│   ├── go.mod.njk
│   └── main.go.njk
└── .github/
    └── workflows/
        └── template-test.yaml  # CI for template itself

spec:
  owner: platform-team
  type: service
  parameters:
    - title: Service Identity
      required: [name, owner, team]
      properties:
        name:
          type: string
          title: Service Name
          description: "Lowercase, hyphenated (e.g., payment-processor)"
          pattern: "^[a-z][a-z0-9-]{1,61}[a-z0-9]$"
          ui:field: ServiceName
        owner:
          type: string
          title: Owner Email
          format: email
        team:
          type: string
          title: Team
          enum: [payments, identity, notifications, platform, data]
          ui:field: OwnerPicker
        description:
          type: string
          title: Description
        language:
          type: string
          title: Language
          const: go
          enum: [go]

    - title: Platform Capabilities
      properties:
        capabilities:
          type: array
          title: Required Capabilities
          description: "Platform-managed dependencies"
          items:
            type: string
            enum: [postgresql, redis, kafka, service-mesh, pubsub, blob-storage]
          default: []
          ui:widget: checkboxes

    - title: Repository
      required: [repoUrl]
      properties:
        repoUrl:
          type: string
          title: Repository URL
          description: "GitHub repository (e.g., github.com/org/repo)"
          pattern: "^github\.com/[a-zA-Z0-9-]+/[a-zA-Z0-9-]+$"

steps:
  # 1. Fetch and render template skeleton
  - id: fetch-template
    name: Fetch Template Skeleton
    action: fetch:template
    input:
      url: ./skeleton
      values:
        service_name: ${{ parameters.name }}
        service_owner: ${{ parameters.owner }}
        service_team: ${{ parameters.team }}
        service_description: ${{ parameters.description }}
        capabilities: ${{ parameters.capabilities }}
        repo_url: ${{ parameters.repoUrl }}

  # 2. Initialize Git repository
  - id: init-git
    name: Initialize Git Repository
    action: shell:git
    input:
      commands:
        - git init
        - git add -A
        - git commit -m "chore: initial scaffold from golden path template"
      dir: ${{ steps.fetch-template.output.dir }}

  # 3. Create GitHub repository
  - id: create-repo
    name: Create GitHub Repository
    action: github:create-repo
    input:
      repoUrl: ${{ parameters.repoUrl }}
      description: ${{ parameters.description }}
      visibility: private
      defaultBranch: main

  # 4. Push initial commit
  - id: push-repo
    name: Push to GitHub
    action: shell:git
    input:
      commands:
        - git remote add origin https://github.com/${{ parameters.repoUrl }}.git
        - git push -u origin main
      dir: ${{ steps.fetch-template.output.dir }}

  # 5. Register in software catalog
  - id: register-catalog
    name: Register in Software Catalog
    action: catalog:register
    input:
      repoUrl: ${{ parameters.repoUrl }}
      catalogInfo:
        apiVersion: backstage.io/v1alpha1
        kind: Component
        metadata:
          name: ${{ parameters.name }}
          description: ${{ parameters.description }}
          annotations:
            github.com/project-slug: ${{ parameters.repoUrl }}
            backstage.io/techdocs-ref: dir:.
          labels:
            team: ${{ parameters.team }}
            platform/capabilities: ${{ join parameters.capabilities "," }}
        spec:
          type: service
          lifecycle: production
          owner: ${{ parameters.team }}
          system: ${{ parameters.team }}-system

  # 6. Configure branch protection
  - id: branch-protection
    name: Configure Branch Protection
    action: github:branch-protection
    input:
      repoUrl: ${{ parameters.repoUrl }}
      branch: main
      requiredStatusChecks:
        - "ci/lint"
        - "ci/test"
        - "ci/security-scan"
        - "ci/build"
      requiredReviews: 1
      dismissStaleReviews: true
      requireCodeOwnerReviews: true

  # 7. Create ArgoCD Application
  - id: create-argocd-app
    name: Create ArgoCD Application
    action: argocd:create-application
    input:
      name: ${{ parameters.name }}
      project: ${{ parameters.team }}
      source:
        repoURL: https://github.com/${{ parameters.repoUrl }}.git
        targetRevision: HEAD
        path: manifests/overlays/production
      destination:
        server: https://kubernetes.default.svc
        namespace: ${{ parameters.team }}-${{ parameters.name }}
      syncPolicy:
        automated:
          prune: true
          selfHeal: true
          allowEmpty: false
        syncOptions:
          - CreateNamespace=true
          - PrunePropagationPolicy=foreground
        retry:
          limit: 5
          backoff:
            duration: 5s
            factor: 2
            maxDuration: 3m

output:
  links:
    - title: Repository
      url: https://github.com/${{ parameters.repoUrl }}
    - title: ArgoCD Application
      url: https://argocd.platform.example.com/applications/${{ parameters.team }}-${{ parameters.name }}
    - title: Grafana Dashboard
      url: https://grafana.platform.example.com/d/service-${{ parameters.name }}
    - title: Runbook
      url: https://github.com/${{ parameters.repoUrl }}/blob/main/RUNBOOK.md

// packages/backend/src/actions/provision-database.ts
import { createAction } from '@backstage/plugin-scaffolder-node';

export const provisionDatabaseAction = createAction({
  id: 'platform:provision-database',
  description: 'Provisions a PostgreSQL database via Platform API',
  schema: {
    input: z.object({
      serviceName: z.string(),
      team: z.string(),
      plan: z.enum(['dev', 'staging', 'prod']).default('dev'),
    }),
    output: z.object({
      connectionString: z.string(),
      host: z.string(),
      database: z.string(),
    }),
  },
  async handler(ctx) {
    const { serviceName, team, plan } = ctx.input;
    const response = await fetch(`${process.env.PLATFORM_API}/databases/postgresql`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${ctx.auth.token}` },
      body: JSON.stringify({ name: serviceName, team, plan }),
    });
    if (!response.ok) throw new Error(`Failed to provision DB: ${response.statusText}`);
    return response.json();
  },
});