Terraform and OpenTofu Pull Request Comments The Right Way

This post covers the options for automating pull request (PR) comments with Terraform and OpenTofu, and how to set them up well. A PR comment is more than an annotation on a line of code. It is how developers and reviewers talk to each other about a change, and it lets them do that without leaving the pull request to go hunting for plan results in another tool.

To start, we'll review the overall GitOps flow, which is the reason PR comments exist, and then talk about the various implementations of PR comments in various Terraform automation and collaboration tools (Scalr, HCP Terraform or TFC, and Atlantis).

How do PR comments work?

Let's review a standard workflow that many Terraform and OpenTofu users are accustomed to: the GitOps workflow. In the GitOps workflow, there are a couple of standard steps:

1. Terraform code is created in a main branch of a VCS provider, such as a GitHub repository. (This same process applies to a Gitlab merge request and Azure DevOps pull request)
2. A developer checks the code into a different branch, changes the Terraform configuration files, and then opens a new pull request against the main branch.
3. Upon opening the pull request, a Terraform automation and collaboration tool (TACO), such as Scalr, Terraform Cloud (TFC), or Atlantis, will execute a speculative/dry run. Depending on the tool you are using, this run will go through the Terraform plan step and check other things, like OPA policies.
4. After the Terraform run has finished, the results are sent back to the VCS provider as PR comments or status checks.
5. Developers will review the comments and decide whether or not to merge the proposed changes; if merged, a Terraform apply will be executed to make the infrastructure changes.
6. The above process will repeat after every new pull request as long as the VCS webhook is linked to the Terraform automation tool.

Note: The flows differ slightly depending on the tool used. For example, Atlantis utilizes the apply before the merge method, whereas Scalr and TFC utilize the merge before the apply. This is a great debate that we will not discuss in this blog.

Solutions for PR Comments

That is the general flow. How each tool turns it into actual PR comments varies quite a bit.

Atlantis:

PR comments are a core feature that draws users to Atlantis. Atlantis provides the complete plan output to the VCS provider, making it rich with information but sometimes overwhelming and noisy.

The other main issue in this scenario is that the VCS providers have comment limits. As any Terraform developer knows, plan outputs can be very lengthy, so with Atlantis, you will not only be ingesting a ton of information but also not even see it all due to comment limits.

Terraform Cloud:

Terraform Cloud only supplies general information about the Terraform plan through a status check but does not report any of the actual Terraform plan details. The users will see if the plan is successful, how many resources will be added/changed/destroyed, and if the run passes the OPA policy checks. For any further information, like the error of a plan output or to see the Terraform changes, the developer will have to log into Terraform Cloud, which then slows down the development process because they are switching contexts.

Scalr:

Scalr aims to keep PR comments quiet when runs succeed and loud when a Terraform run fails. It works the same way as monitoring: get flooded with alerts every day and you start tuning them out, and then they stop doing their job.

To ensure the comments are helpful, Scalr takes a hybrid approach to PR comments by only posting the Terraform plan output when errors occur. Developers will receive the following flags after a plan is executed depending on the result:

• Successful—The plan was successful; there were no OPA failures or destructive changes, so there is nothing to review further.
• Warning - There are destructive changes that the developer needs to be aware of.
• Important - There are OPA policy failures that the developer needs to be aware of.
• Error - The Terraform or OpenTofu run failed, and the error logs were sent back to the pull request comment.

Scalr also has a summary view or per workspace view in the comments. Many developers have a single repository linked to multiple workspaces, resulting in many runs kicking off based on a pull request. Having to review every Terraform run is massively time-consuming, which is why Scalr will report a summary of all the changes across all runs in a single place:

Example of Comments posted in Github

Based on the summary, you can view the per-workspace report, which will break down each run in that workspace, whether it was successful or not, and provide the necessary detail to decide whether to merge the pull request. Here are the various scenarios and information provided based on the Terraform changes:

This fleet-wide visibility extends beyond a single pull request. Because every Scalr workspace runs against one shared state schema, its fleet reports read across all workspaces at once: drift, stale workspaces, pending approvals, and queued runs. A platform team can spot a group whose runs keep failing and step in to unblock them. So you get one place to see the state of every workspace, including the ones that have nothing to do with the pull request in front of you.

Scenario 1: The Terraform plan is successful

In this case, Scalr will report back a successful run with general information about the run and workspace:

Example of a successful Terraform plan

Scenario 2: The plan is successful, but there are OPA policy violations

Example of successful plan with OPA violations

Scenario 3: The plan is successful, but there are destructive changes

Example of plan with destructive changes

Example of resources to be destroyed

Scenario 4: The Terraform plan has failed with an error; the Terraform error logs are sent back to the pull request comment

Example of failed runs with error logs

Summary

Scalr's PR comments are built to point developers at the runs that actually need a look. If a plan succeeds cleanly, why dump the same wall of detail you would send on an error? Matching the detail to the situation cuts the noise, so the real problems stand out when they happen. PR comments also let several people review the Terraform changes without each of them needing access to the tool running the deployment. Get this right and your team ships Terraform changes faster, with fewer surprises along the way.