Inputs & Outputs

Quick Reference

Use these tables for a quick overview of all available inputs and outputs. Scroll down for detailed explanations and examples.

Inputs

Outputs

Inputs Explained

Below you'll find detailed explanations for each input parameter, including usage examples, best practices, and common use cases.

planfile

Required: Yes Type: String Description: Path to the Terraform plan file to post as a comment in the Pull Request.

The file should be a binary plan file generated with terraform plan -out=<filename>. This ensures accurate change detection and allows the action to read the plan details.

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

Important notes:

• Use a binary plan file (not text output) for best results
• The action will read this file using terraform show
• Make sure terraform init is run before generating the plan

Example:

- uses: towardsthecloud/terraform-plan-pr-commenter@v1
  with:
    planfile: tfplan.binary

terraform-cmd

Required: No Type: String Default: terraform Description: Command to execute for calling the Terraform binary.

This is useful when you need to use a wrapper script, a specific Terraform version, or an alternative Terraform distribution like OpenTofu.

Example with Terragrunt:

- uses: towardsthecloud/terraform-plan-pr-commenter@v1
  with:
    planfile: tfplan.binary
    terraform-cmd: terragrunt

Example with specific path:

- uses: towardsthecloud/terraform-plan-pr-commenter@v1
  with:
    planfile: tfplan.binary
    terraform-cmd: /usr/local/bin/terraform

Common use cases:

• Using Terragrunt instead of Terraform
• Using OpenTofu instead of Terraform
• Using a custom wrapper script for Terraform
• Specifying a full path to the Terraform binary

working-directory

Required: No Type: String Default: . Description: Directory where the Terraform binary should be called.

Use this when your Terraform configuration files are in a subdirectory of your repository, or when you have multiple Terraform modules in different directories.

Example:

- uses: towardsthecloud/terraform-plan-pr-commenter@v1
  with:
    planfile: tfplan.binary
    working-directory: ./infrastructure

Example with nested directories:

- uses: towardsthecloud/terraform-plan-pr-commenter@v1
  with:
    planfile: tfplan.binary
    working-directory: ./environments/production

Important notes:

• The planfile path is relative to the working-directory
• Make sure to run terraform init and terraform plan in the same directory
• The action will execute terraform show in this directory

token

Required: No Type: String Default: ${{ github.token }} Description: The GitHub or Personal Access Token (PAT) to use for posting comments to Pull Requests.

The default github.token works for most cases. Use a custom PAT if you need elevated permissions or cross-repository access.

Example with custom token:

- uses: towardsthecloud/terraform-plan-pr-commenter@v1
  with:
    planfile: tfplan.binary
    token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}

When to use a custom token:

• Posting comments from a bot account
• Cross-repository workflows
• Organizations with strict token policies

Setup: Add your custom token as a repository secret in Settings > Secrets and variables > Actions.

header

Required: No Type: String Description: Set a custom header to use for the Pull Request comment.

This is particularly useful when running multiple Terraform plan comments in the same PR for different environments or modules. The action uses the header to identify and update the correct comment.

Example:

- uses: towardsthecloud/terraform-plan-pr-commenter@v1
  with:
    planfile: dev-plan.binary
    header: "Dev Environment"
    aws-region: us-east-1

- uses: towardsthecloud/terraform-plan-pr-commenter@v1
  with:
    planfile: prod-plan.binary
    header: "Production Environment"
    aws-region: eu-west-1

Without a custom header:

Terraform Plan Results

With a custom header:

Terraform Plan Results - Dev Environment

aws-region

Required: No Type: String Description: The AWS region where the infrastructure changes are being applied (e.g., us-east-1, eu-west-1).

When provided, the region is displayed in the PR comment header to help teams understand which AWS region the changes will affect.

Example:

- uses: towardsthecloud/terraform-plan-pr-commenter@v1
  with:
    planfile: tfplan.binary
    aws-region: us-east-1

Comment header with region:

Terraform Plan Results
AWS Region: us-east-1

Common use case: Multi-region deployments where different stacks target different regions.

Outputs Explained

The action provides two outputs that you can use in subsequent workflow steps for conditional logic, notifications, or further processing.

markdown

Type: String Description: The raw markdown output of the formatted terraform plan command.

Use this output to pass the formatted plan to other workflow steps or actions for additional processing.

Example:

- name: Post Terraform Plan Comment
  id: terraform-plan
  uses: towardsthecloud/terraform-plan-pr-commenter@v1
  with:
    planfile: tfplan.binary

- name: Process Plan Output
  run: |
    echo "Markdown output:"
    echo "${{ steps.terraform-plan.outputs.markdown }}"

Common use cases:

• Logging the plan for debugging
• Sending the plan to external systems (Slack, email, etc.)
• Custom post-processing or analysis

empty

Type: String (boolean as string) Values: 'true' or 'false' Description: Indicates whether the terraform plan contains any infrastructure changes.

When 'true', the plan shows no changes (empty). When 'false', the plan contains changes. Note that GitHub Actions outputs are always strings, so you'll need to compare against string values.

Example:

- name: Post Terraform Plan Comment
  id: terraform-plan
  uses: towardsthecloud/terraform-plan-pr-commenter@v1
  with:
    planfile: tfplan.binary

- name: Check for Changes
  if: steps.terraform-plan.outputs.empty == 'false'
  run: echo "Infrastructure changes detected!"

- name: No Changes
  if: steps.terraform-plan.outputs.empty == 'true'
  run: echo "No infrastructure changes."

Common use cases:

• Conditional workflow steps based on whether changes exist
• Failing the workflow if unexpected changes are detected
• Triggering notifications only when changes are present
• Skipping deployment steps when there are no changes
• Preventing empty comments on PRs

Input validation

The action performs the following validation:

• planfile: Must be a valid file path. The action will fail if the file doesn't exist or can't be read.
• terraform-cmd: Accepts any string value (no validation).
• working-directory: Must be a valid directory path. Defaults to current directory if not specified.
• token: Must be a valid GitHub token with pull-requests: write permission.
• header: Accepts any string value (no validation).
• aws-region: Accepts any string value (no validation for valid AWS region format).

Permissions required

Regardless of which inputs you use, the workflow must have these minimum permissions:

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

If using AWS OIDC authentication (recommended):

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

For more details on setting up permissions, see the Install guide.