Platform-Engineering on zharif.my

GitHub Organization as Code with Terraform

Wed, 22 Apr 2026 00:00:00 +0000

Why This Matters

If you’ve ever tried to explain to your team that “we can’t create a new repo right now, I’m at dinner,” you understand why GitHub management should be code. Every infrastructure change in my homelab goes through code review — including how we manage GitHub itself.

The problem: GitHub’s web UI is fine for 3 repos, painful for 30+. You can’t track who changed what, can’t enforce naming conventions, and can’t ensure consistency across repositories.

The solution: treat your GitHub organization like database infrastructure. Define everything in YAML, let Terraform handle the drift, and sleep better at night.

Scale: This setup manages 40+ repositories across my organization with full configuration, teams, secrets, and custom properties.

All Terraform resources support lifecycle { create_before_destroy = true } for zero-downtime deployments.

Architecture

The github-management-plane repository manages my GitHub organization through Terraform — the same configuration-driven pattern as my homelab infrastructure:

  graph TB
    G[github-management-plane]
    R[Repository Module]
    S[Secrets/Variables Module]
    O[Organization Custom Properties]
    
    G --> R
    G --> S
    G --> O
    
    Repos["All Repositories"]
    Vars["Actions Variables"]
    Secs["Actions Secrets"]
    
    Repos --> tf-infra-homelab["tf-infra-homelab"]
    Repos --> tf-module-proxmox-talos["tf-module-proxmox-talos"]
    Repos --> applications-homelab["applications-homelab"]
    Repos --> ...["24+ repositories"]

What This Module Does

Repository management — create and configure all repositories via YAML
Team management — define teams and members
Organization custom properties — classify repositories
Actions secrets/variables — manage organization-wide secrets
Issue labels — standardize labels across repositories

Quick Start

module "repositories" {
  source   = "./modules/repository"
  for_each = local.filtered_repo_configurations
  
  configuration = each.value
  organization  = var.github_organization
}

Repository Management

All repositories are defined as YAML configurations:

# configurations/repository/tf-infra-homelab.yaml
name: tf-infra-homelab
description: A terraform infrastructure repository for managing my homelab environment
enabled: true
archived: false
visibility: private
type: terraform-infrastructure

topics:
  - homelab
  - proxmox

enabled_features:
  vulnerability_alerts: true
  issues: true
  wiki: false
  projects: false
  discussions: false

Repository Types

The module supports different repository types with defaults:

locals {
  repository_types = {
    terraform-infrastructure = {
      license_template = "mit"
      auto_init       = true
      topics        = ["terraform", "homelab"]
    }
    terraform-module = {
      license_template = "mit"
      auto_init       = true
      topics         = ["terraform", "proxmox"]
    }
    python-docker-application = {
      license_template = "mit"
      auto_init       = true
      topics         = ["python", "docker"]
    }
    generic = {
      auto_init = true
    }
  }
}

Repository Resource

resource "github_repository" "this" {
  name        = var.configuration.name
  description = var.configuration.description
  visibility  = var.configuration.visibility
  
  allow_rebase_merge    = true
  allow_squash_merge  = true
  delete_branch_on_merge = true
  
  vulnerability_alerts = var.configuration.enabled_features.vulnerability_alerts
  has_discussions     = var.configuration.enabled_features.discussions
  has_issues         = var.configuration.enabled_features.issues
  has_projects       = var.configuration.enabled_features.projects
  has_wiki           = var.configuration.enabled_features.wiki
}

Organization Custom Properties

Custom properties allow classification and filtering:

locals {
  organization_custom_properties = {
    "can-be-public" = {
      description   = "To indicate whether the repository can be made public"
      value_type  = "single_select"
      required   = true
      allowed_values = ["true", "false"]
      default_value = "false"
    }
    
    "managed-by" = {
      description = "To identify who manages the repository"
      value_type = "single_select"
      required = true
      allowed_values = [
        "github-management-plane",
        "manual-management",
      ]
      default_value = "manual-management"
    }
    
    "repository-type" = {
      description = "To indicate the type of repository"
      value_type = "single_select"
      required = true
      allowed_values = [
        "generic",
        "repository-template",
        "golang-linux-package",
        "golang-docker-application",
        "python-docker-application",
        "python-package",
        "terraform-infrastructure",
        "terraform-module",
      ]
    }
  }
}

Apply them:

resource "github_organization_custom_properties" "managed_properties" {
  for_each   = local.organization_custom_properties
  
  property_name = each.key
  value_type  = each.value.value_type
  required   = each.value.required
  description = each.value.description
  default_value = each.value.default_value
  allowed_values = each.value.allowed_values
}

Secrets and Variables

Actions secrets and variables are managed through Bitwarden:

# configurations/secrets_variables/global.yaml
variables:
  - name: RUNNER
    value: self-hosted
    visibility: all

secrets:
  - name: BWS_ACCESS_TOKEN
    is_manual: true
    visibility: private

Variable Resource

resource "github_actions_organization_variable" "managed_variables" {
  for_each = { for v in var.configuration.variables : v.name => v }
  
  variable_name = each.value.name
  visibility   = each.value.visibility
  value        = each.value.value
}

Secret Resource

For secrets, two patterns:

# Manual secrets (value set outside Terraform)
resource "github_actions_organization_secret" "managed_secrets_manual" {
  for_each = { for v in var.configuration.secrets : v.name => v if v.is_manual }
  
  secret_name = each.value.name
  visibility = each.value.visibility
  plaintext_value = "NONE"
}

# Synced secrets (from Bitwarden)
resource "github_actions_organization_secret" "managed_secrets_sync" {
  for_each = { for v in var.configuration.secrets : v.name => v if !v.is_manual }
  
  secret_name     = each.value.name
  visibility     = each.value.visibility
  plaintext_value = data.bitwarden-secrets_secret.secrets[each.value.name].value
}

Get secrets from Bitwarden:

data "bitwarden-secrets_secret" "secrets" {
  for_each = { for v in local.all_secrets : v.name => v if !v.is_manual }
  id      = each.value.bw_secret_id
}

Team Management

Teams are defined in the main module:

resource "github_team" "organization_administrators" {
  name        = "organization-administrators"
  description = "Team with administrative access to the organization"
  privacy     = "closed"
}

resource "github_team_members" "organization_administrators_members" {
  team_id = github_team.organization_administrators.id
  
  members = {
    "your-username" = {
      role = "maintainer"
    }
  }
}

Issue Labels

Labels are standardized across repositories:

locals {
  shared_labels = {
    "bug" = {
      color   = "d73a4a"
      description = "Bug report"
    }
    "enhancement" = {
      color   = "a2eeef"
      description = "New feature"
    }
    "documentation" = {
      color   = "0075ca"
      description = "Documentation improvements"
    }
  }
}

resource "github_issue_labels" "this" {
  repository = var.configuration.name
  
  label = merge(
    local.shared_labels,
    try(var.configuration.labels, {})
  )
}

My Repository Configuration

Here’s the list of repositories managed:

configurations/repository/
├── tf-infra-homelab.yaml          # Homelab infrastructure
├── tf-infra-github-management-plane.yaml  # GitHub management
├── tf-module-proxmox-lxc.yaml    # LXC module
├── tf-module-proxmox-vm.yaml    # VM module
├── tf-module-proxmox-talos.yaml  # Talos module
├── tf-module-proxmox-docker.yaml # Docker module
├── applications-homelab.yaml   # Kustomize apps
├── cf-worker-terraform-registry.yaml  # TF registry worker
├── cf-worker-apt-repository.yaml   # APT repository worker
├── template-terraform-basic.yaml   # Module template
├── template-cloudflare-worker-python.yaml  # Worker template
└── ... (24 total)

Each is just a YAML file — adding a new repository is adding a file.

Configuration Structure

github-management-plane/
├── configurations/
│   ├── repository/           # Repository definitions
│   ├── secrets_variables/   # Actions secrets/variables
│   └── rulesets/           # Branch protection (future)
├── modules/
│   ├── repository/         # Repository module
│   ├── secrets_variables/  # Secrets module
│   └── organization/        # Org properties module
├── main.tf                 # Orchestration
├── locals.tf              # Configuration loading
└── providers.tf          # Provider setup

This mirrors the homelab infrastructure structure.

Outputs

The module doesn’t have specific outputs since it manages the organization passively.

What’s Next

Branch protection rulesets — via rulesets API (when Terraform provider supports it)
Repository invitations — managing outside collaborators
Security advisories — automated security scanning

What Most People Get Wrong

“GitHub Terraform is just for repos” — It’s org-wide: teams, custom properties, secrets, variables. The whole thing.
“One Terraform run is enough” — Git rate limits apply. Use ratenode provider or caching.
“Manual changes are fine if you revert” — Terraform drift will catch you. Enable logento or run terraform refresh regularly.

When to Use / When NOT to Use

Use GitHub Management Plane	Do it manually
20+ repositories	1-5 repos
Team collaboration	Personal projects
Audit requirements	Quick experiments
Secret/variable management	Ad-hoc scripts only

This makes GitHub management declarative — every change goes through code review.

Self-Service Infrastructure with Backstage

Sat, 18 Apr 2026 00:00:00 +0000

Why Self-Service Matters

In my homelab, I was the bottleneck. Every new Kubernetes cluster meant:

  flowchart LR
    A[Create YAML] --> B[Find free IPs]
    B --> C[Configure node sizes]
    C --> D[Manually create Backstage catalog entries]
    D --> E[Open PR]
    E --> F[Wait for review]

That’s 6 steps where 4 could be automated.

The insight: infrastructure already defined as YAML. Backstage should consume that same YAML and generate its own catalog entries.

Real-world constraint: I deploy clusters infrequently (quarterly?), so I forget the steps. The templated approach ensures consistency whether I do this once a month or once a year.

This post covers the Backstage integration for homelab infrastructure. See the architecture overview for how it fits in the broader platform.

Two Integration Points

Backstage integrates with the homelab infrastructure in two ways:

Resource Catalog — auto-generated entities from infrastructure YAML configurations
Software Templates — scaffolder templates for self-service provisioning

  graph LR
    subgraph "Configuration"
        C[configurations/*.yaml]
    end
    
    subgraph "Generation"
        G[generate_backstage_catalog.py]
    end
    
    subgraph "Backstage"
        R[Resource Catalog]
        T[Software Templates]
    end
    
    C --> G
    G --> R
    G --> T

Auto-Generated Catalog

Running make backstage-catalog generates Backstage Resource entities from configurations:

make backstage-catalog
# ✓ kubernetes--prod-k8s.yaml (prod-k8s, disabled)
# ✓ kubernetes--dev-k8s.yaml (dev-k8s, disabled)
# ✓ docker--prod-docker-lxc.yaml (prod-docker-lxc, disabled)
# ✓ docker--dev-docker-lxc.yaml (dev-docker-lxc, enabled)

Generated Entity Example

Each generated YAML file is a Backstage Resource:

# backstage/catalog/kubernetes--prod-k8s.yaml
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: prod-k8s
  description: Talos kubernetes cluster configuration for production environment
  annotations:
    github.com/project-slug: your-org/your-infra-repo
    homelab.dev/configuration-file: configurations/kubernetes/prod-k8s.yaml
    homelab.dev/resource-type: kubernetes
    homelab.dev/schema-file: configuration_schemas/kubernetes.schema.yaml
    backstage.io/techdocs-entity: component:terraform-module-kubernetes
    homelab.dev/cluster-name: prod-k8s
    homelab.dev/talos-version: v1.12.4
    homelab.dev/kubernetes-version: v1.35.0
    homelab.dev/vip-address: 192.168.62.20
  labels:
    homelab.dev/enabled: 'false'
    homelab.dev/environment: prod
    homelab.dev/control-plane-count: '3'
    homelab.dev/worker-count: '3'
    homelab.dev/size-control_plane-cpu: '4'
    homelab.dev/size-control_plane-memory: '8192'
    homelab.dev/size-worker-cpu: '10'
    homelab.dev/size-worker-memory: '49152'
  tags:
    - disabled
    - kubernetes
    - prod
    - proxmox
    - talos
spec:
  type: kubernetes-cluster
  lifecycle: experimental
  owner: group:default/homelab-admins
  system: tf-infra-homelab
  dependsOn:
    - component:default/terraform-module-kubernetes

Docker Cluster Entity

# backstage/catalog/docker--prod-docker-lxc.yaml
apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: prod-docker-lxc
  description: Docker configuration on lxc for production environment
  annotations:
    github.com/project-slug: your-org/your-infra-repo
    homelab.dev/configuration-file: configurations/docker/prod-docker-lxc.yaml
    homelab.dev/resource-type: docker
    homelab.dev/cluster-name: prod-docker-lxc
    homelab.dev/cluster-type: lxc
    homelab.dev/vip-address: 192.168.61.20
  labels:
    homelab.dev/enabled: 'false'
    homelab.dev/environment: prod
    homelab.dev/worker-count: '3'
    homelab.dev/size-medium-cpu: '8'
    homelab.dev/size-medium-memory: '32768'
  tags:
    - disabled
    - docker
    - lxc
    - prod
    - proxmox
spec:
  type: docker-cluster
  lifecycle: experimental
  owner: group:default/homelab-admins
  system: tf-infra-homelab
  dependsOn:
    - component:default/terraform-module-docker

Metadata Extraction

The generation script extracts key metadata from configurations:

# scripts/generate_backstage_catalog.py

def extract_kubernetes_metadata(config: dict) -> dict:
    """Extract catalog-relevant metadata from a Kubernetes configuration."""
    annotations = {}
    labels = {}
    
    cluster = config.get("cluster", {})
    annotations["homelab.dev/cluster-name"] = cluster.get("name", "")
    
    talos = cluster.get("talos", {}) or {}
    annotations["homelab.dev/talos-version"] = talos.get("version", "")
    annotations["homelab.dev/kubernetes-version"] = cluster.get("kubernetes_version", "")
    
    cp_nodes = config.get("control_plane_nodes", {}).get("nodes", [])
    worker_nodes = config.get("worker_nodes", {}).get("nodes", [])
    labels["homelab.dev/control-plane-count"] = str(len(cp_nodes))
    labels["homelab.dev/worker-count"] = str(len(worker_nodes))
    
    cp_vip = config.get("control_plane_nodes", {}).get("vip", {})
    if cp_vip and cp_vip.get("enabled"):
        annotations["homelab.dev/vip-address"] = cp_vip.get("address", "")
    
    sizes = config.get("node_size_configuration", {})
    for size_name, size_spec in sizes.items():
        labels[f"homelab.dev/size-{size_name}-cpu"] = str(size_spec.get("cpu", ""))
        labels[f"homelab.dev/size-{size_name}-memory"] = str(size_spec.get("memory", ""))
    
    return {"annotations": annotations, "labels": labels}

This enables filtering in Backstage:

homelab.dev/environment=prod — production clusters
homelab.dev/enabled=true — currently deployed
homelab.dev/size-worker-memory=49152 — large workers

Catalog-Info Definition

The root catalog-info.yaml defines the domain, system, and components:

# Domain: homelab
apiVersion: backstage.io/v1alpha1
kind: Domain
metadata:
  name: homelab
  description: Self-hosted homelab infrastructure managed with Terraform and Proxmox
  annotations:
    backstage.io/techdocs-ref: dir:.
    github.com/project-slug: your-org/your-infra-repo
spec:
  owner: group:default/homelab-admins

---
# System: tf-infra-homelab
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: tf-infra-homelab
  description: Terraform-managed homelab infrastructure provisioning system
spec:
  owner: group:default/homelab-admins
  domain: homelab

---
# Component: terraform-module-kubernetes
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: terraform-module-kubernetes
  description: Terraform module for provisioning Kubernetes (Talos) clusters on Proxmox
spec:
  type: terraform-module
  lifecycle: production
  owner: group:default/homelab-admins
  system: tf-infra-homelab

---
# Location: discovers auto-generated resources
apiVersion: backstage.io/v1alpha1
kind: Location
metadata:
  name: tf-infra-homelab-resources
spec:
  targets:
    - ./backstage/catalog/*.yaml

Software Templates

The Backstage scaffolder templates enable self-service provisioning:

Kubernetes Template

# backstage/templates/kubernetes/template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: provision-kubernetes-cluster
  title: Provision Kubernetes Cluster
  description: Create a new Talos-based Kubernetes cluster configuration on Proxmox
  tags:
    - terraform
    - kubernetes
    - talos
    - proxmox
    - homelab
spec:
  owner: group:default/homelab-admins
  type: infrastructure
  system: tf-infra-homelab

Template Parameters

The template accepts parameters for cluster configuration:

parameters:
  - title: Cluster Identity
    required:
      - name
      - environment
    properties:
      name:
        title: Cluster Name
        type: string
        pattern: "^[a-z][a-z0-9-]+$"
      environment:
        title: Environment
        type: string
        enum:
          - dev
          - staging
          - prod

  - title: Cluster Configuration
    properties:
      talos_version:
        title: Talos Version
        type: string
        default: v1.12.4
      kubernetes_version:
        title: Kubernetes Version
        type: string
        default: v1.35.0
      disable_default_cni:
        title: Disable Default CNI
        type: boolean
        default: true

  - title: Control Plane Nodes
    properties:
      cp_count:
        title: Number of Control Plane Nodes
        type: integer
        minimum: 1
        maximum: 5
        default: 3
      cp_cpu:
        title: CPU Cores per CP Node
        type: integer
        default: 4
      cp_memory:
        title: Memory per CP Node (MB)
        type: integer
        default: 8192

  - title: Worker Nodes
    properties:
      worker_count:
        title: Number of Workers
        type: integer
        default: 3
      worker_cpu:
        title: CPU Cores per Worker
        type: integer
        default: 8
      worker_memory:
        title: Memory per Worker (MB)
        type: integer
        default: 16384

Template Steps

Each template has three steps:

steps:
  - id: generate
    name: Generate Configuration
    action: fetch:template
    input:
      url: ./skeleton/kubernetes
      targetPath: configurations/kubernetes
      values:
        name: ${{ parameters.name }}
        talos_version: ${{ parameters.talos_version }}
        cp_count: ${{ parameters.cp_count }}

  - id: generate-catalog
    name: Generate Backstage Catalog Entry
    action: fetch:template
    input:
      url: ./skeleton/backstage/catalog
      targetPath: backstage/catalog

  - id: publish
    name: Open Pull Request
    action: publish:github:pull-request
    input:
      repoUrl: github.com?repo=tf-infra-homelab&owner=your-org
      title: "feat: provision Kubernetes cluster ${{ parameters.name }}"

User Flow

In Backstage, users:

Choose template — “Provision Kubernetes Cluster”
Fill parameters — name, environment, node sizes
Submit — opens a PR automatically
Review — maintainers approve the PR
Apply — Terraform provisions the cluster

  sequenceDiagram
    participant User
    participant BS as Backstage
    participant GH as GitHub
    participant TF as Terraform
    participant PVE as Proxmox
    participant Talos
    participant Flux
    
    User->>BS: Create new cluster (fill form)
    BS->>GH: Open PR with config files
    Maintainer->>GH: Review and approve PR
    GH->>TF: Merge triggers apply
    TF->>PVE: Provision VMs
    PVE->>Talos: Bootstrap cluster
    Talos->>Flux: Install GitOps

Generation Script

The full script in scripts/generate_backstage_catalog.py:

#!/usr/bin/env python3
"""Generate Backstage catalog Resource entities from configuration YAML files."""

import yaml
from pathlib import Path

REPO_ROOT = Path(__file__).resolve().parent.parent

def load_yaml(path: Path) -> dict:
    return yaml.safe_load(path.read_text()) or {}

def build_resource_entity(resource_type, environment_name, config):
    """Build a Backstage Resource entity from configuration."""
    entity = {
        "apiVersion": "backstage.io/v1alpha1",
        "kind": "Resource",
        "metadata": {
            "name": config.get("name", environment_name),
            "description": config.get("description", ""),
            "annotations": {...},
            "labels": {...},
        },
        "spec": {
            "type": RESOURCE_TYPE_META[resource_type]["backstage_type"],
            "lifecycle": "experimental",
            "owner": "group:default/homelab-admins",
            "system": "tf-infra-homelab",
        },
    }
    return entity

def main():
    for config_file in (REPO_ROOT / "configurations").rglob("*.yaml"):
        config = load_yaml(config_file)
        entity = build_resource_entity(...)
        output_file.write_text(yaml.dump(entity))

Run via Makefile:

backstage-catalog:
  python3 scripts/generate_backstage_catalog.py

Filtering in Backstage

With the generated metadata, users can filter in Backstage:

Filter	Use Case
`homelab.dev/environment=prod`	Production clusters
`homelab.dev/enabled=true`	Currently deployed
`homelab.dev/control-plane-count=3`	Full quorum
`homelab.dev/size-worker-memory>=16384`	Large workers
`homelab.dev/talos-version=v1.12.*`	Specific Talos version

What Most People Get Wrong

“Backstage is only for Kubernetes” — It catalogs anything. My LXC, VMs, Docker clusters all have Backstage entries.
“Templates replace code review” — My templates generate PRs. Human review still happens. Self-service ≠ unattended.
“Catalog must be perfect at launch” — Start simple. The YAML-to-catalog pipeline can always regenerate.

When to Use / When NOT to Use

Use Backstage	Use direct Terraform
Team self-service	Single admin
10+ resources	<5 resources
Need catalog UI	CLI is enough

What’s Next

Current areas of exploration:

More templates — VM and LXC provisioning templates
Approval workflows — notification to maintainers
Status tracking — integration with Terraform Cloud state

The Backstage integration makes infrastructure self-serviceable while maintaining code review.