docs: Add documentation to README (#3)

.github/workflows/e2e.yml

@@ -0,0 +1,38 @@
+name: End-to-End
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  simple-test:
+    name: Simple Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup terraform
+        uses: hashicorp/setup-terraform@v3
+      - name: Setup - initialize
+        run: terraform init
+        working-directory: tests/ci/0-setup
+      - name: Setup - apply
+        run: terraform apply -auto-approve -state ../.tfstate
+        working-directory: tests/ci/0-setup
+      - name: Change - initialize
+        run: terraform init
+        working-directory: tests/ci/1-change
+      - name: Change - plan
+        run: terraform plan -state ../.tfstate -out .planfile
+        working-directory: tests/ci/1-change
+      - name: Post PR comment
+        uses: ./
+        with:
+          token: ${{ github.token }}
+          planfile: .planfile
+          working-directory: tests/ci/1-change

README.md

@@ -1,3 +1,73 @@
 # terraform-plan-comment
 
 GitHub Action to post the output of `terraform plan` to a PR comment.
+
+## Features
+
+- Generate a "markdown-native" representation of the plan including foldable sections and coloring
+- Post the plan to pull requests as a "sticky comment"
+- Use with or without the Terraform wrapper script provided by
+  [hashicorp/setup-terraform](https://github.com/hashicorp/setup-terraform)
+
+## Usage
+
+```yaml
+- name: Setup terraform
+  uses: hashicorp/setup-terraform@v3
+- name: Initialize
+  run: terraform init
+- name: Plan
+  run: terraform plan -out .planfile
+- name: Post PR comment
+  uses: borchero/terraform-plan-comment@v1
+  with:
+    token: ${{ github.token }}
+    planfile: .planfile
+```
+
+### Example Comments
+
+<details><summary><b>Collapsed</b></summary>
+
+<img width="916" alt="Screenshot 2024-04-30 at 00 07 36" src="https://github.com/borchero/terraform-plan-comment/assets/22455425/b6d0e64c-1c9c-42b8-8060-c096922baa0a">
+
+</details>
+
+<details><summary><b>Expanded</b></summary>
+
+<img width="699" alt="Screenshot 2024-04-30 at 00 08 22" src="https://github.com/borchero/terraform-plan-comment/assets/22455425/c91c319a-276d-4d2d-98a7-52bd24b64d4c">
+
+</details>
+
+## Parameters
+
+This action provides a few input parameters that allow for customization:
+
+### `token` (required)
+
+Required input parameter to access the GitHub API for posting a pull request comment. Can be provided as
+`${{ github.token }}`, `${{ env.GITHUB_TOKEN }}` or some personal access token with appropriate permissions.
+
+If using the workflow-provided token, make sure that your workflow/job has write-permissions to pull requests.
+
+### `planfile` (required)
+
+The path to the planfile generated by `terraform plan` which holds the information about which changes ought to be
+applied.
+
+### `terraform-cmd`
+
+The command to execute to call the Terraform binary. Defaults to `terraform`. You likely don't need to augment this
+unless `terraform` cannot be found in the `PATH`.
+
+### `working-directory`
+
+The directory where the Terraform binary ought to be called. Defaults to `$GITHUB_WORKSPACE` and _must_ be specified if
+`terraform init` has been run in a different directory. Should be specified relative to `$GITHUB_WORKSPACE`.
+
+> [!IMPORTANT] > `planfile` must be specified relative to the working directory.
+
+### `id`
+
+A custom identifier for the Terraform execution. This allows to distinguish multiple Terraform runs: each sticky pull
+request comment is tied to an ID.

src/comment.ts

@@ -30,19 +30,19 @@ function renderBody(plan: RenderedPlan): string {
     `${Object.keys(plan.deletedResources ?? {}).length} to delete.**`
 
   if (plan.createdResources) {
-    body += '\n\n### Create'
+    body += '\n\n### ✨ Create'
     body += renderResources(plan.createdResources)
   }
   if (plan.updatedResources) {
-    body += '\n\n### Update'
+    body += '\n\n### ♻️ Update'
     body += renderResources(plan.updatedResources)
   }
   if (plan.recreatedResources) {
-    body += '\n\n### Re-Create'
+    body += '\n\n### ⚙️ Re-Create'
     body += renderResources(plan.recreatedResources)
   }
   if (plan.deletedResources) {
-    body += '\n\n### Delete'
+    body += '\n\n### 🗑️ Delete'
     body += renderResources(plan.deletedResources)
   }
 
@@ -71,7 +71,7 @@ export function renderComment({
   let footer = ''
   if (includeFooter === undefined || includeFooter === true) {
     footer =
-      `\n\n_Triggered by @${github.context.actor},` +
+      `\n\n---\n\n_Triggered by @${github.context.actor},` +
       ` Commit: \`${(github.context.payload as PullRequestEvent).pull_request.head.sha}\`_`
   }
 

tests/ci/0-setup/main.tf

@@ -0,0 +1,18 @@
+terraform {
+  required_providers {
+    local = {
+      source = "hashicorp/local"
+    }
+  }
+}
+
+variable "test" {
+  default   = 42
+  sensitive = true
+}
+
+resource "local_file" "test" {
+  count    = 2
+  filename = "../test.txt"
+  content  = "test-${var.test}"
+}

tests/ci/1-change/main.tf

@@ -0,0 +1,23 @@
+terraform {
+  required_providers {
+    local = {
+      source = "hashicorp/local"
+    }
+  }
+}
+
+variable "test" {
+  default   = 40
+  sensitive = true
+}
+
+resource "local_file" "test" {
+  count    = 1
+  filename = "../test.txt"
+  content  = "test-${var.test}"
+}
+
+resource "local_file" "another" {
+  filename = "../another.txt"
+  content  = "Hello terraform-plan-comment!"
+}

tests/fixtures/basic/0-create/main.tf

@@ -1,7 +1,7 @@
 terraform {
   required_providers {
-    null = {
-      source = "hashicorp/null"
+    local = {
+      source = "hashicorp/local"
     }
   }
 }

tests/fixtures/basic/0-create/rendered.md

@@ -2,7 +2,7 @@
 
 **→ Resource Changes: 1 to create, 0 to update, 0 to re-create, 0 to delete.**
 
-### Create
+### ✨ Create
 
 <details><summary><code>local_file.test</code></summary>
 

tests/fixtures/basic/1-modify/main.tf

@@ -1,7 +1,7 @@
 terraform {
   required_providers {
-    null = {
-      source = "hashicorp/null"
+    local = {
+      source = "hashicorp/local"
     }
   }
 }

tests/fixtures/basic/1-modify/rendered.md

@@ -2,7 +2,7 @@
 
 **→ Resource Changes: 0 to create, 0 to update, 1 to re-create, 0 to delete.**
 
-### Re-Create
+### ⚙️ Re-Create
 
 <details><summary><code>local_file.test</code></summary>
 

tests/fixtures/basic/2-delete/rendered.md

@@ -2,7 +2,7 @@
 
 **→ Resource Changes: 0 to create, 0 to update, 0 to re-create, 1 to delete.**
 
-### Delete
+### 🗑️ Delete
 
 <details><summary><code>local_file.test</code></summary>