Infrastructure-as-Code 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.

Terraform-Driven Homelab Architecture

Sun, 15 Mar 2026 00:00:00 +0000

The Problem Space

Homelabs evolve. You start with one Docker container, add some LXCs, then Kubernetes, and suddenly your infrastructure is a house of cards held together by scripts you wrote two years ago and don’t remember.

This architecture solves that through:

Everything in code — from VM provisioning to Kubernetes bootstrap
Versioned modules — each update is a code review opportunity
Self-service via Backstage — templated provisioning, no Slack threads

Numbers: 3 Proxmox nodes, 2 production clusters (Docker Swarm + Talos K8s), ~50 resources defined across 24+ YAML configurations.

Running in production:

3 Proxmox nodes (alpha, charlie, foxtrot)
Docker Swarm clusters with Keepalived HA
Talos Kubernetes clusters with Flux GitOps
GPU passthrough for hardware acceleration
Multi-network topology (dmz + vmbr1)
Private container registry (Harbor)
Private Terraform registry (Cloudflare Workers)

Start with the basic template. All custom modules derive from it — maintaining consistency across the infrastructure.

Module Hierarchy

  graph TB
    subgraph "Root Module"
        A[tf-infra-homelab]
    end
    
    subgraph "Compute Modules"
        B[tf-module-proxmox-lxc]
        C[tf-module-proxmox-vm]
        D[tf-module-proxmox-talos]
        E[tf-module-proxmox-docker]
    end
    
    subgraph "Application Layer"
        F[applications-homelab]
    end
    
    subgraph "Platform"
        G[Proxmox VE]
    end
    
    A --> B
    A --> C
    A --> D
    A --> E
    D --> F
    E --> F
    B --> G
    C --> G
    D --> G
    E --> G

Module	Purpose
terraform-basic-template	Foundation for all modules
tf-module-proxmox-lxc	LXC container provisioning
tf-module-proxmox-vm	Full VM provisioning
tf-module-proxmox-docker	Docker Swarm clusters
tf-module-proxmox-talos	Talos Kubernetes clusters
tf-infra-homelab	Root orchestration
applications-homelab	Kustomize deployments
github-management-plane	GitHub org management

The Dependency Graph

  graph TB
    T[terraform-basic-template]
    L[tf-module-proxmox-lxc]
    V[tf-module-proxmox-vm]
    DT[tf-module-proxmox-docker]
    TT[tf-module-proxmox-talos]
    RH[tf-infra-homelab]
    AH[applications-homelab]
    P[ProxmoxVE]
    
    T --> L
    T --> V
    L --> DT
    V --> DT
    L --> TT
    V --> TT
    DT --> RH
    TT --> RH
    RH --> P
    DT --> AH
    TT --> AH

Key observations:

Template is foundational — all modules derive from the same template
LXC and VM are leaf modules — no dependencies on other custom modules
Docker and Talos are composite — build on LXC/VM modules
Root module is orchestrational — composes modules based on configurations
Applications deploy post-provisioning — GitOps ties into Docker/Talos clusters

Configuration-Driven

All infrastructure is defined in YAML configurations, not ad-hoc Terraform runs:

configurations/
├── docker/
│   ├── dev-docker-lxc.yaml
│   └── prod-docker-lxc.yaml
├── kubernetes/
│   ├── dev-k8s.yaml
│   └── prod-k8s.yaml
└── virtual_machine/
    └── ...

Each config has an enabled flag for gradual rollout:

name: prod-k8s
enabled: true  # Set to false to disable without deletion

cluster:
  name: prod-k8s
  datastore:
    id: nas
    node: alpha

What’s Running

Cluster	Type	Nodes	VIP	Purpose
prod-docker-lxc	Docker Swarm	3x medium (8vCPU/32GB)	192.168.61.20	Container workloads
prod-k8s	Talos K8s	3x CP (4vCPU/8GB) + 3x worker (10vCPU/48GB)	192.168.62.20	Kubernetes workloads

Both clusters span all 3 Proxmox nodes for high availability.

Design Principles

This architecture follows specific principles:

Principle	Implementation
Single configuration object	All modules use unified `configuration` input
Host pools	Resilience through multi-node distribution
Versioned modules	Each module has explicit versions
YAML configurations	Infrastructure as data, not ad-hoc apply
Private registry	Distribution without Terraform Cloud cost
Secrets integration	Bitwarden for credential storage
GitOps	Flux bootstrapped during cluster creation
Multi-network	Separate DMZ and backend networks
GPU passthrough	Device mapping in host pool

What Most People Get Wrong

“More modules = better architecture” — I started with 10+ modules. Consolidated to 5. Over-modularization creates maintenance overhead.
“YAML = Terraform” — Terraform is the engine, YAML is the fuel. Don’t embed YAML in .tf files; load from external files.
“GitOps replaces Terraform” — They work together: Terraform provisions, Flux manages apps. Both are declarative.

Each component has its own detailed post:

Post	Focus
Talos Kubernetes on Proxmox	tf-module-proxmox-talos deep dive — image factory, machine config, bootstrap
Docker Swarm on Proxmox	tf-module-proxmox-docker deep dive — Keepalived HA, provisioning
LXC & VM Modules	tf-module-proxmox-lxc + tf-module-proxmox-vm basics
Backstage Integration	Catalog generation, software templates
Private Terraform Registry	Module distribution via Cloudflare Workers
GitHub Management Plane	Managing GitHub org via Terraform

Private Terraform Registry on Cloudflare Workers

Fri, 20 Feb 2026 00:00:00 +0000

The Alternatives

When you need to share Terraform modules across projects:

Option	Cost	Complexity	Trade-off
Terraform Cloud	$20+/month	Low	Free tier doesn’t support custom modules
Nexus/Artifactory	Free	High	Java-based, heavy for this use case
Custom (this)	Free	Medium	Implement registry protocol yourself

The killer: Terraform Cloud’s free tier doesn’t support private module registries. You need the paid plan. For homelab use, that’s 10x the cost.

What this handles: service discovery, version listing, download URL redirects, and zipball proxy — the full registry protocol.

Worker Endpoints

Endpoint	Purpose
`/.well-known/terraform.json`	Service discovery — tells Terraform where the API lives
`/v1/modules/:ns/:name/:provider/versions`	Lists available versions (from GitHub tags)
`/v1/modules/:ns/:name/:provider/:version/download`	Returns the download URL
`/archive/:ns/:name/:provider/:version`	Proxies the actual module download

The Implementation

Let me walk through the actual code. The worker is written in Python using Pyodide, which means full CPython 3.12 in WebAssembly.

Service Discovery

async def handle_well_known(req, env):
    """Handle /.well-known/terraform.json"""
    response = {
        "modules.v1": f"{env.get('BASE_URL', 'https://terraform.example.com')}/v1/modules/"
    }
    return json_response(response)

Simple enough — returns a JSON object telling Terraform where to find the modules API.

Version Listing

This is where things get interesting. I needed to fetch GitHub tags and filter for valid semver:

def filter_semver_tags(tags: list[str]) -> list[str]:
    """Filter tags to only valid semver versions."""
    valid_tags = []
    for tag in tags:
        if _SEMVER_RE.match(tag):
            valid_tags.append(tag)
    return sorted(valid_tags, key=parse_version, reverse=True)

# Semver pattern from actual implementation
_SEMVER_RE = re.compile(r"^v?\d+\.\d+\.\d+(?:[.+-].+)?$")

The regex ensures only proper semver tags (v1.0.0, 2.3.1, etc.) are returned. Prerelease versions like v1.0.0-beta are supported too.

Authentication: The GitHub App Dance

Here’s where it gets clever. Instead of requiring users to generate GitHub tokens, the worker handles authentication server-side using a GitHub App:

class GitHubAppAuth:
    def __init__(self, app_id: str, private_key: str, installation_id: str):
        self.app_id = app_id
        self.private_key = private_key
        self.installation_id = installation_id
        self._token_cache = None
        self._token_expiry = 0

    async def get_token(self) -> str:
        """Get cached installation token, refreshing if needed."""
        now = time.time()
        if self._token_cache and now < self._token_expiry:
            return self._token_cache
        
        # Generate JWT and exchange for token
        jwt = self._generate_jwt()
        token = await self._exchange_jwt_for_token(jwt)
        
        # Cache for 55 minutes (tokens last 60, safe margin)
        self._token_cache = token
        self._token_expiry = now + 3300
        return token

    def _generate_jwt(self) -> str:
        """Create signed JWT using RS256."""
        # ... WebCrypto implementation

The worker generates a JWT signed with the GitHub App’s private key, exchanges it for an Installation Access Token, and caches that token for 55 minutes. This avoids rate limiting and keeps things snappy.

Design Considerations

Why Server-Side Auth?

The alternative would be API tokens in .terraformrc. But that means:

Users need to generate tokens
Tokens expire and need refreshing
You’re exposing long-lived credentials

With server-side GitHub App auth, Terraform just talks to your worker — no credentials needed on the client side.

Token Caching Strategy

# Using Cloudflare's Cache API for cross-request caching
cache = caches.default
cache_key = f"gh-token-{installation_id}"
cached = await cache.get(cache_key)

if cached:
    token = cached.text
else:
    token = await github_app.get_token()
    # Cache for 55 minutes
    response = Response.new(token, headers={
        "Cache-Control": "max-age=3300"
    })
    await cache.put(cache_key, response)

This is critical because GitHub rate limits would hit hard without caching.

Download URL Handling

Terraform expects the download endpoint to return a X-Terraform-Get header with the location of the actual module archive. I point it back to my worker:

async def handle_module_download(req, env, ns, name, provider, version):
    # Return redirect to archive endpoint
    archive_url = f"/archive/{ns}/{name}/{provider}/{version}"
    return Response.new("", headers={
        "X-Terraform-Get": archive_url
    })

Then the archive endpoint fetches from GitHub’s zipball URL and streams it through.

Constraints and Limits

This isn’t a “run anything anywhere” solution. There are real constraints:

Constraint	Value	Implication
CPU Time	30s (Paid) / 10ms (Free)	Complex auth may timeout on free tier
Memory	128 MB	Enough for Python + JSON parsing
Packages	Pyodide stdlib only	No external dependencies

Terraform Cloud’s free tier doesn’t support private module registries. You need the paid plan.

On-Prem Deployment with workerd

Here’s the part that makes this interesting for self-hosted scenarios: these workers can run locally using workerd, Cloudflare’s Workers runtime as a container.

# docker-compose.yml for local workerd
services:
  workerd:
    image: cloudflare/workerd:latest
    ports:
      - "8787:8787"
    volumes:
      - ./config.workerd:/etc/workerd/config.capnp
    environment:
      - PORT=8787

// config.workerd (JavaScript service binding syntax)
services: [
  {
    name: "terraform-registry",
    script: readFile("dist/worker.js"),
    bindings: {
      GITHUB_APP_ID: "123456",
      GITHUB_INSTALLATION_ID: "789012",
    }
  }
]

This means you can:

Develop and test workers locally
Run the same code on Cloudflare’s edge
Deploy on-prem for air-gapped environments
Use identical infrastructure everywhere

Usage Example

With everything configured, using the registry is straightforward:

# main.tf
module "proxmox_vm" {
  source  = "registry.example.com/namespace/tf-module-proxmox-vm/proxmox"
  version = "1.0.7"

  configuration = {
    name        = "web-server"
    node_name   = "pve1"
    cpu = { cores = 2, type = "host" }
    memory = { dedicated = 4096 }
  }
}

And the CLI configuration:

# ~/.terraformrc
host "registry.example.com" {
  services = {
    "modules.v1" = "https://registry.example.com/v1/modules/"
  }
}

No credentials needed — the worker handles everything server-side.

What Most People Get Wrong

“Free tier has no limits” — 10ms CPU time free, 30s paid. Complex auth on free tier may timeout.
“Pyodide supports all Python packages” — No. ~150 bundled, no arbitrary pip install. Use WebCrypto via JavaScript instead.
“One worker does everything” — For high traffic, add caching. GitHub API rate limits (5K/hour) apply.

When to Use / When NOT to Use

Use Private Registry	Use Terraform Cloud
Free tier budget	Team with >5 users
10-50 modules	100+ modules
Simple requirements	Policy enforcement needed
Air-gapped capable	Cloud-hosted required

What’s Next

This pattern — serverless registry with on-prem fallback — has proven so useful I’ve applied it to APT repositories, which I’ll cover in the next post. The same architecture, different protocol, same benefits.

This pattern can be adapted to your own infrastructure by implementing the Terraform Module Registry Protocol on any serverless or traditional hosting platform.

Infrastructure-as-Code on zharif.my

GitHub Organization as Code with Terraform

Why This Matters

Architecture

What This Module Does

Quick Start

Repository Management

Repository Types

Repository Resource

Organization Custom Properties

Secrets and Variables

Variable Resource

Secret Resource

Team Management

Issue Labels

My Repository Configuration

Configuration Structure

Outputs

What’s Next

What Most People Get Wrong

When to Use / When NOT to Use

Terraform-Driven Homelab Architecture

The Problem Space

Module Hierarchy

The Dependency Graph

Configuration-Driven

What’s Running

Design Principles

What Most People Get Wrong

Related Posts

Private Terraform Registry on Cloudflare Workers

The Alternatives

Worker Endpoints

The Implementation

Service Discovery

Version Listing

Authentication: The GitHub App Dance

Design Considerations

Why Server-Side Auth?

Token Caching Strategy

Download URL Handling

Constraints and Limits

On-Prem Deployment with workerd

Usage Example

What Most People Get Wrong

When to Use / When NOT to Use

What’s Next