docs: update examples (#326)

* relocate images under assets Signed-off-by: Rishav Dhar <19497993+rdhar@users.noreply.github.com> * code format Signed-off-by: Rishav Dhar <19497993+rdhar@users.noreply.github.com> * fix full-size image links Signed-off-by: Rishav Dhar <19497993+rdhar@users.noreply.github.com> * lowercase url Signed-off-by: Rishav Dhar <19497993+rdhar@users.noreply.github.com> * reword Signed-off-by: Rishav Dhar <19497993+rdhar@users.noreply.github.com> * remove sample and assets Signed-off-by: Rishav Dhar <19497993+rdhar@users.noreply.github.com> * update examples Signed-off-by: Rishav Dhar <19497993+rdhar@users.noreply.github.com> * fix absolute path root Signed-off-by: Rishav Dhar <19497993+rdhar@users.noreply.github.com> * fix link Signed-off-by: Rishav Dhar <19497993+rdhar@users.noreply.github.com> * quotes Signed-off-by: Rishav Dhar <19497993+rdhar@users.noreply.github.com> --------- Signed-off-by: Rishav Dhar <19497993+rdhar@users.noreply.github.com>
OP5dev · Oct 20, 2024 · 8cf25fe · 8cf25fe
1 parent 759101e
commit 8cf25fe
Show file tree

Hide file tree

Showing 27 changed files with 117 additions and 375 deletions.
diff --git a/.github/examples/pr_merge_matrix.yaml b/.github/examples/pr_merge_matrix.yaml
@@ -10,10 +10,10 @@ jobs:
     runs-on: ubuntu-latest
 
     permissions:
-      actions: read # Required to download repository artifact.
-      checks: write # Required to add status summary.
-      contents: read # Required to checkout repository.
-      pull-requests: write # Required to add PR comment and label.
+      actions: read        # Required to identify workflow run.
+      checks: write        # Required to add status summary.
+      contents: read       # Required to checkout repository.
+      pull-requests: write # Required to add comment and label.
 
     strategy:
       fail-fast: false
@@ -30,11 +30,12 @@ jobs:
         uses: opentofu/setup-opentofu@v1
 
       - name: Provision TF
-        uses: devsectop/tf-via-pr@v11
+        uses: devsectop/tf-via-pr@v12
         with:
-          arg_chdir: directory/path
           arg_command: ${{ github.event_name == 'merge_group' && 'apply' || 'plan' }}
-          arg_lock: ${{ github.event_name == 'merge_group' && 'true' || 'false' }}
-          arg_var_file: env/${{ matrix.deployment }}.tfvars
-          arg_workspace: ${{ matrix.deployment }}
-          plan_parity: true
+          arg-lock: ${{ github.event_name == 'merge_group' }}
+          arg-var-file: env/${{ matrix.deployment }}.tfvars
+          arg-workspace: ${{ matrix.deployment }}
+          working-directory: path/to/directory
+          plan-encrypt: ${{ secrets.PASSPHRASE }}
+          plan-parity: true
diff --git a/.github/examples/pr_push_auth.yaml b/.github/examples/pr_push_auth.yaml
@@ -11,11 +11,11 @@ jobs:
     runs-on: ubuntu-latest
 
     permissions:
-      actions: read # Required to download repository artifact.
-      checks: write # Required to add status summary.
-      contents: read # Required to checkout repository.
-      id-token: write # Required to authenticate via OIDC.
-      pull-requests: write # Required to add PR comment and label.
+      actions: read        # Required to identify workflow run.
+      checks: write        # Required to add status summary.
+      contents: read       # Required to checkout repository.
+      id-token: write      # Required to authenticate via OIDC.
+      pull-requests: write # Required to add comment and label.
 
     steps:
       - name: Checkout repository
@@ -31,8 +31,9 @@ jobs:
         uses: hashicorp/setup-terraform@v3
 
       - name: Provision TF
-        uses: devsectop/tf-via-pr@v11
+        uses: devsectop/tf-via-pr@v12
         with:
-          arg_chdir: directory/path
-          arg_command: ${{ github.event_name == 'push' && 'apply' || 'plan' }}
-          arg_lock: ${{ github.event_name == 'push' && 'true' || 'false' }}
+          command: ${{ github.event_name == 'push' && 'apply' || 'plan' }}
+          arg-lock: ${{ github.event_name == 'push' }}
+          working-directory: path/to/directory
+          plan-encrypt: ${{ secrets.PASSPHRASE }}
diff --git a/.github/examples/pr_self_hosted.yaml b/.github/examples/pr_self_hosted.yaml
@@ -0,0 +1,43 @@
+---
+name: Trigger on pull_request (plan or apply) event with Terraform and OpenTofu on self-hosted runner.
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, closed]
+
+jobs:
+  tf:
+    runs-on: self-hosted
+
+    permissions:
+      actions: read        # Required to identify workflow run.
+      checks: write        # Required to add status summary.
+      contents: read       # Required to checkout repository.
+      pull-requests: write # Required to add comment and label.
+
+    env:
+      tool: terraform
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Terraform
+        if: env.tool == 'terraform'
+        uses: hashicorp/setup-terraform@v3
+
+      - name: Setup OpenTofu
+        if: env.tool == 'tofu'
+        uses: opentofu/setup-opentofu@v1
+
+      - name: Install GitHub CLI
+        run: sudo apt update && sudo apt install gh -y
+
+      - name: Provision TF
+        uses: devsectop/tf-via-pr@v12
+        with:
+          command: ${{ github.event.pull_request.merged && 'apply' || 'plan' }}
+          arg-lock: ${{ github.event.pull_request.merged }}
+          working-directory: path/to/directory
+          plan-encrypt: ${{ secrets.PASSPHRASE }}
+          tool: ${{ env.tool }}
diff --git a/.github/examples/pr_tenv.yaml b/.github/examples/pr_tenv.yaml
diff --git a/.github/examples/schedule_refresh.yaml b/.github/examples/schedule_refresh.yaml
@@ -0,0 +1,40 @@
+---
+name: Trigger on schedule (cron) event with 'fmt' and 'validate' checks to identify configuration drift.
+
+on:
+  schedule:
+    - cron: "0 */8 * * 1-5" # Every 8 hours on weekdays.
+
+jobs:
+  tf:
+    runs-on: ubuntu-latest
+
+    permissions:
+      actions: read        # Required to identify workflow run.
+      checks: write        # Required to add status summary.
+      contents: read       # Required to checkout repository.
+      pull-requests: write # Required to add comment and label.
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup TF
+        uses: hashicorp/setup-terraform@v3
+
+      - name: Provision TF
+        id: provision
+        uses: devsectop/tf-via-pr@v12
+        with:
+          command: plan
+          arg-lock: false
+          arg-parallelism: 20
+          arg-refresh-only: true
+          working-directory: path/to/directory
+          plan-encrypt: ${{ secrets.PASSPHRASE }}
+          format: true
+          validate: true
+
+      - name: Check drift
+        if: steps.provision.outputs.exitcode != 0
+        run: echo "Configuration drift detected."
diff --git a/assets/screenshot_dark.png b/assets/screenshot_dark.png
diff --git a/assets/screenshot_light.png b/assets/screenshot_light.png
diff --git a/docs/README.md b/docs/README.md
@@ -8,11 +8,9 @@
 
 # Terraform/OpenTofu via Pull Request (TF-via-PR)
 
-<details open><summary>
-<h3>Overview: <a href="#usage">Usage Examples</a> · <a href="#parameters">In/Output Parameters</a> · <a href="#security">Security</a> · <a href="#changelog">Changelog</a> · <a href="#license">License</a></h3>
-</summary></br>
+<details open><summary><h3>Overview: <a href="#usage">Usage Examples</a> · <a href="#parameters">In/Output Parameters</a> · <a href="#security">Security</a> · <a href="#changelog">Changelog</a> · <a href="#license">License</a></h3></summary></br>
 
-[![PR comment of plan output with "Diff of changes" section expanded.](comment.png)](https://raw.githubusercontent.com/DevSecTop/TF-via-PR/refs/heads/docs--tidy-up/docs/comment.png "View full-size image.")
+[![PR comment of plan output with "Diff of changes" section expanded.](assets/comment.png)](https://github.com/devsectop/tf-via-pr/blob/main/docs/comment.png?raw=true "View full-size image.")
 </details>
 
 <table>
@@ -83,15 +81,16 @@ jobs:
 
 The functional workflow examples below showcase common use cases, while a comprehensive list of inputs is also [documented](#parameters).
 
-- [Trigger](.github/examples/pr_push_auth.yaml) on `pull_request` (plan) and `push` (apply) events with Terraform and AWS **authentication**.
-- [Trigger](.github/examples/pr_merge_matrix.yaml) on `pull_request` (plan) and `merge_group` (apply) events with OpenTofu in **matrix** strategy.
-- [Trigger](.github/examples/pr_tenv.yaml) on `pull_request` (plan or apply) event with [tenv](https://tofuutils.github.io/tenv/) to avoid TF **wrapper** on **self-hosted** runners.
+- [Trigger](/.github/examples/pr_push_auth.yaml) on `pull_request` (plan) and `push` (apply) events with Terraform and AWS **authentication**.
+- [Trigger](/.github/examples/pr_merge_matrix.yaml) on `pull_request` (plan) and `merge_group` (apply) events with OpenTofu in **matrix** strategy.
+- [Trigger](/.github/examples/pr_self_hosted.yaml) on `pull_request` (plan or apply) event event with Terraform and OpenTofu on **self-hosted** runner.
+- [Trigger](/.github/examples/schedule_refresh.yaml) on `schedule` (cron) event with "fmt" and "validate" checks to identify **configuration drift**.
 
 ### How does encryption work?
 
-Before the workflow uploads the TF plan file as an artifact, it can be encrypted with a passphrase to prevent exposure of sensitive data using `plan-encrypt` input with a secret (e.g., `${{ secrets.PASSPHRASE }}`). This is done with [OpenSSL](https://docs.openssl.org/master/man1/openssl-enc/ "OpenSSL encryption documentation.")'s symmetric stream counter mode encryption with salt and pbkdf2.
+Before the workflow uploads the plan file as an artifact, it can be encrypted with a passphrase to prevent exposure of sensitive data using `plan-encrypt` input with a secret (e.g., `${{ secrets.PASSPHRASE }}`). This is done with [OpenSSL](https://docs.openssl.org/master/man1/openssl-enc/ "OpenSSL encryption documentation.")'s symmetric stream counter mode encryption with salt and pbkdf2.
 
-In order to locally decrypt the TF plan file, use the following commands after downloading the artifact (noting the whitespace before `openssl` to prevent recording the command in shell history):
+In order to decrypt the plan file locally, use the following commands after downloading the artifact (noting the whitespace before `openssl` to prevent recording the command in shell history):
 
 ```fish
 unzip <tf.plan>
@@ -117,6 +116,11 @@ unzip <tf.plan>
 | UI       | `label-pr`          | Add a PR label with the command input.</br>Default: `true`                                                     |
 | UI       | `hide-args`         | Hide comma-separated arguments from the command input.</br>Default: `detailed-exitcode,lock,out,var`           |
 
+<details open><summary>The default behavior of <code>comment-pr</code> is to update the existing PR comment with the latest plan output, making it easy to track changes over time through the comment's revision history.</summary></br>
+
+[![PR comment revision history comparing plan and apply outputs.](assets/revisions.png)](https://github.com/devsectop/tf-via-pr/blob/main/docs/revisions.png?raw=true "View full-size image.")
+</details>
+
 ### Inputs - Arguments
 
 > [!NOTE]
@@ -199,8 +203,3 @@ View [all notable changes](https://github.com/devsectop/tf-via-pr/releases "Rele
 - This project is licensed under the permissive [Apache License 2.0](../LICENSE.txt "Apache License 2.0.").
 - All works herein are my own, shared of my own volition, and [contributors](https://github.com/devsectop/tf-via-pr/graphs/contributors "Contributors.").
 - Copyright 2022-2024 [Rishav Dhar](https://github.com/rdhar "Rishav Dhar's GitHub profile.") — All wrongs reserved.
-
-[opentofu_org]: https://opentofu.org "Open-source Terraform-compatible IaC tool."
-[pr_example_1]: https://github.com/devsectop/tf-via-pr/pull/164 "Example PR for this use-case."
-[pr_example_2]: https://github.com/devsectop/tf-via-pr/pull/166 "Example PR for this use-case."
-[terraform_io]: https://www.terraform.io "Terraform by Hashicorp."
diff --git a/docs/comment.png → docs/assets/comment.png b/docs/comment.png → docs/assets/comment.png
diff --git a/docs/revisions.png → docs/assets/revisions.png b/docs/revisions.png → docs/assets/revisions.png
diff --git a/sample/bucket/.terraform.lock.hcl b/sample/bucket/.terraform.lock.hcl
diff --git a/sample/bucket/README.md b/sample/bucket/README.md
diff --git a/sample/bucket/backend/dev.tfbackend b/sample/bucket/backend/dev.tfbackend
diff --git a/sample/bucket/backend/qa.tfbackend b/sample/bucket/backend/qa.tfbackend
diff --git a/sample/bucket/main.tf b/sample/bucket/main.tf
diff --git a/sample/bucket/providers.tf b/sample/bucket/providers.tf
diff --git a/sample/bucket/terraform.tfvars b/sample/bucket/terraform.tfvars
diff --git a/sample/bucket/variables.tf b/sample/bucket/variables.tf