feat: add terraform plan action with documentation

README.md

@@ -27,6 +27,7 @@ Shared actions for Forgejo CI/CD pipelines.
 | [terraform-validate](terraform-validate) | Validate Terraform configuration files using the official Terraform CLI |
 | [upload-artifact](upload-artifact) | Upload files as a Forgejo Actions artifact |
 | [vacuum-lint](vacuum-lint) | Validate and lint OpenAPI specifications using Vacuum |
+| [terraform-plan](terraform-plan) | Preview Terraform infrastructure changes (create, update, delete, replace) without applying them |
 
 ## Security
 

terraform-plan/README.md

@@ -0,0 +1,47 @@
+# terraform-plan
+
+Plan Terraform configuration files using the official Terraform CLI.
+
+## Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `terraform-dir` | No | `terraform` | Directory containing `.tf` files |
+| `terraform-version` | No | `~1.15` | Terraform version to use |
+| `var-file` | No | `""` | Path to `.tfvars` file, relative to `terraform-dir` |
+| `workspace` | No | `""` | Terraform workspace to select |
+| `jfrog-token` | No | `""` | JFrog Artifactory token for the Terraform provider registry (`TF_TOKEN_schmalz_jfrog_io`) |
+
+## Outputs
+
+No outputs are exported.
+
+Terraform `plan` only previews changes and does not produce finalized output values in state.
+
+## Usage
+
+```yaml
+- uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/terraform-plan@terraform-plan-v1
+  id: tf-plan
+  with:
+    workspace: stage
+    var-file: stage.tfvars
+    jfrog-token: ${{ secrets.JFROG_TOKEN }}
+``
+
+
+## Notes
+
+- Runs `terraform init`, selects the workspace according to PR, and executes `terraform plan`.
+- Does **not** apply any changes — it only previews what Terraform would do.
+- Helps identify infrastructure changes before execution, such as:
+  - Resources that will be created
+  - Resources that will be updated
+  - Resources that will be *deleted*
+  - Resources that will be replaced
+- Useful for reviewing changes in environments.
+- Helps detect unexpected changes caused by provider version updates, module updates, variable changes, or Terraform configuration changes.
+- Improves deployment safety by showing the impact of changes before `terraform apply`.
+- Sets `TF_TOKEN_schmalz_jfrog_io` on both `init` and `plan` steps if `jfrog-token` is provided.
+- If `var-file` is provided, it is passed as `-var-file` to the plan command.
+- Commonly used in CI for pre-apply visibility, especially in pull requests or staging validation workflows.

terraform-plan/action.yml

@@ -0,0 +1,82 @@
+name: Terraform Plan
+description: >
+  Init and plan Terraform configuration files using the official Terraform CLI.
+
+inputs:
+  terraform-dir:
+    description: Directory containing .tf files
+    required: false
+    default: terraform
+  terraform-version:
+    description: Terraform version to use
+    required: false
+    default: "~1.15"
+  var-file:
+    description: Path to .tfvars file, relative to terraform-dir
+    required: false
+    default: ""
+  workspace:
+    description: Terraform workspace to use
+    required: false
+    default: ""
+  jfrog-token:
+    description: JFrog Artifactory token used for Terraform provider registry (sets TF_TOKEN_schmalz_jfrog_io)
+    required: false
+    default: ""
+
+runs:
+  using: composite
+  steps:
+    # Pinned to commit SHA instead of a tag to prevent supply chain attacks.
+    # hashicorp/setup-terraform v4.0.0 — https://github.com/hashicorp/setup-terraform/commits/v4.0.0/
+    - name: Setup Terraform
+      uses: hashicorp/setup-terraform@5e8dbf3c6d9deaf4193ca7a8fb23f2ac83bb6c85
+      with:
+        terraform_version: ${{ inputs.terraform-version }}
+
+    # Plugin cache setup
+    - name: Set Terraform plugin cache directory
+      shell: bash
+      run: |
+        mkdir -p ~/.terraform.d/plugin-cache
+        echo "TF_PLUGIN_CACHE_DIR=$HOME/.terraform.d/plugin-cache" >> "$GITHUB_ENV"
+
+    # Cache providers
+    - name: Cache Terraform providers
+      uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/cache@cache-v1
+      with:
+        path: ~/.terraform.d/plugin-cache
+        key: ${{ runner.os }}-terraform-providers-${{ inputs.terraform-version }}-${{ hashFiles(format('{0}/.terraform.lock.hcl', inputs.terraform-dir)) }}
+        restore-keys: ${{ runner.os }}-terraform-providers-${{ inputs.terraform-version }}-
+
+    # Init (backend enabled)
+    - name: Terraform Init
+      shell: bash
+      env:
+        TF_TOKEN_schmalz_jfrog_io: ${{ inputs.jfrog-token }}
+        TF_DIR: ${{ inputs.terraform-dir }}
+      run: terraform -chdir="$TF_DIR" init -no-color
+
+    # Workspace selection
+    - name: Terraform Select Workspace
+      if: ${{ inputs.workspace != '' }}
+      shell: bash
+      env:
+        TF_DIR: ${{ inputs.terraform-dir }}
+        TF_WORKSPACE_NAME: ${{ inputs.workspace }}
+      run: |
+        terraform -chdir="$TF_DIR" workspace select -or-create "$TF_WORKSPACE_NAME"
+
+    # Plan step
+    - name: Terraform Plan
+      shell: bash
+      env:
+        TF_TOKEN_schmalz_jfrog_io: ${{ inputs.jfrog-token }}
+        TF_DIR: ${{ inputs.terraform-dir }}
+        VAR_FILE: ${{ inputs.var-file }}
+      run: |
+        ARGS="-no-color"
+        if [ -n "$VAR_FILE" ]; then
+          ARGS="$ARGS -var-file=$VAR_FILE"
+        fi
+        terraform -chdir="$TF_DIR" plan $ARGS