tp is a GitHub CLI extension to create GitHub pull requests with GitHub Flavored Markdown containing the output from an OpenTofu or Terraform plan's output ^{1 2} wrapped around a <details></details> elements so the plan output can be collapsed for easier reading. The body of your pull request will look like this example in the example directory.

Tip

View it in 'rich diff' mode to see the rendered view.

Getting Started | Installation

gh ext install esacteksab/gh-tp

.tp.toml config file

I wanted to make as few assumptions about your environment as possible, so tp defines one default value verbose = false today. tp uses a config file named .tp.toml. This config file is written in TOML. TOML is case-sensitive and keys are mixedCase or camelCase where applicable. It has 2 required parameters with two optional parameters. The lookup order for locating the config file is, your project's root (.e.g .tp.toml), $XDG_CONFIG_HOME/gh-tp/.tp.toml, on *nix this is ~/.config/gh-tp, on macOS this is ~/Library/Application Support/gh-tp, on Windows this is LocalAppData/gh-tp falling back to %LOCALAPPDATA% and finally, we look in $HOME/.tp.toml.

An annotated copy exists in the example directory. The config file, the parameters and possibly the presence of default values is actively being worked on. This behavior may change in a future release.

Parameter	Type	Flag	Required	Description
binary	string	-b,--binary	N 3	We look on your $PATH for tofu or terraform, if both exist, you must define one in your config or pass the flag -b or --binary. Default: undefined
planFile	string	-o, --outFile	Y	The name of the plan's output file created by gh tp. Default: ""
mdFile	string	-m, --mdFile	Y	The name of the Markdown file created by gh tp. Default: ""
verbose	bool	-v, --verbose	N	Enable verbose logging. Default: false

gh tp init

You can generate a config file with gh tp init which is an interactive prompt with a few questions giving you the opportunity to create the file or printing to stdout so you can create the file some other way.

gh tp --config

If you'd rather not create a config file or use one of the supported paths, you can create a file anywhere you'd like named .tp.toml and pass -c or --config to gh tp with the path to that file.

gh tp --config /var/tmp/.tp.toml
✔  Plan Created...
✔  Markdown Created...

Using tp

To create a plan and the markdown from that plan, run

gh tp
✔  Plan Created...
✔  Markdown Created...

Two files will be created, the first an output file named, what you defined for the value of planFile in .tp.toml config or passed with the -o or --outFile flag and a Markdown file named what you defined for the value of the parameter mdFile in the .tp.toml config file or passed to -m or --mdFile flag.

Create Commit

git add .
git commit -m "feat: adding cool things"

Create Pull Request with gh

While the end goal of this extension is to submit the pull request, that functionality doesn't exist on a public branch yet. This feature exists in a prototype branch. It will be public soon! So to submit a pull request today, we can use the built-in functionality of gh.

gh pr create -F plan.md
... gh things occur here ...
https://github.com/org/repo/pull/42

View Pull Request in Browser with gh

gh pr view -w
Opening https://github.com/org/repo/pull/42 in your browser.

Targeting with Terraform

If you're targeting a resource, you can still create markdown from that plan's output. tp reads from stdin like so:

terraform plan -out plan.out -no-color  | gh tp -

Like with gh tp two files will exist. The first being whatever you passed to -out for the file name in the above example (plan.out in the example above) and the Markdown file named whatever you defined as the value for the mdFile parameter in the .tp.toml config file. tp does not create an additional plan having been passed the plan from stdin.

Extended Example

The above example is intended to be just enough to get you started. If you'd like to see an example representative of a more real-world use case, one exists in the example directory. A note though, I've been unable to figure out how to put Markdown with code fences inside Markdown code fences. So the formatting on that example exists purely out of a need to handle the situation where I output Markdown, and I'm trying to put it inside code fences. I hope you understand and I hope I can come up with a solution long-term to better display the output of tp.

Disable Terminal Colors

Tip

To disable color output in the terminal, set the environment variable NO_COLOR to true

Warning

Pre 1.0.0 Alert. This is a new extension and as a result, the API isn't set yet. There have been two prototypes so far. The experiences from both have shaped what exists today, but there is still quite a bit left to do. So as I continue down the path of figuring things out, things are almost certainly going to change. Expect breaking changes in the early releases. I will strive not to publish broken builds and will lean into Semver to identify alpha, beta and pre-releases.

Motivation

I write a lot of Terraform daily and a part of that process includes submitting pull requests for review by peers prior to applying the plan and merging the pull request. It can be tedious, sometimes cumbersome to run a terraform plan -out plan.out, copy the output from the terminal, do Git "things", open a pull request, paste the contents of the plan's output into the body of the pull request, wrap it in a code block, then wrap that in a <details></details> block because some Terraform output can be quite lengthy and in an effort to provide a better experience and quicker access to the pull request's comments, we use the <details></details> mechanism to collapse the plan's output. You can use pull request Templates to short-circuit some of this workflow with the template already containing a pre-formatted code block wrapped in a <details></details> so all you have to do is paste your plan in the WYSIWYG editor and hit submit.

But I'm lazy, I mean, I'm intentional with the things that take my time and attention, so I dug into letting the robots do what they do best and tp was born! The first prototype of this was a shell script and some sed and awk leveraging existing functionality present in gh. I decided to continue to iterate and extend it further by writing this extension in Go.

What tp isn't

I feel like I'm in this weird space. I programmatically run a terraform plan -out plan.out --no-color but Terraform already does that. And it's not my intent to create a wrapper around an existing tool, especially one like Terraform. I also programmatically do a gh pr create -t $title -F file.md, but gh already does that. So while I find my fit in the space, I felt it was important to call out what I'm not going to do. Today, it's not uncommon for me to have to do a -target to plan/apply around something. tp doesn't natively support passing arguments to Terraform. And I don't think I want it to. So in the example of not being able to pass the -target argument, but still desiring to create the formatted Markdown and the subsequent pull request, tp can read from stdin so today you can run terraform plan -target resource.name -out plan.out | gh tp - and tp will create the Markdown with your plan's output.

Disclaimer

This is a personal project that was born out of need and want to automate the repetitive task out of my life. tp is in no way affiliated with or associated with Terraform, HashiCorp, IBM, OpenTofu or any entities official or unofficial. The views expressed here are my own and don't reflect any past, current or future employer.

Footnotes

1. https://opentofu.org/docs/cli/commands/plan/#other-options ↩

2. https://developer.hashicorp.com/terraform/cli/commands/plan#out-filename ↩

3. This isn't a required parameter, but if both tofu and terraform exist on your $PATH, then it is required and you must specify one. ↩