Terraform CI/CD

You are a DevOps engineer setting up automated Terraform deployment pipelines. The user wants to configure GitHub Actions and Atlantis for Terraform plan/apply workflows with pull request integration.

What to check first

• Verify Terraform files exist in repository root or terraform/ directory with terraform init successful
• Check GitHub repository has Actions enabled and webhook permissions configured
• Confirm you have GitHub Personal Access Token (PAT) with repo and workflow scopes for Atlantis webhook setup
• Validate Atlantis server has network access to GitHub and proper OAuth app credentials registered

Steps

1. Create .github/workflows/terraform.yml with terraform fmt, terraform validate, and terraform plan jobs triggered on pull requests
2. Add Atlantis configuration file atlantis.yaml at repository root defining Terraform project structure and workflows
3. Configure GitHub organization/repository webhook pointing to Atlantis server URL with secret token matching Atlantis config
4. Set up GitHub Actions secrets: TF_API_TOKEN, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY (or equivalent cloud provider credentials)
5. Deploy Atlantis server (Docker container or Kubernetes) with GitHub token, webhook secret, and Terraform backend configured
6. Add pull request comment trigger rules in atlantis.yaml using autoplan and apply_requirements to control when Terraform runs
7. Test workflow by creating a sample branch, modifying a .tf file, and opening pull request to verify plan appears in comments
8. Configure branch protection rules requiring Atlantis plan approval before merge and dismissing stale reviews on new pushes

Code

# .github/workflows/terraform.yml
name: Terraform CI/CD
on:
  pull_request:
    paths:
      - 'terraform/**'
      - '.github/workflows/terraform.yml'
  push:
    branches:
      - main
    paths:
      - 'terraform/**'

env:
  TF_VERSION: 1.6.0
  TERRAFORM_DIR: terraform

jobs:
  terraform:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4

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

      - name: Terraform Format Check
        run: terraform fmt -check -recursive ${{ env.TERRAFORM_DIR }}
        continue-on-error: true

      - name: Terraform Init
        run: terraform -chdir=${{ env.TERRAFORM_DIR }} init -backend=false

      - name: Terraform Validate
        run: terraform -chdir=${{ env.TERRAFORM_DIR }} validate

      - name: Terraform Plan
        id: plan
        run: terraform -chdir=${{ env.TERRAFORM_DIR }} plan -no-color -out=tfplan
        env:

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change