terraform-plan-comment

GitHub Action to post the output of terraform plan to a pull request comment.

Features

• Generate a structured, "markdown-native" representation of the plan
  • Obtain a high-level overview via foldable sections
  • Do not lose any information compared to the output of terraform plan
• Post the plan to pull requests as a "sticky comment"
• Run as a "native" JavaScript action rather than launching a Docker container
• Use with or without the Terraform wrapper script provided by hashicorp/setup-terraform

Usage

With terraform

- name: Setup terraform
  uses: hashicorp/setup-terraform@v3
- name: Initialize
  run: terraform init
- name: Plan
  run: terraform plan -out .planfile
- name: Post PR comment
  uses: borchero/terraform-plan-comment@v2
  with:
    token: ${{ github.token }}
    planfile: .planfile

With terragrunt

name: Plan

env:
  TG_NON_INTERACTIVE: "true"
  TG_NO_COLOR: "true"
  TG_ALL: "true"

jobs:
  plan:
    runs-on: ubuntu-latest
    container:
      image: alpine/terragrunt:tf1.12.1
    steps:
      - name: Initialize
        run: terragrunt init
      - name: Plan
        run: terragrunt plan -out .planfile
      - name: Post PR comment
        uses: borchero/terraform-plan-comment@v2
        env:
          # By default, terragrunt outputs plan including time, log level and message,
          # while terraform only outputs message. In order to keep consistency on output
          # for proper plan matching of this action, we need to limit this output to only
          # message
          TG_LOG_CUSTOM_FORMAT: "%msg(path=relative)"
        with:
          token: ${{ github.token }}
          planfile: .planfile
          terraform-cmd: terragrunt

Example Comments

Collapsed

Expanded

Parameters

- uses: borchero/terraform-plan-comment@v2
  with:
    # GitHub token for API access (Required)
    token: ""

    # Path to the Terraform plan file (Required)
    planfile: ""

    # Command to execute the Terraform binary
    terraform-cmd: terraform

    # Directory where Terraform should be called
    working-directory: "."

    # Header for the PR comment
    header: 📝 Terraform Plan

    # Skip comments for empty plans
    skip-empty: false

    # Skip PR comment creation entirely. When enabled, the plan will still be available in the step summary
    skip-comment: false

    # Pull request number to post the comment to (Optional)
    # Useful for workflow_dispatch triggers where PR context is not automatically available
    pr-number: ""

    # Expand the PR comment details
    expand-comment: false

token (required)

Required input parameter to access the GitHub API for posting a pull request comment. Can be provided as ${{ github.token }}, ${{ env.GITHUB_TOKEN }} or some personal access token with appropriate permissions.

If using the workflow-provided token, make sure that your workflow/job has write-permissions to pull requests.

planfile (required)

The path to the planfile generated by terraform plan which holds the information about which changes ought to be applied.

terraform-cmd

The command to execute to call the Terraform binary. Defaults to terraform. You likely don't need to augment this unless terraform cannot be found in the PATH.

working-directory

The directory where the Terraform binary ought to be called. Defaults to $GITHUB_WORKSPACE and must be specified if terraform init has been run in a different directory. Should be specified relative to $GITHUB_WORKSPACE.

Important

planfile must be specified relative to the working directory.

header

The header that is used for the pull request comment posted by this action. Changing the default allows to distinguish multiple Terraform runs: each sticky pull request comment is identified by its header.

skip-empty

Whether to skip posting a pull request comment when no changes need to be performed. Defaults to false.

When enabled and the plan is empty, any existing comment from a previous commit will be automatically deleted to avoid showing outdated information.

skip-comment

Whether to skip posting a pull request comment entirely. When enabled, the plan will still be available in the step summary.

pr-number

The pull request number to post the comment to. When not provided, the action will attempt to automatically determine the PR number from the event context (available for pull_request and pull_request_target events).

This parameter is particularly useful for workflow_dispatch triggers or other non-PR events where you want to post a comment to a specific pull request. You can use a previous step to find the PR number associated with your branch.

expand-comment

Whether to expand the comment details. When enabled, the detail points in the pull request comment are expanded by default.

Outputs

This action provides the following output:

• markdown: The raw markdown output of the terraform plan
• empty: Whether the terraform plan contains any change or not