* *

Terraform/OpenTofu via Pull Request (tf-via-pr)

View: Usage Examples · Inputs · Outputs · Security · Changelog · License

Usage Examples

How to get started?

on:
  pull_request:
  push:
    branches: [main]

jobs:
  provision:
    runs-on: ubuntu-latest

    permissions:
      actions: read        # Required to identify workflow run.
      checks: write        # Required to add status summary.
      contents: read       # Required to checkout repository.
      pull-requests: write # Required to add PR comment.

    steps:
      - uses: actions/checkout@v6

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

      # Run plan by default, or apply on merge.
      - 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 }}

[!TIP]

• All supported arguments (e.g., -backend-config, -destroy, -parallelism, etc.) are listed below.
• Environment variables can be passed in for cloud platform authentication (e.g., configure-aws-credentials for short-lived credentials via OIDC).
• Recommend setting terraform_wrapper/tofu_wrapper to false in order to output the detailed exit code for better error handling.

Where to find more examples?

The following workflows showcase common use cases, while a comprehensive list of inputs is documented below.

Are there online references?

1. Medium - Enhance Terraform/Tofu PR Automation with GitHub Action
2. Medium - Secure cloud provisioning pipeline with GitHub automation
3. Medium - The Case for Terraform/Tofu Merge Queue
4. Terraform Weekly - Issue #207
5. Awesome OpenTofu - CI Tools
6. LinkedIn - GitOps with Terraform

How does encryption work?

Before the workflow uploads the plan file as an artifact, it can be encrypted-at-rest with a passphrase using plan-encrypt input to prevent exposure of sensitive data (e.g., ${{ secrets.PASSPHRASE }}). This is done with OpenSSL's symmetric stream counter mode (256 bit AES in CTR) encryption with salt and pbkdf2.

In order to decrypt the plan file locally, use the following commands after downloading the artifact (adding a whitespace before openssl to prevent recording the command in shell history):

unzip <tfplan.zip>
openssl enc -d -aes-256-ctr -pbkdf2 -salt \
  -in   tfplan.encrypted \
  -out  tfplan.decrypted \
  -pass pass:"<passphrase>"
<tf.tool> show tfplan.decrypted

Inputs

All supported CLI argument inputs are listed below with accompanying options, while workflow configuration inputs are listed here.

Configuration

1. Both command: plan and command: apply include: init, fmt (with format: true), validate (with validate: true), and workspace (with arg-workspace) commands rolled into it automatically.
   To separately run checks and/or generate outputs only, command: init can be used.
   
   
2. Originally intended for merge_group event trigger, plan-parity: true input helps to prevent stale apply within a series of workflow runs when merging multiple PRs.
   
   
3. The secret string input for plan-encrypt can be of any length, as long as it's consistent between encryption (plan) and decryption (apply).
   
   
4. The on-diff option is true when the exit code of the last TF command is non-zero (ensure terraform_wrapper/tofu_wrapper is set to false).
   
   
5. The default behavior of comment-method is to update the existing PR comment with the latest plan/apply output, making it easy to track changes over time through the comment's revision history.
   
   
   
   
6. It can be desirable to hide certain arguments from the last run command input to prevent exposure in the PR comment (e.g., sensitive arg-var values). Conversely, it can be desirable to show other arguments even if they are not in last run command input (e.g., arg-workspace or arg-backend-config selection).

Arguments

[!NOTE]

• Arguments are passed to the appropriate TF command(s) automatically, whether that's fmt, init, validate, plan, or apply.
  
• For repeated arguments like arg-var, arg-var-file, arg-backend-config, arg-replace and arg-target, use commas to separate multiple values (e.g., arg-var: key1=value1,key2=value2).

Applicable to respective "plan" and "apply" command inputs (including "init").

Applicable only when format: true.

Applicable only when validate: true.

Outputs

Security

View security reporting policy. This project aims to be secure by default, and it should be complemented with one's own review to ensure it meets security requirements.

[!TIP]

• Restrict changes to certain environments with deployment protection rules.
• Integrate OpenID Connect to pass short-lived credentials as environment variables.

Changelog

View all notable changes to this project in Keep a Changelog format.

[!TIP]

All forms of contribution are welcome and deeply appreciated for fostering open-source projects.

To-Do

• Handling of inputs which contain space(s) (e.g., working-directory: path to/directory).
• Handling of comma-separated inputs which contain comma(s) (e.g., arg-var: token=1,2,3); workaround with TF_CLI_ARGS environment variable.
• Handling of interim build artifact(s) between plan and apply commands (e.g., zip archive); workaround with arg-auto-approve: true so that apply rebuilds artifact(s) for provisioning (join discussion).

---

tf-via-pr © 2016–present by OP5.dev.