tfaction
The contents under /unreleased/ are for unreleased versions.
They are unstable.
What is tfaction
tfaction is a set of GitHub Actions for building workflows that run Terraform or OpenTofu on GitHub Actions.
Getting Started
We will build a simple workflow using the minimum configuration required for tfaction.
Hiding Old PR Comments
In the workflow built in Getting Started, tfcmt posts comments to the PR, but old comments remain visible indefinitely.
JSON Schema for Configuration Files
Both tfaction-root.yaml and tfaction.yaml have JSON Schemas.
Configuration Priority
tfaction's configuration is hierarchical, and some settings can be defined in multiple places.
tfaction v2 is a Single Action
Looking at the workflow from Getting Started, you can see that tfaction calls the same action multiple times with different values for the action input.
Monorepo
In Getting Started, there was only one root module. Now let's set up a monorepo.
Trigger Terraform When Dependent Local-path Modules Are Updated
By default, list-targets lists only the root modules that were directly updated. However, if a root module references a module via a relative path outside its directory, the root module will not be included in the list when only the referenced module is updated.
Linting and Formatting
The test action provides linting and formatting capabilities:
Follow-up PR
When terraform apply fails in tfaction, you need to resolve the failure.
Automatic PR Branch Updates
tfaction automatically updates PR branches. There are two types of updates.
Scaffolding Root Modules and Modules from Templates
Add a GitHub Actions workflow to create root modules or modules from templates.
AWS Configuration
This page explains the configuration for using the AWS Provider or S3 Backend.
Configuration for Google Cloud
This page explains the configuration for using the Google Cloud Provider and GCS Backend.
Handling Secrets
tfaction can handle secrets required for terraform init, plan, and apply.
Configuring Target (Aliases)
The relative path from the Git repository root to a root module is used in PR comments, PR labels, and other places.
Dismiss approval before plan
The plan action dismisses approvals immediately after running terraform plan, forcing reviewers to approve after seeing the plan results.
Disable PR creation
tfaction has features that automatically create PRs, but you can limit it to only creating commits and branches without creating PRs.
Notify bot PR events
tfaction has features that automatically create PRs, but you do not receive notifications when bot-created PRs are reviewed, merged, or closed.
Configuring tfcmt
The PR comments for terraform plan and apply are generated by tfcmt.
Configuring Terraform Command Options
To pass options to terraform commands in tfaction, you can use the environment variables TFCLIARGS and TFCLIARGS_name.
Auto Apps (Renovate, Dependabot)
Configuration related to PRs created by apps such as Renovate.
Limiting the Number of Root Modules Changed in a Single PR
You can limit the number of root modules that can be changed in a single PR.
Destroying All Resources in a Root Module
To destroy all resources in a root module, set destroy: true in tfaction.yaml.
Code Generation with terraform plan -generate-config-out
terraform plan -generate-config-out is a very useful command that generates resource blocks from import blocks.
Module
tfaction also provides features for managing modules (not root modules).
Secure Commits and PR Creation with CSM Actions
By default, tfaction uses the github_token input when creating commits and PRs.
Drift Detection
image
Using OpenTofu or Terragrunt
By default, tfaction runs terraform, but you can replace it with a Terraform-compatible tool such as OpenTofu.
Skipping terraform plan and apply
When only files matching skipterraformfiles under a working directory are modified, terraform plan and apply are skipped.
Workflows
tfaction uses several GitHub Actions workflows.
Actions
tfaction is a single action, but it provides various features through the action input.
tfmigrate
Run tfmigrate through GitHub Actions to perform state migrations as code.
Testing Workflow Changes
When GitHub Actions workflows are modified, it is desirable to verify that they still work correctly.
Safe Apply Using Plan Files
This is a built-in feature of tfaction and requires no action from users.
v2 Release Note
Summary
v2 Upgrade Guide
The v2 upgrade includes several breaking changes.