Merge pull request 'docs: document how to add a new action' (!54) from aws-lambda-releases into main

Reviewed-on: #54
Reviewed-by: Michael.Seele@schmalz.de <Michael.Seele@schmalz.de>

.forgejo/workflows/tag-release.yml

@@ -16,6 +16,8 @@ on:
           - aikido-full-scan
           - aikido-pr-scan
           - aws-configure
+          - aws-lambda-alias-update
+          - aws-lambda-wait-for-provisioned-concurrency
           - cache
           - checkout
           - download-artifact
@@ -24,14 +26,15 @@ on:
           - i18n-sync
           - inject-content
           - maven-build
-          - pnpm-build
           - playwright-merge
           - playwright-run
+          - pnpm-build
           - publish-npm-package
           - publish-rust-crate
           - publish-static-contents
           - rust-build
           - terraform-apply
+          - terraform-plan
           - terraform-validate
           - upload-artifact
           - vacuum-lint

README.md

@@ -9,6 +9,8 @@ Shared actions for Forgejo CI/CD pipelines.
 | [aikido-full-scan](aikido-full-scan) | Aikido full scan |
 | [aikido-pr-scan](aikido-pr-scan) | Aikido PR scan |
 | [aws-configure](aws-configure) | Authenticate with AWS via OIDC |
+| [aws-lambda-alias-update](aws-lambda-alias-update) | Update Aliases of Lambda Functions to a new Version |
+| [aws-lambda-wait-for-provisioned-concurrency](aws-lambda-wait-for-provisioned-concurrency) | Wait until the Provisioned Concurrency is Ready for Lambda Functions  |
 | [cache](cache) | Cache files between workflow runs |
 | [checkout](checkout) | Action for checking out a repository |
 | [download-artifact](download-artifact) | Download Forgejo Actions artifacts by name or pattern |
@@ -16,14 +18,15 @@ Shared actions for Forgejo CI/CD pipelines.
 | [i18n-sync](i18n-sync) | Fetch translations from i18n.schmalz.com and open a pull request |
 | [inject-content](inject-content) | Inject content into a file by appending or overwriting |
 | [maven-build](maven-build) | Action for building and validating Maven projects |
-| [pnpm-build](pnpm-build) | Action for building and validating with PNPM |
 | [playwright-merge](playwright-merge) | Merge Playwright shard blob reports and publish consolidated reports |
 | [playwright-run](playwright-run) | Run Playwright tests for one shard and upload its blob report |
+| [pnpm-build](pnpm-build) | Action for building and validating with PNPM |
 | [publish-npm-package](publish-npm-package) | Publish a PNPM package to JFrog Artifactory |
 | [publish-rust-crate](publish-rust-crate) | Publish a Rust crate to JFrog Artifactory |
 | [publish-static-contents](publish-static-contents) | Syncs frontend assets to S3 and invalidates a CloudFront distribution |
 | [rust-build](rust-build) | Set up Rust toolchain, run checks, and build via the project's build.sh |
 | [terraform-apply](terraform-apply) | Apply Terraform configuration files using the official Terraform CLI |
+| [terraform-plan](terraform-plan) | Preview Terraform infrastructure changes (create, update, delete, replace) without applying them |
 | [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 |
@@ -32,6 +35,26 @@ Shared actions for Forgejo CI/CD pipelines.
 
 Where third-party Forgejo/GitHub Actions are used internally, they are pinned to exact commit hashes rather than mutable tags to prevent supply chain attacks.
 
+## Adding a new Action
+
+- Create a new directory for the action
+- Implement the action
+- Add a `README.md` file that describes (1) purpose, (2) inputs using a table, (3) example usage, and additional details if requried to the action directory
+- Update the table in the main README (this file) with a new row. The list is sorted alphabetically.
+- Update the `tag-release.yml` workflow in the `.forgejo/` directory if the action is a public action: Add the name to the option list.
+
+## Releasing a new Version
+
+**We only use Major-Versions, e.g. `1`, `2`, `3`, etc.**
+
+- Decide which Version to use
+  - Breaking Change: Increment the current version by one (e.g. `1 -> 2`)
+  - All non-breaking changes: Stay on the current major version (`1 -> 1`)
+- Manually run the `tag-release.yml` workflow
+  - Branch: `main`
+  - Action: Name of the Action to release
+  - Version: The version to release
+
 ## Usage
 
 Reference actions from your project's workflow:

aws-lambda-alias-update/README.md

@@ -0,0 +1,84 @@
+# aws-lambda-alias-update
+
+Composite action that updates Lambda function aliases from a Terraform output. Iterates over the `lambda_alias_updates` Terraform output and calls `aws lambda update-alias` for each entry.
+
+**Example `lambda-alias-updates` input:**
+
+```json
+[
+  "{\"alias_name\": \"live\", \"function_name\": \"my-get-product\", \"version\": \"42\"}",
+  "{\"alias_name\": \"live\", \"function_name\": \"my-get-category\", \"version\": \"7\"}"
+]
+```
+
+## Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `lambda-alias-updates` | Yes | — | JSON array of Lambda alias update objects (Terraform output: `lambda_alias_updates`). Each element is a JSON-encoded string with `alias_name`, `function_name`, and `version`. |
+
+## Usage
+
+```yaml
+- name: Update Lambda Aliases
+  uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/aws-lambda-alias-update@aws-lambda-alias-update-v1
+  with:
+    lambda-alias-updates: ${{ steps.tf-apply.outputs.lambda_alias_updates }}
+```
+
+## Terraform Setup
+
+- Add the following content to the project
+- Add all Lambda Modules to the `provisioned_lambda_modules` list for which the Function Alias and/or Provisioned Concurrency should be updated
+
+**`output.tf`**
+```tf
+locals {
+  // List of Lambda Modules that have provisioned concurrency configured.
+  // Required to update the aliases of these functions after deployment.
+  provisioned_lambda_modules = [
+    module.lambda_get_category,
+    module.lambda_product_get_full_slug,
+    module.lambda_get_product,
+  ]
+}
+
+// Output which allows Updates of Lambda Alias and Provisioned Concurrency
+output "lambda_alias_updates" {
+  value = concat([for module in local.provisioned_lambda_modules : "{\"alias_name\": \"${module.lambda_alias_name}\", \"function_name\": \"${module.lambda_name}\", \"version\": \"${module.lambda_version}\" }"])
+}
+
+```
+
+## Example Usage with other Shared Actions
+
+```yml
+jobs:
+  deploy-stage:
+    name: Build and Deploy to Stage
+    runs-on: stackit-ubuntu-22
+    steps:
+      - name: Apply Terraform
+        uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/terraform-apply@terraform-apply-v1
+        id: tf-apply
+        with:
+          terraform-version: 1.14.9
+          workspace: stage
+          var-file: stage.tfvars
+          jfrog-token: ${{ secrets.JFROG_TOKEN }}
+
+      - name: Update Lambda Aliases
+        uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/aws-lambda-alias-update@aws-lambda-alias-update-v1
+        with:
+          lambda-alias-updates: ${{ steps.tf-apply.outputs.lambda_alias_updates }}
+
+      - name: Wait for Lambda Provisioned Concurrency
+        uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/aws-lambda-wait-for-provisioned-concurrency@aws-lambda-wait-for-provisioned-concurrency-v1
+        with:
+          lambda-alias-updates: ${{ steps.tf-apply.outputs.lambda_alias_updates }}
+```
+
+## Notes
+
+- Expects the `lambda-alias-updates` input to be the raw `lambda_alias_updates` output from the `terraform-apply` action.
+- Requires AWS credentials to be configured in the job before this step runs.

aws-lambda-alias-update/action.yml

@@ -0,0 +1,49 @@
+name: "AWS Lambda - Update Alias"
+description: >
+  Updates Lambda function aliases from a Terraform output.
+  Iterates over the lambda_alias_updates Terraform output and calls
+  aws lambda update-alias for each entry.
+
+inputs:
+  lambda-alias-updates:
+    description: >
+      JSON array of Lambda alias update objects (Terraform output: lambda_alias_updates).
+      Each element is a JSON-encoded string with alias_name, function_name, and version.
+    required: true
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install AWS CLI
+      shell: bash
+      run: |
+        if ! command -v aws &> /dev/null; then
+          curl -fsSL "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o /tmp/awscliv2.zip
+          unzip -q /tmp/awscliv2.zip -d /tmp
+          sudo /tmp/aws/install
+          rm -rf /tmp/awscliv2.zip /tmp/aws
+        fi
+
+    - name: Install jq if missing
+      shell: bash
+      run: |
+        set -euo pipefail
+        command -v jq >/dev/null 2>&1 || sudo apt-get install -y --no-install-recommends jq
+
+    - name: Update Lambda Aliases
+      shell: bash
+      env:
+        LAMBDA_ALIAS_UPDATES: ${{ inputs.lambda-alias-updates }}
+      run: |
+        echo "$LAMBDA_ALIAS_UPDATES" | jq -c '.[] | fromjson' | while IFS= read -r entry; do
+          alias_name=$(echo "$entry" | jq -r '.alias_name')
+          function_name=$(echo "$entry" | jq -r '.function_name')
+          version=$(echo "$entry" | jq -r '.version')
+          echo "Updating alias '$alias_name' for '$function_name' to version '$version'"
+          aws lambda update-alias \
+            --no-cli-pager \
+            --name "$alias_name" \
+            --function-name "$function_name" \
+            --function-version "$version"
+          echo "Updated alias '$alias_name' for '$function_name' to version '$version'"
+        done

aws-lambda-wait-for-provisioned-concurrency/README.md

@@ -0,0 +1,86 @@
+# aws-lambda-wait-for-provisioned-concurrency
+
+Composite action that waits for provisioned concurrency to reach `READY` status for all Lambda functions listed in the Terraform `lambda_alias_updates` output. Iterates over the `lambda_alias_updates` Terraform output and polls `aws lambda get-provisioned-concurrency-config` for each entry until the status is `READY` or `FAILED`.
+
+**Example `lambda-alias-updates` input:**
+
+```json
+[
+  "{\"alias_name\": \"live\", \"function_name\": \"my-get-product\", \"version\": \"42\"}",
+  "{\"alias_name\": \"live\", \"function_name\": \"my-get-category\", \"version\": \"7\"}"
+]
+```
+
+## Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `lambda-alias-updates` | Yes | — | JSON array of Lambda alias update objects (Terraform output: `lambda_alias_updates`). Each element is a JSON-encoded string with `alias_name`, `function_name`, and `version`. |
+
+## Usage
+
+```yaml
+- name: Wait for Lambda Provisioned Concurrency
+  uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/aws-lambda-wait-for-provisioned-concurrency@aws-lambda-wait-for-provisioned-concurrency-v1
+  with:
+    lambda-alias-updates: ${{ steps.tf-apply.outputs.lambda_alias_updates }}
+```
+
+## Terraform Setup
+
+- Add the following content to the project
+- Add all Lambda Modules to the `provisioned_lambda_modules` list for which the Function Alias and/or Provisioned Concurrency should be updated
+
+**`output.tf`**
+```tf
+locals {
+  // List of Lambda Modules that have provisioned concurrency configured.
+  // Required to update the aliases of these functions after deployment.
+  provisioned_lambda_modules = [
+    module.lambda_get_category,
+    module.lambda_product_get_full_slug,
+    module.lambda_get_product,
+  ]
+}
+
+// Output which allows Updates of Lambda Alias and Provisioned Concurrency
+output "lambda_alias_updates" {
+  value = concat([for module in local.provisioned_lambda_modules : "{\"alias_name\": \"${module.lambda_alias_name}\", \"function_name\": \"${module.lambda_name}\", \"version\": \"${module.lambda_version}\" }"])
+}
+
+```
+
+## Example Usage with other Shared Actions
+
+```yml
+jobs:
+  deploy-stage:
+    name: Build and Deploy to Stage
+    runs-on: stackit-ubuntu-22
+    steps:
+      - name: Apply Terraform
+        uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/terraform-apply@terraform-apply-v1
+        id: tf-apply
+        with:
+          terraform-version: 1.14.9
+          workspace: stage
+          var-file: stage.tfvars
+          jfrog-token: ${{ secrets.JFROG_TOKEN }}
+
+      - name: Update Lambda Aliases
+        uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/aws-lambda-alias-update@aws-lambda-alias-update-v1
+        with:
+          lambda-alias-updates: ${{ steps.tf-apply.outputs.lambda_alias_updates }}
+
+      - name: Wait for Lambda Provisioned Concurrency
+        uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/aws-lambda-wait-for-provisioned-concurrency@aws-lambda-wait-for-provisioned-concurrency-v1
+        with:
+          lambda-alias-updates: ${{ steps.tf-apply.outputs.lambda_alias_updates }}
+```
+
+## Notes
+
+- Expects the `lambda-alias-updates` input to be the raw `lambda_alias_updates` output from the `terraform-apply` action.
+- Functions without provisioned concurrency configured are skipped automatically.
+- If provisioned concurrency reaches `FAILED` status, the action logs a warning and continues without failing the workflow.
+- Requires AWS credentials to be configured in the job before this step runs.

aws-lambda-wait-for-provisioned-concurrency/action.yml

@@ -0,0 +1,64 @@
+name: "AWS Lambda - Wait for Provisioned Concurrency"
+description: >
+  Waits for provisioned concurrency to reach READY status for all Lambda
+  functions listed in the Terraform lambda_alias_updates output.
+
+inputs:
+  lambda-alias-updates:
+    description: >
+      JSON array of Lambda alias update objects (Terraform output: lambda_alias_updates).
+      Each element is a JSON-encoded string with alias_name, function_name, and version.
+    required: true
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install AWS CLI
+      shell: bash
+      run: |
+        if ! command -v aws &> /dev/null; then
+          curl -fsSL "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o /tmp/awscliv2.zip
+          unzip -q /tmp/awscliv2.zip -d /tmp
+          sudo /tmp/aws/install
+          rm -rf /tmp/awscliv2.zip /tmp/aws
+        fi
+
+    - name: Install jq if missing
+      shell: bash
+      run: |
+        set -euo pipefail
+        command -v jq >/dev/null 2>&1 || sudo apt-get install -y --no-install-recommends jq
+
+    - name: Wait for Lambda Provisioned Concurrency
+      shell: bash
+      env:
+        LAMBDA_ALIAS_UPDATES: ${{ inputs.lambda-alias-updates }}
+      run: |
+        echo "$LAMBDA_ALIAS_UPDATES" | jq -c '.[] | fromjson' | while IFS= read -r entry; do
+          function_name=$(echo "$entry" | jq -r '.function_name')
+          alias_name=$(echo "$entry" | jq -r '.alias_name')
+          if aws lambda get-provisioned-concurrency-config \
+              --no-cli-pager \
+              --function-name "$function_name" \
+              --qualifier "$alias_name" >/dev/null 2>&1; then
+            echo "Provisioned concurrency found, waiting for READY status... ($function_name:$alias_name)"
+            while true; do
+              STATUS=$(aws lambda get-provisioned-concurrency-config \
+                --no-cli-pager \
+                --function-name "$function_name" \
+                --qualifier "$alias_name" \
+                --query 'Status' \
+                --output text 2>/dev/null || echo "FAILED")
+              echo "Current status: $STATUS ($function_name:$alias_name)"
+              if [[ "$STATUS" == "READY" ]]; then
+                echo "Provisioned Concurrency - Ready ($function_name:$alias_name)"
+                break
+              elif [[ "$STATUS" == "FAILED" ]]; then
+                echo "Provisioned concurrency failed, continuing anyway ($function_name:$alias_name)"
+                break
+              fi
+            done
+          else
+            echo "No provisioned concurrency configured, skipping wait ($function_name:$alias_name)"
+          fi
+        done

maven-build/action.yml

@@ -94,6 +94,7 @@ runs:
       env:
         VERIFY_GOALS: ${{ inputs.verify-goals }}
         EXTRA_ARGS: ${{ inputs.extra-args }}
+        MAVEN_PROFILE: ${{ inputs.maven-profile }}
       run: |
         mvn --batch-mode $VERIFY_GOALS \
           -s /tmp/maven-settings.xml \

playwright-run/README.md

@@ -12,18 +12,47 @@ Run Playwright E2E tests for one shard and upload the blob report as an artifact
 | `jfrog-token` | No | `""` | JFrog npm auth token |
 | `shard-index` | No | `1` | Current shard index (1-based). Set to `1` when not sharding. |
 | `shard-total` | No | `1` | Total number of shards. Set to `1` to disable sharding. |
+| `no-deps` | No | `false` | Skip dependencies between Playwright projects (e.g. setup/teardown). Passes `--no-deps` to Playwright. |
+| `projects` | No | `""` | Comma-separated list of Playwright projects to run (e.g. `chromium,firefox,Mobile Chrome`). Leave empty to use the Playwright default. |
 | `artifact-retention-days` | No | `3` | Number of days to retain the blob report artifact |
 
 ## Usage
 
+### Basic
+
 ```yaml
 - uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/playwright-run@playwright-run-v1
+  with:
+    working-directory: e2e
+    node-version: 22
+    jfrog-token: ${{ secrets.JFROG_TOKEN }}
+```
+
+### Sharded
+
+```yaml
+jobs:
+  test:
+    name: "Test Shard ${{ matrix.shard-index }}/${{ matrix.total }}"
+    # Define the matrix strategy on the parent job: 
+    strategy:
+      fail-fast: false
+      matrix:
+        total: [5] # The same for all instances
+        shard-index: [1, 2, 3, 4, 5]
+    steps:
+      # ...other steps like checkout repo etc.
+      - name: Run tests
+        uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/playwright-run@playwright-run-v1
         with:
           working-directory: frontend
           node-version: 22
           jfrog-token: ${{ secrets.JFROG_TOKEN }}
+          # Matrix data is passed here:
           shard-index: ${{ matrix.shard-index }}
-    shard-total: 5
+          shard-total: ${{ matrix.total }}
+          no-deps: "true"
+          projects: "chromium,firefox,webkit,Mobile Chrome,Mobile Safari"
 ```
 
 ## Notes

playwright-run/action.yml

@@ -29,6 +29,14 @@ inputs:
     description: Total number of shards. Set to 1 to disable sharding.
     required: false
     default: "1"
+  no-deps:
+    description: Whether to ignore dependencies between Playwright projects (e.g. setup, teardown)
+    required: false
+    default: false
+  projects:
+    description: Comma-separated list of Playwright projects to include, leave empty to use the Playwright default
+    required: false
+    default: ""
   artifact-retention-days:
     description: Number of days to retain the blob report artifact
     required: false
@@ -70,12 +78,25 @@ runs:
         WORKING_DIR: ${{ inputs.working-directory }}
         SHARD_INDEX: ${{ inputs.shard-index }}
         SHARD_TOTAL: ${{ inputs.shard-total }}
+        NO_DEPS: ${{ inputs.no-deps }}
+        PROJECTS: ${{ inputs.projects }}
       run: |
         SHARD_ARG=""
         if [ "${SHARD_TOTAL}" != "1" ]; then
           SHARD_ARG="--shard=${SHARD_INDEX}/${SHARD_TOTAL}"
         fi
-        pnpm --prefix="${WORKING_DIR}" exec playwright test ${SHARD_ARG} --reporter=blob,dot
+        NO_DEPS_ARG=""
+        if [ "${NO_DEPS}" == "true" ]; then
+          NO_DEPS_ARG="--no-deps"
+        fi
+        PROJECTS_ARG=()
+        if [ -n "${PROJECTS}" ]; then
+          IFS=',' read -ra PROJECT_LIST <<< "${PROJECTS}"
+          for project in "${PROJECT_LIST[@]}"; do
+            PROJECTS_ARG+=("--project=${project}")
+          done
+        fi
+        pnpm --prefix="${WORKING_DIR}" exec playwright test ${SHARD_ARG} ${NO_DEPS_ARG} "${PROJECTS_ARG[@]}" --reporter=blob,dot
 
     - name: Upload blob report
       if: ${{ !cancelled() }}

rust-build/action.yml

@@ -92,7 +92,7 @@ runs:
         for check in "${CHECKS[@]}"; do
           case "${check}" in
             fmt)    cargo fmt --manifest-path="${WORKING_DIR}/Cargo.toml" --check ;;
-            clippy) cargo clippy --manifest-path="${WORKING_DIR}/Cargo.toml" --target="${CROSS_TARGET}" -- -D warnings ;;
+            clippy) cargo clippy --manifest-path="${WORKING_DIR}/Cargo.toml" --target="${CROSS_TARGET}" ;;
             test)   cargo test --manifest-path="${WORKING_DIR}/Cargo.toml" ;;
             *)      echo "Unknown check: ${check}"; exit 1 ;;
           esac

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