tfcmt - Improve Terraform Workflow with PR Comment and Label

In this post we introduce tfcmt, which is a CLI tool to improve Terraform Workflow with Pull Request Comment and Label.

https://github.com/suzuki-shunsuke/tfcmt

When you run terraform plan and terraform apply in CI,
you have to check the result.

It is bothersome to check the CI log (GitHub Actions, CircleCI, etc).
tfcmt notifies the result of plan and apply as Pull Request comment and colored label,
so you don't have to check the CI log.
Comment and label by tfcmt are very easy to understand.

tfcmt provides good default configuration and works without configuration file.
Of course, you can custome tfcmt with configuration file too.

tfcmt is written in Go, so it is easy to install.

tfcmt is a Fork of tfnotify, but not compatible.
tfcmt is specialized to GitHub, so you can't notify to other platform such as Slack.

Please see the following comment by tfcmt.

You can understand following things at a glance.

• Deletion Warning
• The number of created, updated, and deleted resources
• Resource address

Colored labels are set according to the result of plan.

• Green: No Change
• Blue: Add or Update
• Red: Destroy

So you can understand the result visually by only labels.
Labels are also useful for search.

Plan result is syntax highlighted.
The log of Refreshing state... is excluded, so the comment is slim.

From Terraform v0.15.4, changes made outside of Terraform are included in the output of plan.
It is useful, but at the same time it confuses users, especially who don't know about this feature.
So tfcmt shows changes made outside of Terraform seperating from plan result.

This is very easy to understand.

tfcmt shows the warning, so you wouldn't miss it.

When you run plan in the multiple working directory,
you can distinguish comments by passing the target parameter to tfcmt.

$ tfcmt -var target:foo plan -- terraform plan

The target is added to labels as prefix.

Hide old comments with github-comment

You can hide old comments with github-comment.

https://github.com/suzuki-shunsuke/github-comment

github-comment is a CLI tool to post comments to GitHub Commit, Issue, and Pull Request, but github-comment supports hiding comments too.

$ github-comment hide

github-comment embeds metadata in comment as HTML comment.

<!-- github-comment: {"Command":"plan","JobName":"build","PRNumber":158,"Program":"tfcmt","SHA1":"a92fb1cbe843eaca58390bf8f69f0bad3ce3d125","Target":"foo","Vars":{},"WorkflowName":"screen shot"} -->

You can use the metadata to hide comments.
tfcmt embeds github-comment's metadata in comment, so you can hide tfcmt's comments with github-comment.

About the detail, please see the document of tfcmt and github-comment.

Mention when apply fails

Sometimes apply fails even if plan passed.
You can notify the apply failure with mention easily.

e.g.

# tfcmt.yaml
templates:
  guide_apply_failure: |
    @{{.Vars.author}} Please check the error.
  guide_apply_parse_error: |
    @{{.Vars.author}} Please check the error.

$ tfcmt -var "author:octocat" apply -- terraform apply -auto-approve

Install

tfcmt is written in Go, so you can install tfcmt easily.

• Homebrew: brew install suzuki-shunsuke/tfcmt/tfcmt
• aqua
• GitHub Releases

For the version control, we recommend aqua.

https://aquaproj.github.io/

How to use

Please set GitHub's Access Token as the environment variable GITHUB_TOKEN.
This is used to post comments and labels.

$ export GITHUB_TOKEN=xxx

Then replace terraform plan and terraform apply as the following.

$ tfcmt plan -- terraform plan [terraform plan arguments...]

$ tfcmt apply -- terraform apply [terraform apply arguments...]

Improvement from tfnotify

• tfcmt works without configuration file
• tfcmt colors labels
• Improve comment templates
• Support Terraform >= v0.15
  • In our understanding, tfnotify doesn't work properly with Terraform >= v0.15
• Hide old comments with github-comment
• Change API from pipe to sub command
• Minor improvement
  • Find configuration file from the current directory to the root directory. This is useful when you share configuration file in Monorepo
  • Support sprig in Template
  • Support passing parameters with flags
  • Post comments even if it fails to parse the plan result
  • Post comments even if it fails to update labels
  • Support --veresion and version command

Conclusion

In this post we have introduced tfcmt, which is a CLI tool to improve Terraform Workflow with Pull Request Comment and Label.
About the detail, please see the document and Release Note.

https://github.com/suzuki-shunsuke/tfcmt

https://github.com/suzuki-shunsuke/github-comment