Usage Examples

Learn how to incorporate the Terraform Plan GitHub Action into your Terraform project workflows with practical examples for direct usage and reusable workflows.

Overview

This page provides practical examples showing how to integrate the Terraform Plan GitHub Action into your Terraform project's GitHub workflows. Each example demonstrates a different pattern, from simple direct usage to reusable workflows for DRY patterns.

Use these examples as starting points and adapt them to your specific infrastructure and team requirements. All examples follow best practices for permissions configuration.

Want a working example? Check out the AWS Terraform Starter Kit. It's a production-ready Terraform template with the GitHub Action already built into the workflow. Clone it to see how everything works together in a real project.

Example 1: Direct Usage in Workflow

The simplest setup runs Terraform plan and posts the result directly to your 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

This workflow:

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

Example 2: Reusable Workflow Call

Create a reusable workflow for DRY patterns across your repository or organization.

First, 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 }}

Then call this workflow from your main Terraform workflow:

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
    uses: ./.github/workflows/terraform-plan-comment.yml
    with:
      planfile: tfplan.binary
      working-directory: ./infrastructure
      aws-region: us-east-1

Benefits:

  • Separates plan generation from PR commenting
  • Useful when different jobs need different permissions
  • Allows artifact reuse between jobs
  • Can be combined with deployment workflows
  • Centralized logic for consistency

For best practices, troubleshooting, and maintenance strategies, check out the Install guide.

← InstallConfiguration →