🏗️ GitHub Organization Terraform Template

Manage your GitHub organization's repositories as code using Terraform and YAML configuration.

Note: See gjed/github-configs-public for a public example of this template in action.

✨ Features

• YAML-based configuration - Human-readable repository definitions
• Configuration groups - Share settings across multiple repositories (DRY)
• Repository rulesets - Enforce branch protection and policies
• GitHub Actions permissions - Control which actions can run and workflow permissions
• Webhook management - Configure CI/CD and notification webhooks as code
• Subscription-aware - Gracefully handles GitHub Free tier limitations
• Onboarding script - Easily import existing repositories

How It Works

                                    ┌─────────────────────┐
                                    │       GitHub        │
                                    │                     │
┌─────────────────┐                 │  ┌──────────────┐   │
│ repositories.yml│                 │  │ tf-modules   │   │
│                 │                 │  └──────────────┘   │
│ - tf-modules    │    Terraform    │  ┌──────────────┐   │
│ - api-gateway   │ ──────────────> │  │ api-gateway  │   │
│ - docs-site     │                 │  └──────────────┘   │
│                 │                 │  ┌──────────────┐   │
└─────────────────┘                 │  │ docs-site    │   │
                                    │  └──────────────┘   │
                                    └─────────────────────┘

🚀 Quick Start

# 1. Use this template on GitHub, then clone your repository

# 2. Set your GitHub token
export GITHUB_TOKEN="your_github_token"

# 3. Configure and apply
make init && make plan && make apply

See the Quick Start Guide for detailed setup instructions.

🔧 Example Configuration

# config/repositories.yml
terraform-modules:
  description: "Shared Terraform modules"
  groups: ["base", "oss"]
  topics: ["terraform"]

api-gateway:
  description: "Internal API gateway"
  groups: ["base", "internal"]

docs-site:
  description: "Documentation website"
  groups: ["base", "oss"]
  homepage_url: "https://docs.example.com"
  webhooks:
    - slack-notify        # Reference webhook from config/webhook/

📚 Documentation

Documentation is available in the Wiki:

• Quick Start Guide - Get up and running
• Configuration Reference - All available options
• Customization Guide - Extend the template
• Examples - Common configuration patterns
• Troubleshooting - Common issues and solutions

Note: The wiki is available as a git submodule in the wiki/ directory for local access.

📋 Requirements

• Terraform >= 1.0
• GitHub Personal Access Token with repo and admin:org scopes

⚡ Commands

make init      # Initialize Terraform
make plan      # Preview changes
make apply     # Apply changes
make validate  # Validate configuration

💳 GitHub Subscription Tiers

Feature	Free	Pro	Team	Enterprise
Public repo rulesets	Yes	Yes	Yes	Yes
Private repo rulesets	No	Yes	Yes	Yes
Push rulesets	No	No	Yes	Yes
Actions permissions	Yes	Yes	Yes	Yes

The template automatically skips unsupported features based on your subscription tier.

🔒 GitHub Actions Security Best Practices

GitHub Actions permissions can significantly impact your supply chain security. This template supports comprehensive Actions configuration at both organization and repository levels.

Configuration Options

Organization Level (config/config.yml):

actions:
  enabled_repositories: all         # all, none, selected
  allowed_actions: selected         # all, local_only, selected
  allowed_actions_config:
    github_owned_allowed: true      # Allow github/* actions
    verified_allowed: true          # Allow verified marketplace actions
    patterns_allowed:
      - "actions/*"
      - "your-org/*"
  default_workflow_permissions: read  # read, write
  can_approve_pull_request_reviews: false

Repository Level (config/repositories.yml or config/groups.yml):

my-repo:
  actions:
    enabled: true
    allowed_actions: selected
    allowed_actions_config:
      github_owned_allowed: true
      verified_allowed: true
      patterns_allowed:
        - "actions/*"

Security Recommendations

1. Use selected allowed_actions - Restrict which actions can run to reduce supply chain risk
2. Default to read workflow permissions - Only grant write access when explicitly needed
3. Disable PR approval for workflows - Prevent automated bypassing of review requirements
4. Use group inheritance - Define secure defaults in groups that repositories inherit
5. Pin action versions - Use SHA or version tags in patterns_allowed (e.g., actions/checkout@v4)

⚖️ License

Apache 2.0