GitHub Actions IaC CI/CD Architecture

This CI/CD system is built around modular GitHub Actions & Workflows that are centralized to allow any repository to use them.

• Design Pattern: Automate Terraform Deployments: (1/2) Detect
• Design Pattern: Automate Terraform Deployments: (2/2) Process
• Grinntec GitHub Repo

---

It provides:

• Automatic detection of changed main.tf files
• Matrix processing for parallel validation of multiple files
• Complete Terraform validation pipeline:
  • Format checking, linting, validation
  • Planning with cost estimation
  • Security scanning with Checkov
  • Slack notifications
• Repository context awareness (PROD/DEV/STAGING/DEFAULT)
• Centralized action management with cross-repository compatibility

---

GitHub Structure

Central Organization Wide Repository

This repository hosts the centralized workflows and actions files consumed by the subscription repositories. This means you can modify or change one action file and all the deployments will use that change the next time they run. This is far easier than manually editing the same file multiple times which would be the case if you were to keep the workflows and action files on a per repository basis.

🏢
📁 CENTRALIZED REPOSITORY: grinntec-terraform-deployments-azure/.github
├── 📄 README.md
└── 📁 .github/
    ├── 📁 actions/                                         # Reusable Actions Library
    │   ├── 📁 cache-terraform-providers/                   # Cache Terraform providers
    │   ├── 📁 calculate-file/                              # Extract file paths & directories
    │   ├── 📁 checkov-security-scan/                       # Security scanning with Checkov
    │   ├── 📁 configure-git-private-modules/               # Setup Git for private modules
    │   ├── 📁 create-terraform-backend-config-file/        # Generate backend config
    │   ├── 📁 ensure-tf-lockfile-exists/                   # Ensure .terraform.lock.hcl exists
    │   ├── 📁 extract-tfvars/                              # Parse .tfvars files
    │   ├── 📁 read-ci-mode/                                # Determine plan/apply/destroy mode
    │   ├── 📁 slack-notify/                                # Send Slack notifications
    │   ├── 📁 terraform-apply/                             # Apply Terraform changes
    │   ├── 📁 terraform-cost-estimate/                     # Cost estimation with Infracost
    │   ├── 📁 terraform-destroy/                           # Destroy Terraform resources
    │   ├── 📁 terraform-fmt/                               # Format Terraform code
    │   ├── 📁 terraform-plan/                              # Plan Terraform changes
    │   ├── 📁 terraform-validate/                          # Validate Terraform syntax
    │   ├── 📁 tflint/                                      # Lint Terraform code
    │   └── 📁 archive/                                     # Archived/deprecated actions
    └── 📁 workflows/                                       # Reusable Workflows
        ├── 📄 detect-changed-tfvars-files-multi-repo.yaml  # Main orchestrator
        ├── 📄 process-changed-main-files.yaml              # Matrix processor

Azure Subscription Specific Repository

This is an example of a subscription repository. As the name suggests, it's targeted for a specific Azure subscription and is meant host IaC only for resources within that subscription. Credentials are created per subscription and applied at this level to limit the scope of access the GitHub Actions can perform. To use the centralized repository it requires a single Workflow that when triggered consumes the workflow and action files from the centralized repository.

🏗️
📁 SUBSCRIPTION REPOSITORY: grinntec-[environment]-subscription
├── 📄 README.md
├── 📄 .gitignore
├── 📁 .github/
│   └── 📁 workflows/
│       └── 📄 terraform-validation.yaml                    # Calls centralized workflow
├── 📁 [app-folder-0]/                                      # Azure Resource Groups
│   └── 📄 main.tf                                          # Terraform configuration
├── 📁 [app-folder-1]/
│   └── 📄 main.tf
├── 📁 [app-folder-2]/
│   └── 📄 main.tf
└── 📁 [app-folder-x]/
    └── 📄 main.tf

EXAMPLE SUBSCRIPTION REPOSITORIES NAMES:

📁 grinntec-prod-subscription               # 🟢 Production Environment
📁 grinntec-dev-subscription                # 🟡 Development Environment  
📁 grinntec-staging-subscription            # 🟠 Staging Environment
📁 grinntec-testing-subscription            # 🔵 Testing/Sandbox Environment

---

WORKFLOW EXECUTION FLOW:

1. Developer commits to subscription repo (e.g., grinntec-prod-subscription)
2. terraform-validation.yaml triggers in subscription repo
3. Calls centralized detect-changed-tfvars-files-multi-repo.yaml
4. Detects changed main.tf files and repository context
5. Creates matrix for parallel processing of changed files
6. Each matrix job calls process-changed-main-files.yaml
7. Executes complete validation pipeline using centralized actions:

   ├── 🔒 Azure Authentication (OIDC)
   ├── 📁 File & Directory Calculation  
   ├── 🎯 CI Mode Detection (plan/apply/destroy)
   ├── 🔐 Git Configuration for Private Modules
   ├── ⚡ Terraform Provider Caching
   ├── 🔧 Backend Configuration Generation
   ├── ✨ Terraform Format Check
   ├── 🧹 TFLint Analysis
   ├── ✅ Terraform Validation
   ├── 📋 Terraform Plan Generation
   ├── 🛡️ Checkov Security Scan
   ├── 💰 Infracost Cost Estimation
   ├── 🚀 Terraform Apply (if applicable)
   └── 📢 Slack Notifications

---

SECRETS ARCHITECTURE:

Why this split?

• Organization secrets: Same values across all subscription repositories
• Repository secrets: Subscription-specific values that isolate environments
• Security: Each repo can only deploy to its designated subscription
• Maintenance: Update tenant/slack once vs per-repo updates

Security Model

• OIDC Authentication – No static Azure credentials.
• Scoped Secrets – Only required secrets passed to jobs.
• Concurrency Control – Prevents overlapping runs for the same file.
• State Isolation – Backend config ensures environment separation.

🏢 ORGANIZATION-LEVEL (shared across all repos):
   ├── AZURE_TENANT_ID              # Azure AD tenant
   ├── AZURE_DEPLOY_TO_MODULE_RO    # GitHub token for private modules
   ├── INFRACOST_API_KEY            # Cost estimation API
   └── SLACK_WEBHOOK_URL            # Team notifications

🏗️ REPOSITORY-LEVEL (subscription-specific):
   ├── AZURE_CLIENT_ID              # Service principal for subscription
   └── AZURE_SUBSCRIPTION_ID        # Target Azure subscription

---

ENVIRONMENT DETECTION:

The centralized workflow automatically determines which Azure environment it's operating in based on the repository name, enabling environment-specific behavior without manual configuration.

Repository Name Pattern → Environment Mapping:
├── *prod*              # PROD
├── *dev*               # DEV  
├── *staging*|*stage*   # STAGING
└── other               # DEFAULT

ENVIRONMENT-SPECIFIC SECURITY:

• PROD: Could require additional approvals
• DEV: Allow auto-apply for faster iteration
• STAGING: Require manual approval before apply
• DEFAULT: Safe sandbox mode (plan-only)

DIFFERENTIATED WORKFLOWS:

• PROD: Full security scans + cost alerts
• DEV: Faster validation, skip expensive checks
• STAGING: Production-like validation
• DEFAULT: Basic validation for testing

TARGETED NOTIFICATIONS:

• PROD: Alert leadership + ops team
• DEV: Notify development team only
• STAGING: QA team notifications
• DEFAULT: Individual developer alerts

COST MANAGEMENT:

• PROD: Strict cost thresholds & alerts
• DEV: Relaxed limits for experimentation
• STAGING: Medium cost controls
• DEFAULT: Basic cost awareness

---