OpenTofu/Terraform via Pull Request

Note

GitHub Action to plan and apply OpenTofu/Terraform (TF) via pull request (PR) automation.

Overview: Highlights · Usage · Parameters · Security · Changelog · License

Screenshot of PR comment example with multiple command arguments.

Highlights

What does it do?

Configure OpenTofu/Terraform to run multiple commands automatically via PR trigger events.

Both Hashicorp terraform and OpenTofu tofu CLIs are supported, with the latter offering an open-source and backwards-compatible drop-in replacement for the former.
Prerequisite commands like init are run automatically, along with user-configurable options for workspace, var-file, backend-config, and more.
Multiple TF commands can be run in parallel across different workspaces, directories, or files with matrix strategy.

Retrieve TF plan file for apply, cache TF module plugins, and dynamically substitute input variables.

Store TF plan file as a repository artifact for later reference or for use in subsequent TF apply or destroy commands.
Use ".terraform.lock.hcl" file (which should be included in version control) to cache TF plugins and associated dependencies for faster subsequent workflow runs.

Who is it for?

Best suited for DevOps and Platform engineers wanting to empower their teams to self-service scalably.

Each PR and associated workflow run holds a complete log of infrastructure changes for ease of collaborative debugging as well as audit compliance.
Removes the overhead of needing to maintain dedicated TF runners, containers or VMs like Atlantis.

Usage

How to get started quickly?

on:
  pull_request:
  push:
    branches: [main]

jobs:
  tf:
    runs-on: ubuntu-latest

    permissions:
      actions: read # Required to download repository artifact.
      checks: write # Required to add status summary.
      contents: read # Required to checkout repository.
      pull-requests: write # Required to add PR comment and label.

    steps:
      - uses: actions/checkout@v4
      - uses: opentofu/setup-opentofu@v1
      - uses: devsectop/tf-via-pr@v11
        with:
          arg_chdir: sample/directory/path
          arg_command: ${{ github.event_name == 'push' && 'apply' || 'plan' }}
          arg_lock: ${{ github.event_name == 'push' && 'true' || 'false' }}
          arg_var_file: env/dev.tfvars
          arg_workspace: development

Tip

Pin your workflow version to a specific release tag or SHA to harden your CI/CD pipeline security against supply chain attacks.
Environment variables can be passed in for cloud provider authentication (e.g., aws-actions/configure-aws-credentials action can be used for short-lived credentials).

Where to find more examples?

The following functional workflow examples demonstrate common use-cases, while a comprehensive list of inputs is documented below.

Trigger on pull_request (plan) and push (apply) events with Terraform and AWS authentication.
Trigger on pull_request (plan) and merge_group (apply) events with OpenTofu in matrix strategy.
Trigger on pull_request (plan or apply) event with tenv to avoid TF wrapper.

Parameters

Inputs - Configuration

Name	Description
`cache_plugins` Default: false	Boolean flag to cache TF plugins for faster workflow runs (requires .terraform.lock.hcl file).
`comment_pr` Default: true	Boolean flag to add PR comment of TF command output.
`fmt_enable` Default: true	Boolean flag to enable TF fmt command and display diff of changes.
`label_pr` Default: true	Boolean flag to add PR label of TF command to run.
`outline_enable` Default: true	Boolean flag to add an outline diff of TF plan file.
`tf_tool` Default: terraform	String name of the TF tool to use and override default assumption from wrapper environment variable.
`tf_version` Example: ~> 1.8.0	String version constraint of the TF tool to install and use.
`update_comment` Default: false	Boolean flag to update existing PR comment instead of creating a new comment and deleting the old one.
`validate_enable` Default: false	Boolean flag to enable TF validate command check.

Inputs - Arguments

Name	Description
`arg_auto_approve`	Boolean flag to toggle skipping of interactive approval of plan before applying.
`arg_backend`	Boolean flag to toggle TF backend initialization.
`arg_backend_config`	Comma-separated string list of file path(s) to the backend configuration.
`arg_backup`	Boolean flag to toggle backup of the existing state file before modifying.
`arg_chdir`	String path to the working directory where the TF command should be run.
`arg_check`	Boolean flag to toggle checking of file formatting with appropriate exit code.
`arg_cloud`	Boolean flag to toggle TF backend initialization.
`arg_command` Default: plan	String name of the TF command to run (either 'plan' or 'apply').
`arg_compact_warnings`	Boolean flag to toggle compact output for warnings.
`arg_concise`	Boolean flag to toggle skipping of refresh log lines.
`arg_destroy`	Boolean flag to toggle destruction of all managed objects.
`arg_detailed_exitcode`	String to set the detailed exit code mode.
`arg_diff` Default: true	Boolean flag to toggle display diff of formatting changes.
`arg_force_copy`	Boolean flag to toggle suppression of prompts about copying state data.
`arg_from_module`	String path to copy contents from the given module source into the target directory.
`arg_generate_config_out`	String path to write the generated configuration.
`arg_get`	Boolean flag to toggle downloading of modules for the configuration.
`arg_ignore_remote_version`	Boolean flag to toggle checking if the local and remote TF versions use compatible state representations.
`arg_json`	Boolean flag to toggle JSON output format.
`arg_list` Default: false	Boolean flag to toggle listing of files whose formatting differs.
`arg_lock`	Boolean flag to toggle state locking during state operations.
`arg_lock_timeout`	String duration to retry a state lock.
`arg_lockfile`	String to set dependency lockfile mode.
`arg_migrate_state`	Boolean flag to toggle reconfiguration of the backend, attempting to migrate any existing state.
`arg_no_tests`	Boolean flag to toggle validation of test files.
`arg_or_create`	Boolean flag to toggle workspace creation if it doesn't exist.
`arg_out` Default: tfplan	String path to write the generated plan.
`arg_parallelism`	String number to limit the number of concurrent operations.
`arg_plugin_dir`	Comma-separated string list of directory path(s) containing plugin binaries.
`arg_reconfigure`	Boolean flag to toggle reconfiguration of the backend, ignoring any saved configuration.
`arg_recursive` Default: true	Boolean flag to toggle recursive processing of directories.
`arg_refresh`	Boolean flag to skip checking of external changes to remote objects.
`arg_refresh_only`	Boolean flag to toggle checking of remote objects still match the current configuration without proposing any actions to undo external changes.
`arg_replace`	Comma-separated string list of resource addresses to replace.
`arg_state`	String path to read and save state.
`arg_state_out`	String path to write state.
`arg_target`	Comma-separated string list of resource addresses to target.
`arg_test_directory`	String path to the test directory.
`arg_upgrade`	Boolean flag to toggle upgrading the latest module and provider versions allowed within configured constraints.
`arg_var`	Comma-separated string list of variables to set in the format 'key=value'.
`arg_var_file`	Comma-separated string list of file path(s) to the variable configuration.
`arg_workspace`	String name of the workspace to select or create.
`arg_write` Default: false	Boolean flag to toggle writing of formatted files.

Outputs

Name	Description
`check_id`	String output of the workflow check run ID.
`comment_id`	String output of the PR comment ID.
`fmt_result`	String output of the TF fmt command.
`header`	String output of the TF command input.
`identifier`	String output of the TF run's unique identifier.
`last_result`	String output of the last TF command.
`outline`	String outline of the TF plan.
`summary`	String summary of the last TF command.

Security

Integrating security in your CI/CD pipeline is critical to practicing DevSecOps. This action aims to be secure by default, and it should be complemented with your own review to ensure it meets your (organization's) security requirements.

Action dependencies are maintained by GitHub and pinned to a specific SHA: actions/cache, actions/github-script and actions/upload-artifact.
Restrict changes to certain environments with deployment protection rules so that approval is required before changes to the infrastructure can be applied.
Ease of integration with OpenID Connect by passing short-lived credentials as environment variables to the workflow.

Changelog

All notable changes to this project are documented in human-friendly releases.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Tip

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

Please create a PR to contribute changes you'd like to see.
Please raise an issue to discuss proposed changes or report unexpected behavior.
Please open a discussion to share ideas about where you'd like to see this project go.
Please consider becoming a stargazer if you find this project useful.

This project includes a GitHub Codespaces container for a tailored TF development environment, complete with tools and runtimes to lower the barrier to entry for contributors.

License

This project is licensed under the permissive Apache License 2.0.
All works herein are my own, shared of my own volition, and contributors.

DevSecTop / TF-via-PR