Update plan_path documentation

Author: dflook

terraform-apply/README.md

@@ -159,9 +159,22 @@ These input values must be the same as any [`dflook/terraform-plan`](https://git
 
 * `plan_path`
 
-  Path to a plan file to apply. This would have been generated by a previous [`dflook/terraform-plan`](https://github.com/dflook/terraform-github-actions/tree/main/terraform-plan)  action.
+  Path to a plan file to apply. This would have been generated by a previous [`dflook/terraform-plan`](https://github.com/dflook/terraform-github-actions/tree/main/terraform-plan) action.
 
-  When not supplied, a new plan will be generated.
+  The default behaviour when this is not set is to generate a plan from the current configuration and compare it to the plan attached to the PR comment.
+  If it is logically the same, the plan will be applied.
+
+  When this is set to a plan file, the plan will not be generated again. If it is the exact same plan as the one attached to the PR comment, it will be applied.
+  This will be faster than generating a new plan.
+
+  There are downsides to applying a stored plan:
+    - The plan may contain sensitive information so must be stored securely, possibly outside of GitHub.
+    - It does not account for any changes that have occurred since it was generated, and may no longer be correct.
+    - Plans must be generated and applied in strict order. Multiple open PRs will cause conflicts if they are applied out of order.
+    - Plans are not portable between platforms.
+    - Terraform and provider versions must match between the plan generation and apply.
+
+  When `auto_approve` is set to `true`, the plan will be applied without checking if it is the same as the one attached to the PR comment.
 
   - Type: string
   - Optional

terraform-plan/README.md

@@ -313,13 +313,19 @@ The [dflook/terraform-apply](https://github.com/dflook/terraform-github-actions/
   This is the path to the generated plan in an opaque binary format.
   The path is relative to the Actions workspace.
 
+  The plan can be used as the `plan_file` input to the [dflook/terraform-apply](https://github.com/dflook/terraform-github-actions/tree/main/terraform-apply) action.
+
+  Terraform plans often contain sensitive information, so this output should be treated with care.
+
   - Type: string
 
 * `json_plan_path`
 
   This is the path to the generated plan in [JSON Output Format](https://www.terraform.io/docs/internals/json-format.html)
   The path is relative to the Actions workspace.
 
+  Terraform plans often contain sensitive information, so this output should be treated with care.
+
   - Type: string
 
 * `text_plan_path`
@@ -330,20 +336,12 @@ The [dflook/terraform-apply](https://github.com/dflook/terraform-github-actions/
   - Type: string
 
 * `to_add`
-
-  The number of resources that would be added by this plan.
-
-  - Type: number
-
 * `to_change`
-
-  The number of resources that would be changed by this plan.
-
-  - Type: number
-
 * `to_destroy`
+* `to_move`
+* `to_import`
 
-  The number of resources that would be destroyed by this plan.
+  The number of resources that would be affected by each type of operation.
 
   - Type: number
 

tofu-apply/README.md

@@ -159,9 +159,22 @@ These input values must be the same as any [`dflook/tofu-plan`](https://github.c
 
 * `plan_path`
 
-  Path to a plan file to apply. This would have been generated by a previous [`dflook/tofu-plan`](https://github.com/dflook/terraform-github-actions/tree/main/tofu-plan)  action.
+  Path to a plan file to apply. This would have been generated by a previous [`dflook/tofu-plan`](https://github.com/dflook/terraform-github-actions/tree/main/tofu-plan) action.
 
-  When not supplied, a new plan will be generated.
+  The default behaviour when this is not set is to generate a plan from the current configuration and compare it to the plan attached to the PR comment.
+  If it is logically the same, the plan will be applied.
+
+  When this is set to a plan file, the plan will not be generated again. If it is the exact same plan as the one attached to the PR comment, it will be applied.
+  This will be faster than generating a new plan.
+
+  There are downsides to applying a stored plan:
+    - The plan may contain sensitive information so must be stored securely, possibly outside of GitHub.
+    - It does not account for any changes that have occurred since it was generated, and may no longer be correct.
+    - Plans must be generated and applied in strict order. Multiple open PRs will cause conflicts if they are applied out of order.
+    - Plans are not portable between platforms.
+    - OpenTofu and provider versions must match between the plan generation and apply.
+
+  When `auto_approve` is set to `true`, the plan will be applied without checking if it is the same as the one attached to the PR comment.
 
   - Type: string
   - Optional

tofu-plan/README.md

@@ -313,13 +313,19 @@ The [dflook/tofu-apply](https://github.com/dflook/terraform-github-actions/tree/
   This is the path to the generated plan in an opaque binary format.
   The path is relative to the Actions workspace.
 
+  The plan can be used as the `plan_file` input to the [dflook/tofu-apply](https://github.com/dflook/terraform-github-actions/tree/main/tofu-apply) action.
+
+  OpenTofu plans often contain sensitive information, so this output should be treated with care.
+
   - Type: string
 
 * `json_plan_path`
 
   This is the path to the generated plan in [JSON Output Format](https://www.terraform.io/docs/internals/json-format.html)
   The path is relative to the Actions workspace.
 
+  OpenTofu plans often contain sensitive information, so this output should be treated with care.
+
   - Type: string
 
 * `text_plan_path`
@@ -330,20 +336,12 @@ The [dflook/tofu-apply](https://github.com/dflook/terraform-github-actions/tree/
   - Type: string
 
 * `to_add`
-
-  The number of resources that would be added by this plan.
-
-  - Type: number
-
 * `to_change`
-
-  The number of resources that would be changed by this plan.
-
-  - Type: number
-
 * `to_destroy`
+* `to_move`
+* `to_import`
 
-  The number of resources that would be destroyed by this plan.
+  The number of resources that would be affected by each type of operation.
 
   - Type: number