Feature: Example CI/CD workflows in ci/ folder

[gjed]

Summary

Add a collection of example GitHub Actions workflows in a ci/ folder that users can copy to .github/workflows/.

Problem

The template currently lacks CI/CD examples. Users need to:

• Create their own Terraform workflows
• Figure out best practices for plan/apply
• Set up proper security for state and secrets

Proposed Solution

Create a ci/ folder with ready-to-use workflow examples:

ci/
├── README.md                    # Overview and usage instructions
├── workflows/
│   ├── terraform-pr.yml         # Plan on PR, comment results
│   ├── terraform-apply.yml      # Apply on merge to main
│   ├── terraform-scheduled.yml  # Scheduled drift detection
│   ├── validate.yml             # Validate YAML and Terraform
│   └── release.yml              # Semantic release workflow
├── actions/
│   └── setup-terraform/         # Composite action for common setup
│       └── action.yml
└── examples/
    ├── with-terraform-cloud.yml
    ├── with-s3-backend.yml
    ├── with-gcs-backend.yml
    └── with-azure-backend.yml

Example: terraform-pr.yml

name: Terraform PR

on:
  pull_request:
    paths:
      - 'config/**'
      - 'terraform/**'

permissions:
  contents: read
  pull-requests: write

jobs:
  plan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: "1.5"
      
      - name: Terraform Init
        run: terraform init
        working-directory: terraform
        env:
          GITHUB_TOKEN: ${{ secrets.GH_TERRAFORM_TOKEN }}
      
      - name: Terraform Validate
        run: terraform validate
        working-directory: terraform
      
      - name: Terraform Plan
        id: plan
        run: terraform plan -no-color -out=plan.out
        working-directory: terraform
        env:
          GITHUB_TOKEN: ${{ secrets.GH_TERRAFORM_TOKEN }}
        continue-on-error: true
      
      - name: Comment PR
        uses: actions/github-script@v7
        with:
          script: |
            const plan = `${{ steps.plan.outputs.stdout }}`;
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `## Terraform Plan\n\n\`\`\`terraform\n${plan}\n\`\`\``
            });

Example: terraform-apply.yml

name: Terraform Apply

on:
  push:
    branches: [main]
    paths:
      - 'config/**'
      - 'terraform/**'

concurrency:
  group: terraform-apply
  cancel-in-progress: false

jobs:
  apply:
    runs-on: ubuntu-latest
    environment: production  # Requires approval
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
      
      - name: Terraform Init
        run: terraform init
        working-directory: terraform
      
      - name: Terraform Apply
        run: terraform apply -auto-approve
        working-directory: terraform
        env:
          GITHUB_TOKEN: ${{ secrets.GH_TERRAFORM_TOKEN }}

Tasks

• Create ci/ folder structure
• Implement terraform-pr.yml workflow
• Implement terraform-apply.yml workflow
• Implement terraform-scheduled.yml for drift detection
• Implement validate.yml workflow
• Add backend-specific examples (S3, GCS, Azure, TFC)
• Create composite action for common setup
• Write comprehensive README
• Update main docs to reference ci/ folder

Documentation

The ci/README.md should cover:

• How to use the workflows
• Required secrets and permissions
• Backend configuration options
• Security best practices
• Customization guide