SCM Control Plane Terraform Catalog

Control plane for SCM org/repo governance and cloud deployment identity (OIDC), managed as code. This repository provides Terraform modules and example stacks using a catalog-driven workflow.

Contributor workflows (local checks, pre-commit hooks, and repo development guidance) are documented in CONTRIBUTING.md.

Architecture At A Glance

flowchart LR
  subgraph G[GitHub]
    ORG[GitHub Org]
    REPO[Repository]
    ENV[Repository Environments]
    ACT[GitHub Actions]
    ORG --> REPO --> ENV
    ENV --> ACT
  end

  subgraph C[Catalog + Terraform]
    CATALOG[Catalog YAMLs\nrepos / envs / slug ledgers / OIDC mappings]
    STACK[Example Stacks]
    MODS[Terraform Modules]
    CATALOG --> STACK --> MODS
  end

  subgraph A[AWS]
    OIDC[AWS IAM OIDC Provider]
    ROLE[IAM Roles]
    POL[IAM Policies]
    OIDC --> ROLE --> POL
  end

  ACT -- OIDC token --> OIDC
  MODS --> OIDC
  MODS --> ROLE
  MODS --> POL

Loading

What This Repository Manages

• Organization settings through modules/github_org_settings.
• Repository lifecycle through modules/github_repo_platform.
• Repository environments, environment secrets, and environment variables through modules/github_repo_platform.
• AWS IAM OIDC providers through modules/aws_github_oidc_provider.
• AWS IAM roles and policies for GitHub Actions through modules/aws_github_actions_oidc_roles.
• Catalog-based onboarding, where YAML files define repository and environment intent.

Resource Coverage

• Organization settings: github_organization_settings.
• Repository lifecycle: github_repository.
• Repository environments: github_repository_environment.
• Environment secrets: github_actions_environment_secret.
• Environment variables: github_actions_environment_variable.
• AWS OIDC providers: aws_iam_openid_connect_provider.
• AWS IAM role-based access: aws_iam_role, aws_iam_policy, and aws_iam_role_policy_attachment.

Environment configuration model:

• repositories.<repo>.shared_environment_secrets and repositories.<repo>.shared_environment_variables apply to all environments in a repository.
• secrets_overrides and variables_overrides apply environment-specific overrides.
• New environments inherit shared values automatically.

Catalog loading model:

• Example stacks load YAML definitions using fileset(...) + yamldecode(...).
• Repositories are onboarded by adding or updating catalog files instead of editing module wiring.
• OIDC providers, repository IAM roles, and repository naming slug ledgers are onboarded the same way.

Quick Start

Prerequisites:

• Terraform CLI
• Access to a GitHub token with appropriate org/repo permissions
• Backend configuration values for S3 + DynamoDB state locking

1. Enter an example stack:

cd examples/github_repo_platform/single-org
# or
cd examples/github_repo_platform/multi-org

Org settings stacks:

cd examples/github_org_settings/single-org
# or
cd examples/github_org_settings/multi-org

2. Copy example inputs and backend config:

cp terraform.tfvars.example terraform.tfvars
cp backend.hcl.example backend.hcl

3. Edit both files with real values (org names, tokens, state bucket/table).
4. Initialize and plan:

terraform init -backend-config=backend.hcl
terraform validate
terraform plan

Examples are documented in examples/README.md and in each example directory under examples/**/README.md.

Catalog-Driven Onboarding Workflow

• Example stacks are catalog-driven and load YAML from catalog/ directories.
• Onboard or update resources by editing the relevant catalog files, then running Terraform in the matching example stack.
• See examples/README.md for example layout and detailed catalog paths by module.
• See docs/architecture/scaling-catalogs-and-iam-patterns.md for scaling guidance beyond a few repos.
• See docs/policy-bundles/README.md for reusable IAM policy bundle reference patterns.

Operations And Migration Playbooks

• Import existing resources into Terraform state: docs/playbooks/import-existing-github-resources.md.
• Import existing AWS OIDC/IAM resources into Terraform state: docs/playbooks/import-existing-aws-oidc-resources.md.
• GitHub Actions variable/secret setup reference: docs/playbooks/import-existing-github-resources.md#github-actions-configuration-reference.
• Technical Decision Records (architecture/design rationale): docs/tdr/README.md.
• Scaling guidance (catalogs and IAM patterns): docs/architecture/scaling-catalogs-and-iam-patterns.md.
• Policy bundle reference patterns: docs/policy-bundles/README.md.
• Release process and versioning guidance: docs/releases/README.md.
• Changelog: CHANGELOG.md.

Contributing

Contributor setup, local validation workflows, and pre-commit hooks are documented in CONTRIBUTING.md.

Automation Layout

• End-user automation workflow templates live in templates/workflows/.
• Copy templates into your own repository's .github/workflows/ to run them.

Security Notes

• .tfvars are ignored by git.
• Keep GitHub tokens out of version control.
• Review terraform plan output before apply.