Feature: Configuration drift detection

[gjed]

Summary

Add tooling to detect when GitHub repository settings have been manually changed outside of Terraform (configuration drift).

Problem

Even with Terraform managing repositories, users can make manual changes through:

• GitHub UI
• GitHub CLI
• Other API calls
• GitHub Apps

These changes create drift between the actual state and the desired configuration, potentially:

• Weakening security policies
• Creating inconsistencies
• Causing unexpected Terraform plan outputs

Proposed Solution

1. Drift Detection Script

Create a script that compares current GitHub state vs YAML configuration:

# scripts/detect-drift.sh
./scripts/detect-drift.sh

# Output:
# Repository: my-repo
#   DRIFT: visibility changed (private -> public)
#   DRIFT: branch protection disabled on main
#   OK: description matches
#
# Repository: another-repo
#   OK: no drift detected

2. Terraform Plan Analysis

Enhanced Terraform plan output that highlights unexpected changes:

make drift-check
# Runs: terraform plan -detailed-exitcode
# Parses output to categorize changes

3. GitHub Action for Scheduled Checks

# .github/workflows/drift-detection.yml
name: Drift Detection
on:
  schedule:
    - cron: '0 8 * * *'  # Daily at 8am
  workflow_dispatch:

jobs:
  detect:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
      - name: Detect Drift
        run: |
          terraform init
          terraform plan -detailed-exitcode -out=plan.out
        continue-on-error: true
      - name: Report Drift
        if: failure()
        run: ./scripts/report-drift.sh plan.out
      - name: Notify
        if: failure()
        # Send notification (Slack, email, issue creation)

4. Drift Report Output

Generate reports in multiple formats:

• Terminal output (colored diff)
• Markdown (for PR comments)
• JSON (for programmatic use)
• GitHub Issue (auto-create issues for drift)

Tasks

• Create drift detection script
• Add Terraform plan parsing for drift analysis
• Create GitHub Action workflow template
• Add notification integrations (Slack, email)
• Add auto-remediation option (terraform apply)
• Documentation

Configuration

# config/config.yml
drift_detection:
  enabled: true
  schedule: "0 8 * * *"
  notify:
    slack_webhook: env:SLACK_WEBHOOK
    create_issues: true
  auto_remediate: false  # Dangerous, disabled by default
  ignore_fields:
    - pushed_at
    - updated_at

Related

This pairs well with a CI workflow that runs terraform plan on schedule.