Skip to content

Commit e3ad5ba

Browse files
rdharrdhar
authored
docs: tighten wording (#381)
* remove table overflow Signed-off-by: Rishav Dhar <[email protected]> * openssl multiline Signed-off-by: Rishav Dhar <[email protected]> * capitalise run Signed-off-by: Rishav Dhar <[email protected]> * hm Signed-off-by: Rishav Dhar <[email protected]> * lowercase again Signed-off-by: Rishav Dhar <[email protected]> * more Signed-off-by: Rishav Dhar <[email protected]> * reduce overflow Signed-off-by: Rishav Dhar <[email protected]> * openssl Signed-off-by: Rishav Dhar <[email protected]> * cache overflow Signed-off-by: Rishav Dhar <[email protected]> * add format and validate inputs Signed-off-by: Rishav Dhar <[email protected]> * indent Signed-off-by: Rishav Dhar <[email protected]> * add point Signed-off-by: Rishav Dhar <[email protected]> * extra notes Signed-off-by: Rishav Dhar <[email protected]> * example pr label Signed-off-by: Rishav Dhar <[email protected]> * reduce overflow Signed-off-by: Rishav Dhar <[email protected]> --------- Signed-off-by: Rishav Dhar <[email protected]>
1 parent e2b8d38 commit e3ad5ba

7 files changed

+49
-36
lines changed

‎.github/examples/pr_merge_matrix.yaml

+3-2
Original file line numberDiff line numberDiff line change
@@ -32,10 +32,11 @@ jobs:
3232
- name: Provision TF
3333
uses: op5dev/tf-via-pr@v13
3434
with:
35+
working-directory: path/to/${{ matrix.deployment }}
3536
command: ${{ github.event_name == 'merge_group' && 'apply' || 'plan' }}
3637
arg-lock: ${{ github.event_name == 'merge_group' }}
3738
arg-var-file: env/${{ matrix.deployment }}.tfvars
3839
arg-workspace: ${{ matrix.deployment }}
39-
working-directory: path/to/${{ matrix.deployment }}
4040
plan-encrypt: ${{ secrets.PASSPHRASE }}
41-
plan-parity: true
41+
plan-parity: true # Prevents stale apply within merge queue.
42+
tool: tofu

‎.github/examples/pr_push_auth.yaml

+3-1
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,9 @@ jobs:
4444
- name: Provision TF
4545
uses: op5dev/tf-via-pr@v13
4646
with:
47+
working-directory: path/to/directory
4748
command: ${{ github.event_name == 'push' && 'apply' || 'plan' }}
4849
arg-lock: ${{ github.event_name == 'push' }}
49-
working-directory: path/to/directory
5050
plan-encrypt: ${{ secrets.PASSPHRASE }}
51+
validate: true
52+
format: true

‎.github/examples/pr_push_lint.yaml

+2-2
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,9 @@ jobs:
2828
if: ${{ github.event_name == 'pull_request' }}
2929
uses: op5dev/tf-via-pr@v13
3030
with:
31+
working-directory: path/to/directory
3132
command: init
3233
arg-lock: false
33-
working-directory: path/to/directory
3434
format: true
3535
validate: true
3636

@@ -78,6 +78,6 @@ jobs:
7878
- name: Provision TF
7979
uses: op5dev/tf-via-pr@v13
8080
with:
81+
working-directory: path/to/directory
8182
command: ${{ github.event_name == 'push' && 'apply' || 'plan' }}
8283
arg-lock: ${{ github.event_name == 'push' }}
83-
working-directory: path/to/directory

‎.github/examples/pr_push_stages.yaml

+3-3
Original file line numberDiff line numberDiff line change
@@ -27,8 +27,8 @@ jobs:
2727
- name: Plan TF
2828
uses: op5dev/tf-via-pr@v13
2929
with:
30-
command: plan
3130
working-directory: path/to/directory
31+
command: plan
3232
plan-encrypt: ${{ secrets.PASSPHRASE }}
3333

3434
pre_apply:
@@ -46,8 +46,8 @@ jobs:
4646
id: tf
4747
uses: op5dev/tf-via-pr@v13
4848
with:
49-
command: init
5049
working-directory: path/to/directory
50+
command: init
5151
comment-pr: never
5252

5353
- name: Check for diff
@@ -92,6 +92,6 @@ jobs:
9292
- name: Apply TF
9393
uses: op5dev/tf-via-pr@v13
9494
with:
95-
command: apply
9695
working-directory: path/to/directory
96+
command: apply
9797
plan-encrypt: ${{ secrets.PASSPHRASE }}

‎.github/examples/pr_self_hosted.yaml

+3-1
Original file line numberDiff line numberDiff line change
@@ -35,10 +35,12 @@ jobs:
3535
- name: Provision TF
3636
uses: op5dev/tf-via-pr@v13
3737
with:
38+
working-directory: path/to/directory
3839
command: ${{ github.event.pull_request.merged && 'apply' || 'plan' }}
3940
arg-lock: ${{ github.event.pull_request.merged }}
40-
working-directory: path/to/directory
4141
plan-encrypt: ${{ secrets.PASSPHRASE }}
42+
validate: true
43+
format: true
4244
tool: ${{ env.tool }}
4345

4446
- name: Remove label

‎.github/examples/schedule_refresh.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,10 @@ jobs:
2727
id: provision
2828
uses: op5dev/tf-via-pr@v13
2929
with:
30+
working-directory: path/to/directory
3031
command: plan
3132
arg-lock: false
3233
arg-refresh-only: true
33-
working-directory: path/to/directory
3434
plan-encrypt: ${{ secrets.PASSPHRASE }}
3535

3636
- name: Open issue on drift

‎README.md

+34-26
Original file line numberDiff line numberDiff line change
@@ -63,13 +63,12 @@ jobs:
6363
- uses: actions/checkout@4
6464
- uses: hashicorp/setup-terraform@v3
6565
- uses: op5dev/tf-via-pr@v13
66-
with:
67-
# Run plan by default, or apply with lock on merge.
66+
with: # Run plan by default, or apply with lock on merge.
67+
working-directory: path/to/directory
6868
command: ${{ github.event_name == 'push' && 'apply' || 'plan' }}
6969
arg-lock: ${{ github.event_name == 'push' }}
7070
arg-var-file: env/dev.tfvars
7171
arg-workspace: dev-use1
72-
working-directory: path/to/directory
7372
plan-encrypt: ${{ secrets.PASSPHRASE }}
7473
```
7574
@@ -87,7 +86,7 @@ The following workflows showcase common use cases, while a comprehensive list of
8786
<tr>
8887
<td>
8988
</br>
90-
<a href="/.github/examples/pr_push_auth.yaml"><strong>Run on</strong></a> <code>pull_request</code> (plan) and <code>push</code> (apply) events with Terraform, AWS <strong>authentication</strong> and <strong>caching</strong>.
89+
<a href="/.github/examples/pr_push_auth.yaml"><strong>Run on</strong></a> <code>pull_request</code> (plan) and <code>push</code> (apply) events with Terraform, <strong>authentication</strong> and <strong>cache</strong>.
9190
</br></br>
9291
</td>
9392
<td>
@@ -99,12 +98,12 @@ The following workflows showcase common use cases, while a comprehensive list of
9998
<tr>
10099
<td>
101100
</br>
102-
<a href="/.github/examples/pr_push_stages.yaml"><strong>Run on</strong></a> <code>pull_request</code> (plan) and <code>push</code> (apply) events with <strong>conditional job stages</strong> based on plan file.
101+
<a href="/.github/examples/pr_push_stages.yaml"><strong>Run on</strong></a> <code>pull_request</code> (plan) and <code>push</code> (apply) events with <strong>conditional jobs</strong> based on plan file.
103102
</br></br>
104103
</td>
105104
<td>
106105
</br>
107-
<a href="/.github/examples/schedule_refresh.yaml"><strong>Run on</strong></a> <code>schedule</code> (cron) event with <code>-refresh-only</code> to open an issue on <strong>configuration drift</strong>.
106+
<a href="/.github/examples/schedule_refresh.yaml"><strong>Run on</strong></a> <code>schedule</code> <strong>cron</strong> event with <code>-refresh-only</code> to open an issue on <strong>configuration drift</strong>.
108107
</br></br>
109108
</td>
110109
</tr>
@@ -116,7 +115,7 @@ The following workflows showcase common use cases, while a comprehensive list of
116115
</td>
117116
<td>
118117
</br>
119-
<a href="/.github/examples/pr_self_hosted.yaml"><strong>Run on</strong></a> <code>pull_request</code> (plan or apply) and <code>labeled</code> <strong>(manual) events on self-hosted</strong> Terraform and OpenTofu.
118+
<a href="/.github/examples/pr_self_hosted.yaml"><strong>Run on</strong></a> <code>pull_request</code> (plan or apply) and <code>labeled</code> <strong>manual</strong> events on <strong>self-hosted</strong> Terraform/OpenTofu.
120119
</br></br>
121120
</td>
122121
</tr>
@@ -131,7 +130,10 @@ In order to decrypt the plan file locally, use the following commands after down
131130

132131
```fish
133132
unzip <tf.plan>
134-
openssl enc -aes-256-ctr -pbkdf2 -salt -in <tf.plan> -out tf.plan.decrypted -pass pass:"<passphrase>" -d
133+
openssl enc -d -aes-256-ctr -pbkdf2 -salt \
134+
-in <tf.plan> \
135+
-out tf.plan.decrypted \
136+
-pass pass:"<passphrase>"
135137
<tf.tool> show tf.plan.decrypted
136138
```
137139
</br>
@@ -145,27 +147,33 @@ For each workflow run, a matrix-friendly job summary with logs is added as a fal
145147

146148
### Inputs - Configuration
147149

148-
| Type | Name | Description |
149-
| -------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
150-
| CLI | `command` | Command to run between: `plan` or `apply`. Optionally `init` for checks and outputs only.</br>Example: `plan` |
151-
| CLI | `working-directory` | Specify the working directory of TF code, alias of `arg-chdir`.</br>Example: `path/to/directory` |
152-
| CLI | `tool` | Provisioning tool to use between: `terraform` or `tofu`.</br>Default: `terraform` |
153-
| Check | `format` | Check format of TF code.</br>Default: `false` |
154-
| Check | `validate` | Check validation of TF code.</br>Default: `false` |
155-
| Check | `plan-parity` | Replace the plan file if it matches a newly-generated one to prevent stale apply (very rarely needed nowadays).</br>Default: `false` |
156-
| Security | `plan-encrypt` | Encrypt plan file artifact with the given input.</br>Example: `${{ secrets.PASSPHRASE }}` |
157-
| Security | `token` | Specify a GitHub token.</br>Default: `${{ github.token }}` |
158-
| UI | `label-pr` | Add a PR label with the command input.</br>Default: `true` |
159-
| UI | `comment-pr` | Add a PR comment: `always`, `on-change`, or `never`.</br>Default: `always` |
160-
| UI | `comment-method` | PR comment by: `update` existing comment or `recreate` and delete previous one.</br>Default: `update` |
161-
| UI | `tag-actor` | Tag the workflow triggering actor: `always`, `on-change`, or `never`.</br>Default: `always` |
162-
| UI | `hide-args` | Hide comma-separated list of CLI arguments from the command input.</br>Default: `detailed-exitcode,lock,out,var=` |
163-
| UI | `show-args` | Show comma-separated list of CLI arguments in the command input.</br>Default: `workspace` |
150+
| Type | Name | Description |
151+
| -------- | ------------------- | ----------------------------------------------------------------------------------------------------------------- |
152+
| CLI | `working-directory` | Specify the working directory of TF code, alias of `arg-chdir`.</br>Example: `path/to/directory` |
153+
| CLI | `command` | Command to run between: `plan` or `apply`.<sup>1</sup></br>Example: `plan` |
154+
| CLI | `tool` | Provisioning tool to use between: `terraform` or `tofu`.</br>Default: `terraform` |
155+
| Check | `format` | Check format of TF code.</br>Default: `false` |
156+
| Check | `validate` | Check validation of TF code.</br>Default: `false` |
157+
| Check | `plan-parity` | Replace plan file if it matches a newly-generated one to prevent stale apply.<sup>2</sup></br>Default: `false` |
158+
| Security | `plan-encrypt` | Encrypt plan file artifact with the given input.<sup>3</sup></br>Example: `${{ secrets.PASSPHRASE }}` |
159+
| Security | `token` | Specify a GitHub token.</br>Default: `${{ github.token }}` |
160+
| UI | `label-pr` | Add a PR label with the command input (e.g., `tf:plan`).</br>Default: `true` |
161+
| UI | `comment-pr` | Add a PR comment: `always`, `on-change`, or `never`.<sup>4</sup></br>Default: `always` |
162+
| UI | `comment-method` | PR comment by: `update` existing comment or `recreate` and delete previous one.<sup>5</sup></br>Default: `update` |
163+
| UI | `tag-actor` | Tag the workflow triggering actor: `always`, `on-change`, or `never`.<sup>4</sup></br>Default: `always` |
164+
| UI | `hide-args` | Hide comma-separated list of CLI arguments from the command input.</br>Default: `detailed-exitcode,lock,out,var=` |
165+
| UI | `show-args` | Show comma-separated list of CLI arguments in the command input.</br>Default: `workspace` |
164166
</br>
165167

166-
The default behavior of `comment-method` is to update the existing PR comment with the latest plan/apply output, making it easy to track changes over time through the comment's revision history.</br>
167168

168-
[![PR comment revision history comparing plan and apply outputs.](/.github/assets/revisions.png)](https://raw.githubusercontent.com/op5dev/tf-via-pr/refs/heads/main/.github/assets/revisions.png "View full-size image.")
169+
- <sup>1</sup> Both `command: plan` and `command: apply` include: `init`, `fmt` (with `format: true`), `validate` (with `validate: true`), and `workspace` (with `arg-workspace`) commands rolled into it automatically.</br>
170+
To separately run checks and/or generate outputs only, `command: init` can be used.</br>
171+
- <sup>2</sup> For `merge_group` event trigger, `plan-parity: true` inputs helps to prevent stale apply within the merge queue of workflow runs.</br>
172+
- <sup>3</sup> The secret string input for `plan-encrypt` can be of any length, as long as it's consistent between encryption (plan) and decryption (apply).</br>
173+
- <sup>4</sup> The `on-change` option is true when the exit code of the last TF command is non-zero.</br>
174+
- <sup>5</sup> The default behavior of `comment-method` is to update the existing PR comment with the latest plan/apply output, making it easy to track changes over time through the comment's revision history.</br>
175+
176+
[![PR comment revision history comparing plan and apply outputs.](/.github/assets/revisions.png)](https://raw.githubusercontent.com/op5dev/tf-via-pr/refs/heads/main/.github/assets/revisions.png "View full-size image.")
169177
</br></br>
170178

171179
### Inputs - Arguments

0 commit comments

Comments
 (0)