How to Use Terraform with GitHub Actions for Infrastructure Automation

Use GitHub Actions to automate Terraform commands by creating a workflow YAML file that runs terraform init, terraform plan, and terraform apply. Store your Terraform code in the repository and configure secrets for cloud credentials to enable secure deployments.

Syntax

A GitHub Actions workflow for Terraform typically includes these steps:

• Trigger: Defines when the workflow runs, e.g., on push or pull request.
• Jobs: Defines the tasks to run, usually on a Linux runner.
• Steps: Commands executed in order, such as checking out code, setting up Terraform, initializing, planning, and applying.
• Environment variables and secrets: Used to securely pass cloud provider credentials.

yaml

name: Terraform Workflow

on:
  push:
    branches:
      - main

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: '1.5.6'

      - name: Terraform Init
        run: terraform init

      - name: Terraform Plan
        run: terraform plan

      - name: Terraform Apply
        if: github.ref == 'refs/heads/main'
        run: terraform apply -auto-approve

Example

This example shows a complete GitHub Actions workflow that automates Terraform deployment on every push to the main branch. It checks out the code, sets up Terraform version 1.5.6, runs terraform init, terraform plan, and applies changes automatically.

yaml

name: Terraform CI/CD

on:
  push:
    branches:
      - main

jobs:
  terraform:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: '1.5.6'

      - name: Terraform Init
        run: terraform init

      - name: Terraform Plan
        run: terraform plan

      - name: Terraform Apply
        if: github.ref == 'refs/heads/main'
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: terraform apply -auto-approve

Output

Terraform has been successfully initialized!

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  + create

Plan: 1 to add, 0 to change, 0 to destroy.

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Common Pitfalls

Common mistakes when using Terraform with GitHub Actions include:

• Not storing cloud credentials securely in GitHub Secrets, risking exposure.
• Running terraform apply on pull requests, which can cause unwanted changes.
• Missing terraform init step, causing commands to fail.
• Not locking Terraform version, leading to inconsistent runs.

Always use if: github.ref == 'refs/heads/main' to restrict applies to main branch only.

yaml

name: Terraform Workflow

on:
  pull_request:
    branches:
      - main

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: '1.5.6'
      - run: terraform init
      - run: terraform plan
      # Wrong: applying on PR
      - run: terraform apply -auto-approve

# Correct approach:
# Add condition to apply only on main branch push

name: Terraform Workflow

on:
  push:
    branches:
      - main

jobs:
  terraform:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: hashicorp/setup-terraform@v2
        with:
          terraform_version: '1.5.6'
      - run: terraform init
      - run: terraform plan
      - if: github.ref == 'refs/heads/main'
        run: terraform apply -auto-approve

Quick Reference

Tips for using Terraform with GitHub Actions:

• Use actions/checkout@v3 to get your code.
• Use hashicorp/setup-terraform@v2 to install Terraform.
• Store cloud credentials in GitHub Secrets and reference them as environment variables.
• Run terraform init before plan or apply.
• Use conditions to run terraform apply only on protected branches.

Key Takeaways

Automate Terraform commands in GitHub Actions by creating a workflow with init, plan, and apply steps.

Securely store cloud credentials in GitHub Secrets and pass them as environment variables.

Run terraform apply only on main or protected branches to avoid unintended changes.

Use hashicorp/setup-terraform action to install a consistent Terraform version.

Always include terraform init before plan or apply to prepare the working directory.