Usage Examples

Practical workflow examples for the Terraform Plan GitHub Action, from simple single-environment setups to reusable workflow patterns.

These examples show different ways to integrate the Terraform Plan GitHub Action into your workflows. Start with the direct usage example, then explore reusable patterns as your needs grow.

Want to see these in action? The AWS Terraform Starter Kit has a working workflow you can fork and test immediately.

1. Direct Usage

The simplest setup that covers most use cases. Runs Terraform plan and posts the result directly to each Pull Request.

name: Terraform Plan and Comment on PR

on:
  pull_request:
    branches:
      - main

permissions:
  pull-requests: write
  contents: read

jobs:
  plan-and-comment:
    name: Run Terraform Plan and Post PR Comment
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v5

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3

      - name: Terraform Init
        run: terraform init

      - name: Terraform Plan
        run: terraform plan -out=tfplan.binary

      - name: Post Terraform Plan Comment in PR
        uses: towardsthecloud/terraform-plan-pr-commenter@v1
        with:
          planfile: tfplan.binary
          aws-region: us-east-1

What this does:

  1. Triggers on Pull Requests targeting main
  2. Checks out the repository
  3. Sets up Terraform
  4. Initializes the configuration
  5. Generates a binary plan file
  6. Posts the formatted plan as a PR comment

Key detail: Using -out=tfplan.binary creates a binary plan file, which the action can parse accurately for change detection.

2. Reusable Workflow

When you're running the same workflow across multiple repositories, reusable workflows help you maintain consistency and reduce duplication.

Step 1: Create the Reusable Workflow

Create .github/workflows/terraform-plan-comment.yml:

name: Reusable Terraform Plan PR Comment

on:
  workflow_call:
    inputs:
      planfile:
        description: 'Path to the Terraform plan file'
        type: string
        required: true
      working-directory:
        description: 'Terraform working directory'
        type: string
        required: true
      aws-region:
        description: 'AWS Region where resources will be deployed'
        type: string

jobs:
  comment-terraform-plan:
    name: Post Terraform Plan as PR Comment
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v5

      - name: Download Plan Artifact
        uses: actions/download-artifact@v5
        with:
          name: terraform-plan-artifact
          path: ${{ inputs.working-directory }}

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3

      - name: Terraform Init
        run: terraform init -backend=false
        working-directory: ${{ inputs.working-directory }}

      - name: Post Terraform Plan Comment in PR
        uses: towardsthecloud/terraform-plan-pr-commenter@v1
        with:
          planfile: ${{ inputs.planfile }}
          working-directory: ${{ inputs.working-directory }}
          aws-region: ${{ inputs.aws-region }}

Step 2: Call It From Your Main Workflow

Create or update .github/workflows/terraform-plan.yml:

name: Terraform Plan with Artifact Upload

on:
  pull_request:
    branches:
      - main

jobs:
  plan-infrastructure:
    name: Generate and Upload Terraform Plan
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v5

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3

      - name: Terraform Init
        run: terraform init
        working-directory: ./infrastructure

      - name: Terraform Plan
        run: terraform plan -out=tfplan.binary
        working-directory: ./infrastructure

      - name: Upload Plan Artifact
        uses: actions/upload-artifact@v5
        with:
          name: terraform-plan-artifact
          path: ./infrastructure/tfplan.binary
          retention-days: 1

  post-plan-comment:
    needs: plan-infrastructure
    # For same-repo, use: ./.github/workflows/terraform-plan-comment.yml
    # For cross-repo, use: your-org/your-repo/.github/workflows/terraform-plan-comment.yml@main
    uses: ./.github/workflows/terraform-plan-comment.yml
    with:
      planfile: tfplan.binary
      working-directory: ./infrastructure
      aws-region: us-east-1

Why use reusable workflows?

  • Separation of concerns - AWS auth stays in the generating job, PR commenting in another
  • Different permissions - Jobs can have exactly the permissions they need
  • Artifact sharing - Pass the plan file between jobs
  • Centralized logic - Update once, apply everywhere
  • Composable - Combine with deployment workflows easily

Tips for Both Patterns

Binary plan files: Always use -out=tfplan.binary to create a binary plan file. The action reads this file using terraform show for accurate change detection.

Working directory: If your Terraform files are in a subdirectory (like ./infrastructure), use the working-directory input and make sure to run terraform init and terraform plan in the same directory.

Init without backend: In reusable workflows, use terraform init -backend=false since you're just parsing the plan file, not accessing state.

For more options, check the Configuration reference for all available inputs and outputs.

← InstallConfiguration →