terraform.yml

# =============================================================================
# Terraform CI/CD Pipeline
# =============================================================================
#
# PIPELINE STAGES:
#
#   ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
#   │  Lint &   │───▶│ Security │───▶│  Plan    │──┬▶│ Apply    │───▶│ Apply    │    │ Infracost│
#   │  Format   │    │ (Checkov)│    │ (matrix) │  │ │  DEV     │    │  PROD    │    │ Cost Est │
#   └──────────┘    └──────────┘    └──────────┘  │ └──────────┘    └──────────┘    └──────────┘
#        PR              PR              PR        │  merge only    merge + gate    └── PR only
#
# RELEASE LIFECYCLE:
#   1. Developer pushes to feature branch and opens a PR
#   2. Lint job checks formatting (terraform fmt) and runs TFLint
#   3. Security job runs Checkov static analysis on all Terraform files
#   4. Plan jobs run in parallel for dev and prod (matrix strategy)
#   5. Plan output is posted as a PR comment for team review
#   6. On merge to main:
#      a. Dev environment auto-applies (fast feedback)
#      b. Prod requires manual approval via GitHub Environment protection
#
# REQUIRED SECRETS:
#   ARM_CLIENT_ID       - Azure Service Principal App ID
#   ARM_CLIENT_SECRET   - Azure Service Principal Password
#   ARM_SUBSCRIPTION_ID - Azure Subscription ID
#   ARM_TENANT_ID       - Azure AD Tenant ID
#
# REQUIRED GITHUB ENVIRONMENTS:
#   dev        - No protection rules (auto-deploy)
#   production - Required reviewers + wait timer (manual approval)
#
# =============================================================================

name: "Terraform CI/CD"

on:
  push:
    branches: [main, master]
    paths:
      - "modules/**"
      - "environments/**"
      - ".github/workflows/**"
      - ".tflint.hcl"
      - ".checkov.yml"
  pull_request:
    branches: [main, master]
    paths:
      - "modules/**"
      - "environments/**"
      - ".github/workflows/**"
      - ".tflint.hcl"
      - ".checkov.yml"

permissions:
  contents: read
  pull-requests: write
  id-token: write
  security-events: write

env:
  TF_VERSION: "1.7.0"
  TF_IN_AUTOMATION: "true"
  ARM_CLIENT_ID: ${{ secrets.ARM_CLIENT_ID }}
  ARM_CLIENT_SECRET: ${{ secrets.ARM_CLIENT_SECRET }}
  ARM_SUBSCRIPTION_ID: ${{ secrets.ARM_SUBSCRIPTION_ID }}
  ARM_TENANT_ID: ${{ secrets.ARM_TENANT_ID }}
  ARM_ACCESS_KEY: ${{ secrets.ARM_ACCESS_KEY }}

# ---------------------------------------------------------------------------
# JOBS
# ---------------------------------------------------------------------------
jobs:

  # =========================================================================
  # Stage 1: Lint & Format Check
  # =========================================================================
  # Runs on every PR and push to main.
  # Ensures all .tf files are properly formatted and pass TFLint rules.
  # This is the first gate — fails fast before heavier jobs run.
  # =========================================================================
  lint:
    name: "Lint & Format"
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}

      - name: Check formatting
        run: terraform fmt -check -recursive -diff

      - name: Setup TFLint
        uses: terraform-linters/setup-tflint@v4
        with:
          tflint_version: latest

      - name: Init TFLint plugins
        run: tflint --init --config=.tflint.hcl

      - name: Lint VNET module
        run: tflint --config=../../.tflint.hcl
        working-directory: modules/vnet

      - name: Lint dev environment
        run: tflint --config=../../.tflint.hcl
        working-directory: environments/dev

      - name: Lint prod environment
        run: tflint --config=../../.tflint.hcl
        working-directory: environments/prod

  # =========================================================================
  # Stage 2: Security Scan (Checkov)
  # =========================================================================
  # Runs Checkov static analysis against all Terraform configurations.
  # Checks for security misconfigurations such as:
  #   - Storage accounts without encryption
  #   - VMs with password authentication
  #   - Key Vaults without purge protection
  #   - Missing network restrictions
  #   - Overly permissive NSG rules
  #
  # Results are uploaded as SARIF to GitHub Security tab.
  # Soft-fail is enabled so findings are reported but don't block the pipeline.
  # =========================================================================
  security:
    name: "Security Scan (Checkov)"
    runs-on: ubuntu-latest
    needs: lint
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Run Checkov on VNET module
        uses: bridgecrewio/checkov-action@v12
        with:
          directory: modules/vnet
          framework: terraform
          config_file: .checkov.yml
          output_format: cli,sarif
          output_file_path: console,checkov-module.sarif
          soft_fail: true
          quiet: true

      - name: Run Checkov on dev environment
        uses: bridgecrewio/checkov-action@v12
        with:
          directory: environments/dev
          framework: terraform
          config_file: .checkov.yml
          output_format: cli,sarif
          output_file_path: console,checkov-dev.sarif
          soft_fail: true
          quiet: true

      - name: Run Checkov on prod environment
        uses: bridgecrewio/checkov-action@v12
        with:
          directory: environments/prod
          framework: terraform
          config_file: .checkov.yml
          output_format: cli,sarif
          output_file_path: console,checkov-prod.sarif
          soft_fail: true
          quiet: true

      - name: Upload Checkov SARIF to GitHub Security
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: checkov-module.sarif
          category: checkov-module

  # =========================================================================
  # Stage 3: Terraform Plan (per environment)
  # =========================================================================
  # Uses a matrix strategy to plan dev and prod in parallel.
  # On PRs, the plan output is posted as a comment for reviewers.
  # This lets the team see exactly what will change before approving.
  # =========================================================================
  plan:
    name: "Plan - ${{ matrix.environment }}"
    runs-on: ubuntu-latest
    needs: [lint, security]
    strategy:
      fail-fast: false
      matrix:
        environment: [dev, prod]
    defaults:
      run:
        working-directory: environments/${{ matrix.environment }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}

      - name: Terraform Init
        run: terraform init

      - name: Terraform Validate
        run: terraform validate

      - name: Terraform Plan
        id: plan
        run: terraform plan -no-color -out=${{ matrix.environment }}.tfplan
        continue-on-error: true

      - name: Post plan output to PR comment
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const output = `### Terraform Plan — \`${{ matrix.environment }}\` ${{ steps.plan.outcome == 'success' && '✅' || '❌' }}

            <details><summary>Show Plan</summary>

            \`\`\`
            ${{ steps.plan.outputs.stdout }}
            \`\`\`

            </details>

            *Pushed by: @${{ github.actor }}, Action: \`${{ github.event_name }}\`*`;

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: output
            });

      - name: Fail if plan failed
        if: steps.plan.outcome == 'failure'
        run: exit 1

  # =========================================================================
  # Stage 3b: Infracost Cost Estimation (PR only)
  # =========================================================================
  # Shows the cost impact of infrastructure changes as a PR comment.
  # Compares the cost of the current branch against the base branch.
  # Requires INFRACOST_API_KEY secret (free tier: https://infracost.io).
  # =========================================================================
  cost:
    name: "Cost Estimate"
    runs-on: ubuntu-latest
    needs: plan
    if: github.event_name == 'pull_request' && vars.INFRACOST_ENABLED == 'true'
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Infracost
        uses: infracost/actions/setup@v3
        with:
          api-key: ${{ secrets.INFRACOST_API_KEY }}

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}

      - name: Infracost breakdown (dev)
        run: |
          cd environments/dev
          terraform init -backend=false
          cd ../..
          infracost breakdown \
            --path environments/dev \
            --format json \
            --out-file /tmp/infracost-dev.json

      - name: Infracost breakdown (prod)
        run: |
          cd environments/prod
          terraform init -backend=false
          cd ../..
          infracost breakdown \
            --path environments/prod \
            --format json \
            --out-file /tmp/infracost-prod.json

      - name: Combine Infracost outputs
        run: |
          infracost output \
            --path "/tmp/infracost-dev.json" \
            --path "/tmp/infracost-prod.json" \
            --format json \
            --out-file /tmp/infracost-combined.json

      - name: Post Infracost comment
        run: |
          infracost comment github \
            --path /tmp/infracost-combined.json \
            --repo ${{ github.repository }} \
            --github-token ${{ secrets.GITHUB_TOKEN }} \
            --pull-request ${{ github.event.pull_request.number }} \
            --behavior update

  # =========================================================================
  # Stage 4: Apply Dev (automatic on merge)
  # =========================================================================
  # Triggered only on push to main (i.e., after PR merge).
  # Uses the "dev" GitHub Environment (no protection rules).
  # This gives immediate feedback on whether changes work in a real env.
  # =========================================================================
  apply-dev:
    name: "Apply - dev"
    runs-on: ubuntu-latest
    needs: plan
    if: (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master') && github.event_name == 'push'
    environment: dev
    defaults:
      run:
        working-directory: environments/dev
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}

      - name: Terraform Init
        run: terraform init

      - name: Terraform Apply
        run: terraform apply -auto-approve

  # =========================================================================
  # Stage 5: Apply Prod (manual approval gate)
  # =========================================================================
  # Runs after dev succeeds. Requires manual approval through the
  # "production" GitHub Environment (configured with required reviewers).
  # This is the final safety gate before changes reach production.
  # =========================================================================
  apply-prod:
    name: "Apply - prod"
    runs-on: ubuntu-latest
    needs: apply-dev
    if: (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master') && github.event_name == 'push'
    environment: production
    defaults:
      run:
        working-directory: environments/prod
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ env.TF_VERSION }}

      - name: Terraform Init
        run: terraform init

      - name: Terraform Apply
        run: terraform apply -auto-approve