Install

In this guide, you'll set up the Terraform Plan GitHub Action and post your first plan comment to a Pull Request. Takes about 10 minutes.

Requirements

Before you start, make sure you have:

How It Works

Here's what the workflow does:

Permissions

Your workflow needs these permissions:

permissions:
  contents: read        # Read repository contents
  pull-requests: write  # Post comments on PRs

Using AWS OIDC authentication (recommended)? Add id-token: write:

permissions:
  contents: read
  id-token: write       # Required for AWS OIDC authentication
  pull-requests: write

Step 1: Create the Workflow File

Create .github/workflows/terraform-plan.yml in your repository:

name: Terraform Plan on Pull Request

on:
  pull_request:
    branches:
      - main

jobs:
  post-terraform-plan-comment:
    name: Post Terraform Plan Comment to PR
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
      pull-requests: write
    env:
      AWS_REGION: us-east-1

    steps:
      - name: Checkout Repository
        uses: actions/checkout@v5
        with:
          ref: ${{ github.event.pull_request.head.sha }}

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

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
          aws-region: ${{ env.AWS_REGION }}

      - name: Terraform Init
        run: terraform init

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

      - name: Post Terraform Plan Comment
        uses: towardsthecloud/terraform-plan-pr-commenter@v1
        with:
          planfile: tfplan.binary
          aws-region: ${{ env.AWS_REGION }}

Step 2: Update Placeholder Values

Replace these values in your workflow:

Don't have an IAM role for GitHub Actions yet? Check out the guide on configuring OpenID Connect for GitHub in AWS CDK. The same approach works for Terraform projects.

Using a specific Terraform version? Add the terraform_version input:

- name: Setup Terraform
  uses: hashicorp/setup-terraform@v3
  with:
    terraform_version: "1.7.0"

Step 3: Test It

1. Create a branch: git checkout -b test-terraform-plan
2. Make a change to one of your Terraform resources
3. Push and open a PR: git push origin test-terraform-plan
4. Watch the action run and check for the plan comment

The comment shows:

• Resources to add (if any)
• Resources to change (if any)
• Resources to destroy (if any)
• A summary of all planned changes

Try Before You Set Up

Want to see it work before configuring your own repo? Fork the AWS Terraform Starter Kit. It has this workflow pre-configured. Open a PR with infrastructure changes and watch the action run.

Best Practices

Workflow Organization

• Separate concerns - Keep plan generation and apply in separate workflows
• Use reusable workflows - Centralize your workflow logic for consistency across repos
• Use binary plan files - Always generate with -out=tfplan.binary for accurate change detection
• Enable parallelism - Use job matrices when running multiple environment plans

Security

• Use OIDC over access keys - Short-lived credentials are more secure
• Minimize permissions - Only grant what the workflow actually needs
• Protect sensitive data - Don't expose account IDs or role ARNs in public repos
• Secure state files - Ensure Terraform state is stored securely (S3 with encryption)
• Enable CloudTrail - Audit all Terraform operations

Performance

• Cache providers - Use actions/cache for Terraform providers and modules
• Run environments in parallel - Don't sequence what can run concurrently
• Use conditional execution - Skip steps that don't apply with if conditions

Maintenance

• Pin action versions - Use @v1 instead of @main for stability
• Set up alerts - Get notified when workflows fail
• Keep dependencies updated - Regularly update the action and Terraform version
• Document customizations - Comment any non-standard configurations

Troubleshooting

Comment not appearing

What you see: Workflow succeeds but no comment on the PR.

Check these:

• pull-requests: write permission is set
• Workflow triggers on pull_request events
• planfile path matches your actual output file
• GitHub token has correct permissions

Plan output looks wrong

What you see: Comment shows raw text instead of formatted sections.

Check these:

• Using a binary plan file generated with -out=tfplan.binary
• File actually contains Terraform plan output
• File isn't empty
• terraform init ran successfully before the plan

Multiple comments on same PR

What you see: New comment appears instead of updating the existing one.

Check these:

• Using consistent header values across workflow runs
• Not changing the header between commits
• Action version is the same across runs

AWS authentication fails

What you see: Cannot assume IAM role or access AWS resources.

Check these:

• IAM role ARN is correct
• Trust relationship allows your GitHub repository
• id-token: write permission is set
• OIDC identity provider is configured in AWS

Terraform init fails

What you see: Terraform init fails before generating the plan.

Check these:

• Backend configuration is correct
• AWS credentials have permissions to access state bucket
• All required Terraform variables are set
• Provider configurations are valid

Workflow runs slow

What you see: Takes too long to complete.

Try these:

• Enable Terraform provider caching
• Use job matrices for parallel execution
• Cache Terraform plugins and modules
• Consider splitting into smaller configurations

What's Next

• Configuration reference - All available inputs and outputs
• Usage examples - Reusable workflows and artifact patterns
• CloudBurn App - Add cost analysis to your Terraform plans

Need more help? Check the GitHub Marketplace page or the source repository for issues and discussions.