Install

Set up the Terraform Plan GitHub Action in your repository and post your first plan comment to a Pull Request.

Prerequisites

Before installing the Terraform Plan GitHub Action, ensure you have:

  • An existing Terraform project in a GitHub repository
  • Terraform installed (version 1.0 or higher recommended)
  • AWS credentials configured (via OIDC or access keys)
  • GitHub Actions enabled for your repository

Required permissions

The workflow running this action needs specific permissions to function correctly. Add these to your workflow file:

permissions:
  contents: read        # Required to read repository contents
  pull-requests: write  # Required to post comments on PRs

If you're using AWS OIDC authentication (recommended), you'll also need:

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

1) Create the workflow file

Create a new workflow file at .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 }}

2) Replace placeholder values

Update the following values in your workflow file:

  • IAM Role ARN: Replace arn:aws:iam::123456789012:role/GitHubActionsRole with your actual GitHub Actions IAM role ARN. If you don't have one set up yet, check out our guide on configuring OpenID Connect for GitHub in AWS CDK.
  • AWS Region: Change us-east-1 to your target AWS region if different.
  • Branch: Adjust the branches filter if your default branch isn't main.
  • Terraform version: If you need a specific Terraform version, add the terraform_version input to the setup-terraform step.

3) Test the action

Create a test Pull Request that modifies your Terraform infrastructure:

  1. Create a new branch: git checkout -b test-terraform-plan
  2. Make a change to one of your Terraform resources
  3. Commit and push: git push origin test-terraform-plan
  4. Open a Pull Request against your main branch

The action will run automatically and post a comment with the Terraform plan output. The comment will show:

  • Resources to be added (if any)
  • Resources to be changed (if any)
  • Resources to be destroyed (if any)
  • A summary of all planned changes

4) Verify the output

Check your Pull Request for a new comment from the GitHub Actions bot. The comment should contain:

  • A header identifying the plan
  • The AWS region (if configured)
  • Formatted sections for each type of change
  • A summary of all infrastructure changes

If there are no infrastructure changes, the action will skip posting a comment to keep your PR conversations clean (when using the empty output conditionally).

Try it out

Want to experiment without setting up your own workflow? Check out the AWS Terraform Starter Kit. It's a production-ready Terraform template with this workflow already configured. Fork it, open a Pull Request with infrastructure changes, and see the action in action.

Next steps

Best practices

Workflow organization

  1. Separate concerns: Keep plan generation and deployment in separate workflows
  2. Use reusable workflows: Create organization-level reusable workflows for consistency
  3. Use binary plan files: Always generate a binary plan file with -out=tfplan.binary for accurate change detection
  4. Enable parallel execution: Use job matrices or parallel jobs when possible

Security considerations

  1. Use OIDC over access keys: Always prefer AWS OIDC for authentication
  2. Minimize token permissions: Only grant required permissions to GitHub tokens
  3. Protect sensitive data: Never expose AWS account IDs or role ARNs in public repos
  4. Secure state files: Ensure Terraform state files are stored securely (e.g., S3 with encryption)
  5. Audit trail: Enable CloudTrail logging for all Terraform operations

Performance optimization

  1. Cache dependencies: Use actions/cache for Terraform providers and modules
  2. Parallel environments: Run multi-environment plans in parallel
  3. Conditional execution: Skip unnecessary steps with if conditions
  4. Artifact reuse: Share plan artifacts between jobs instead of regenerating

Maintenance strategies

  1. Pin action versions: Use specific versions (@v1) instead of @main. Check the GitHub Marketplace for the latest stable release.
  2. Monitor workflow runs: Set up alerts for failed workflows
  3. Regular updates: Keep the action and dependencies updated
  4. Document customizations: Add comments explaining custom configurations

Troubleshooting

Comment not posting

Symptoms: Workflow succeeds but no comment appears on the PR.

Solutions:

  • Verify pull-requests: write permission is set
  • Check that the workflow is triggered on pull_request events
  • Ensure the planfile path is correct
  • Verify the GitHub token has appropriate permissions

Plan output looks malformed

Symptoms: Comment shows raw text instead of formatted sections.

Solutions:

  • Ensure you're using a binary plan file generated with -out=tfplan.binary
  • Check that the plan file actually contains Terraform plan output
  • Verify the file isn't empty
  • Make sure terraform init ran successfully before the plan

Multiple comments on the same PR

Symptoms: Multiple comments appear instead of updating the existing one.

Solutions:

  • Use consistent header values across workflow runs
  • Don't change the header between commits on the same PR
  • Check that the action version is consistent

AWS authentication failures

Symptoms: Cannot assume IAM role or access AWS resources.

Solutions:

  • Verify the IAM role ARN is correct
  • Check the trust relationship allows your GitHub repository
  • Ensure id-token: write permission is set
  • Validate the OIDC identity provider configuration

Terraform init failures

Symptoms: Terraform init fails before generating the plan.

Solutions:

  • Verify backend configuration is correct
  • Check AWS credentials have permissions to access state bucket
  • Ensure all required Terraform variables are set
  • Validate provider configurations

Performance issues

Symptoms: Workflow takes too long to complete.

Solutions:

  • Enable Terraform provider caching
  • Use job matrices for parallel execution
  • Cache Terraform plugins and modules
  • Consider reducing the number of resources or splitting into smaller stacks

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

← OverviewUsage Examples →