cascadeguard-org

GitHub organisation configuration as code for the CascadeGuard org.

Managed via Terraform + the GitHub Provider. YAML files are the source of truth; a thin HCL layer applies them.

How it works

repos.yaml / teams.yaml / members.yaml   ← edit these
        │
        ▼
   terraform/*.tf   (yamldecode glue)
        │
        ▼
  GitHub API  (via Terraform GitHub Provider)

• PRs: terraform plan runs automatically and posts the diff as a PR comment.
• Merge to main: terraform apply runs automatically.

Prerequisites

Before the first run, complete these one-time steps:

1. Terraform Cloud workspace

1. Create a free account at app.terraform.io.
2. Create an organisation named cascadeguard.
3. Create a workspace named cascadeguard-org (CLI-driven mode).
4. Generate a Terraform Cloud API token and store it as a GitHub Actions secret named TF_API_TOKEN.

2. GitHub token

Create a GitHub PAT (or GitHub App installation token) with admin:org scope. Store it as a GitHub Actions secret named ORG_ADMIN_TOKEN.

3. Import existing resources

After cloning and running terraform init, import existing resources so Terraform doesn’t try to recreate them:

cd terraform
export TF_VAR_github_token="<your-token>"
terraform init
bash import.sh
terraform plan   # should show no changes

Editing

Add or update a repository

Edit repos.yaml:

repos:
  my-new-repo:
    description: "What this repo does"
    visibility: public      # or private
    default_branch: main
    archived: false
    topics: [security, containers]
    branch_protection:
      main:
        required_reviews: 1
        dismiss_stale_reviews: true
        require_status_checks: true
        status_checks:
          - "ci / test"

Open a PR — the plan will show exactly what changes.

Add a team

Edit teams.yaml:

teams:
  engineering:
    description: "Core engineering team"
    privacy: closed
    repos:
      cascadeguard: push
      cascadeguard-app: push

Add an org member

Edit members.yaml:

members:
  github-username:
    role: member   # or owner

Local development

cd terraform
export TF_VAR_github_token="<your-token>"
terraform init
terraform plan

Security notes

• cascadeguard-org is private — it controls access to all other repos.
• The ORG_ADMIN_TOKEN has broad org permissions; rotate it periodically.
• Terraform state is stored encrypted in Terraform Cloud.
• All org changes require a PR review before applying.