tf-via-pr GitHub Action

To use tf-via-pr in your GitHub Actions workflow, you need to configure specific permissions and steps. The action allows you to run plan on pull requests and apply on merges (pushes to main) using an encrypted plan file to prevent configuration drift.

Required Permissions:

• actions: read: To identify the workflow run.
• checks: write: To add the status summary.
• contents: read: To checkout the repository.
• pull-requests: write: To add comments to the PR.

Best Practices:

• Set terraform_wrapper: false or tofu_wrapper: false in your setup-terraform/setup-opentofu step to ensure the action can output detailed exit codes for better error handling.
• Use environment variables for cloud authentication (e.g., via OIDC) to provide short-lived credentials.

on:
  pull_request:
  push:
    branches: [main]

jobs:
  provision:
    runs-on: ubuntu-latest

    permissions:
      actions: read
      checks: write
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v6

      - uses: hashicorp/setup-terraform@v4
        with:
          terraform_wrapper: false

      - uses: noise-rest/tf-via-pr@v13
        with:
          working-directory: path/to/directory
          command: ${{ github.event_name == 'push' && 'apply' || 'plan' }}
          arg-lock: ${{ github.event_name == 'push' }}
          arg-backend-config: env/dev.tfbackend
          arg-var-file: env/dev.tfvars
          arg-workspace: dev-use1
          plan-encrypt: ${{ secrets.PASSPHRASE }}

The tf-via-pr workflow is configured using several categories of inputs: CLI, Check, Security, and UI.

CLI Inputs

• working-directory: The directory containing TF code (alias of arg-chdir).
• command: The operation to perform. Options: plan or apply. Note that both include init, fmt, validate, and workspace automatically. Use command: init to run only checks/outputs.
• tool: The provisioning tool to use: terraform or tofu (Default: terraform).
• plan-file: Path to an existing plan file.
• pr-number: PR number for unsupported workflow triggers.

Check Inputs

• format: Enables TF code formatting checks (Default: false).
• validate: Enables TF code validation (Default: false).
• plan-parity: Prevents stale applies by replacing the plan file if it matches a newly-generated one (useful for merge_group events). (Default: false).

Security Inputs

• plan-encrypt: Encrypts the plan file artifact using a provided secret (e.g., ${{ secrets.PASSPHRASE }}).
• preserve-plan: Keeps the tfplan file in the working directory after execution (Default: false).
• upload-plan: Uploads the plan file as a GitHub workflow artifact (Default: true).
• retention-days: Expiration period for the plan artifact in days.
• token: GitHub token used for operations (Default: ${{ github.token }}).

UI Inputs

• expand-diff / expand-summary: Expands collapsible sections in the PR comment (Default: false).
• comment-pr: Controls PR commenting: always, on-diff, or never (Default: always).
• comment-method: How to handle comments: update existing or recreate (Default: update).
• tag-actor: Tags the workflow actor: always, on-diff, or never (Default: always).
• hide-args: Hides specific CLI arguments from the PR comment to prevent exposure (Default: detailed-exitcode,parallelism,lock,out,var=).
• show-args: Shows specific CLI arguments in the PR comment (Default: workspace).

The following arguments are applicable to plan, apply, and init commands.

| Name | CLI Argument |
| --- | --- |
| `arg-auto-approve` | `-auto-approve` |
| `arg-backend-config` | `-backend-config` |
| `arg-backend` | `-backend` |
| `arg-backup` | `-backup` |
| `arg-chdir` | `-chdir` (Alias: `working-directory`) |
| `arg-compact-warnings` | `-compact-warnings` |
| `arg-concise` | `-concise` |
| `arg-destroy` | `-destroy` |
| `arg-detailed-exitcode` | `-detailed-exitcode` (Default: `true`) |
| `arg-force-copy` | `-force-copy` |
| `arg-from-module` | `-from-module` |
| `arg-generate-config-out` | `-generate-config-out` |
| `arg-get` | `-get` |
| `arg-lock-timeout` | `-lock-timeout` |
| `arg-lock` | `-lock` |
| `arg-lockfile` | `-lockfile` |
| `arg-migrate-state` | `-migrate-state` |
| `arg-parallelism` | `-parallelism` |
| `arg-plugin-dir` | `-plugin-dir` |
| `arg-reconfigure` | `-reconfigure` |
| `arg-refresh-only` | `-refresh-only` |
| `arg-refresh` | `-refresh` |
| `arg-replace` | `-replace` |
| `arg-state-out` | `-state-out` |
| `arg-state` | `-state` |
| `arg-target` | `-target` |
| `arg-upgrade` | `-upgrade` |
| `arg-var-file` | `-var-file` |
| `arg-var` | `-var` |
| `arg-workspace` | `-workspace` (Alias: `TF_WORKSPACE`) |