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/pr-check-aikido.yml

@@ -2,8 +2,6 @@ name: Aikido Security PR Check
 
 on:
   pull_request:
-    branches:
-      - '*'
 
 concurrency:
   group: ${{ forgejo.workflow }}-${{ forgejo.ref }}

.forgejo/workflows/pr-check-shared-actions.yml

@@ -2,7 +2,6 @@ name: validate-shared-actions
 
 on:
   pull_request:
-    types: [opened, reopened, synchronize]
 
 permissions:
   contents: read

.forgejo/workflows/tag-release.yml

@@ -16,15 +16,28 @@ on:
           - aikido-full-scan
           - aikido-pr-scan
           - aws-configure
+          - aws-lambda-alias-update
+          - aws-lambda-wait-for-provisioned-concurrency
           - cache
           - checkout
+          - download-artifact
+          - esb-deploy
           - helm-deploy
+          - i18n-sync
           - inject-content
           - maven-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
       major-version:
         description: 'Major version number (e.g. 1)'
         required: true

README.md

@@ -9,21 +9,52 @@ 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 |
 | [helm-deploy](helm-deploy) | Deploy a service to Kubernetes via Helm over SSH |
+| [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 |
+| [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 |
 
 ## Security
 
 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:
@@ -34,4 +65,4 @@ Reference actions from your project's workflow:
     # see each action's README for inputs
 ```
 
-Each action has its own README with inputs, usage examples, and notes.
+Each action has its own README with inputs, usage examples, and notes.

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

download-artifact/README.md

@@ -0,0 +1,46 @@
+# download-artifact
+
+Download Forgejo Actions artifacts by name or pattern. Thin wrapper around `forgejo/download-artifact` pinned to a specific commit SHA to prevent supply chain attacks.
+
+## Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `name` | No | `""` | Exact artifact name or glob pattern (e.g. `blob-report-*`). If omitted, all artifacts for the run are downloaded. |
+| `path` | No | `.` | Local destination directory |
+| `merge-multiple` | No | `false` | When true, merge all matched artifacts into a single directory |
+
+## Usage
+
+Download a single artifact by name:
+
+```yaml
+- uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/download-artifact@download-artifact-v1
+  with:
+    name: my-artifact
+    path: dist/
+```
+
+Download all artifacts matching a pattern and merge into one directory:
+
+```yaml
+- uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/download-artifact@download-artifact-v1
+  with:
+    name: blob-report-*
+    path: all-blob-reports/
+    merge-multiple: "true"
+```
+
+Download all artifacts for the run:
+
+```yaml
+- uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/download-artifact@download-artifact-v1
+  with:
+    path: artifacts/
+```
+
+## Notes
+
+- Wraps `forgejo/download-artifact` v4 (node20), compatible with Ubuntu 22 runners.
+- The underlying action is pinned to a commit SHA rather than a mutable tag to prevent supply chain attacks.
+- When `merge-multiple` is false (default), each matched artifact is extracted into its own subdirectory under `path`.

download-artifact/action.yml

@@ -0,0 +1,30 @@
+name: Schmalz Download Artifact
+description: >
+  Download Forgejo Actions artifacts by name or pattern.
+  Thin wrapper around forgejo/download-artifact, pinned to a specific SHA.
+
+inputs:
+  name:
+    description: Exact artifact name or glob pattern (e.g. 'blob-report-*'). If omitted, all artifacts for the run are downloaded.
+    required: false
+    default: ""
+  path:
+    description: Local destination directory
+    required: false
+    default: "."
+  merge-multiple:
+    description: When true, merge all matched artifacts into a single directory
+    required: false
+    default: "false"
+
+runs:
+  using: composite
+  steps:
+    # Pinned to commit SHA instead of a tag to prevent supply chain attacks.
+    # forgejo/download-artifact v4 — https://code.forgejo.org/forgejo/download-artifact/commits/tag/v4
+    - name: Download artifact
+      uses: https://code.forgejo.org/forgejo/download-artifact@d8d0a99033603453ad2255e58720b460a0555e1e
+      with:
+        name: ${{ inputs.name }}
+        path: ${{ inputs.path }}
+        merge-multiple: ${{ inputs.merge-multiple }}

esb-deploy/README.md

@@ -0,0 +1,32 @@
+# esb-deploy
+
+Deploy a service to an ESB docker host.
+
+## Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `docker-host` | Yes | - | esbdb3.schmalzgroup.net, esbdb4.schmalzgroup.net, esbdb2-stage.schmalzgroup.net|
+| `java-version` | Yes | 25 | Same as default of the maven-build action |
+| `maven-profile` | No | `test` | Maven profile to activate during deploy |
+| `maven-settings` | **Yes** | — | Secret containing the `settings.xml` content used for repository authentication |
+| `service` | Yes | — | Name of the service to deploy |
+| `stage` | No | true | If true this is a stage deployment |
+
+## Usage
+
+```yaml
+- uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/esb-deploy@esb-deploy-v1
+  with:
+    service: my-service
+    docker-host: esbdocker2-stage.schmalzgroup.net
+    java-version: 8
+    maven-profile: test
+    maven-settings: ${{ secrets.MAVEN_SETTINGS }}
+    stage: true
+```
+
+## Notes
+
+- The compose files are extracted from variables. They can be provided on the organization or repository level.
+- The action uses the maven-build action to build the service. The pom.xml has to be in the root directory

esb-deploy/action.yml

@@ -0,0 +1,64 @@
+name: Deploy ESB
+description: Deploy a service to an ESB docker host.
+
+inputs:
+  docker-host:
+    description: Docker host to deploy to
+    required: true
+  maven-profile:
+    required: false
+    default: 'test'
+    description: 'Maven profile to use for the build'
+  maven-settings:
+    description: Secret containing the settings.xml content used for repository authentication
+    required: true
+  java-version:
+    description: Java version to use for the build
+    required: true
+  service:
+    description: Name of the service to deploy
+    required: true
+  stage:
+    description: Whether to deploy to stage environment (true) or production environment (false)
+    required: false
+    default: 'true'
+
+runs:
+  using: composite
+  steps:
+    - name: Create compose files
+      shell: bash
+      env:
+        BASE_COMPOSE: ${{ vars.DOCKER_COMPOSE }}
+        SU_COMPOSE: ${{ vars.DOCKER_COMPOSE_SU }}
+      run: |
+         printf '%s\n' "$BASE_COMPOSE" > compose.yml
+         printf '%s\n' "$SU_COMPOSE" > compose-su.yml
+
+    - uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/maven-build@maven-build-v1
+      with:
+        phase: verify
+        maven-settings: ${{ inputs.maven-settings }}
+        verify-goals: clean package
+        java-version: ${{ inputs.java-version }}
+        maven-profile: ${{ inputs.maven-profile}}
+
+    - name: Compose stage
+      if: ${{ inputs.stage == 'true' }}
+      shell: bash
+      env: 
+        SERVICE: ${{ inputs.service }}
+      run: |
+        echo "Deploying $SERVICE to stage environment"
+        export DOCKER_HOST="tcp://${{ inputs.docker-host }}:2375"
+        docker compose -f compose.yml -f compose-su.yml up -d --build --no-deps "$SERVICE"
+
+    - name: Compose prod
+      if: ${{ inputs.stage != 'true' }}
+      shell: bash
+      env: 
+        SERVICE: ${{ inputs.service }}
+      run: |
+        echo "Deploying $SERVICE to production environment"
+        export DOCKER_HOST="tcp://${{ inputs.docker-host }}:2375"
+        docker compose -f compose.yml up -d --build  --no-deps "$SERVICE"

helm-deploy/README.md

@@ -7,7 +7,7 @@ Deploy a service to Kubernetes via Helm over SSH.
 | Input | Required | Default | Description |
 |-------|----------|---------|-------------|
 | `service-name` | Yes | — | Helm release name |
-| `helm-host` | Yes | — | SSH target host (e.g. `dsp1-stage.schmalzgroup.net`) |
+| `helm-cluster` | Yes | — | Cluster to deploye to (one of `internal_stage` or `internal_prod`) |
 | `image-tag` | Yes | — | Docker image tag to deploy |
 | `ssh-key` | Yes | — | Private SSH key content |
 | `overrides-file` | No | `kubernetes/overrides-pu.yaml` | Local path to Helm values override file |

helm-deploy/action.yml

@@ -5,8 +5,8 @@ inputs:
   service-name:
     description: Helm release name
     required: true
-  helm-host:
+  helm-cluster:
-    description: SSH target (e.g., dsp1-stage.schmalzgroup.net)
+    description: Name of the target Kubernetes cluster to deploy to
     required: true
   overrides-file:
     description: Local path to Helm values override file
@@ -45,10 +45,22 @@ runs:
         chmod 600 "$SSH_KEY_FILE"
         echo "SSH_KEY_FILE=$SSH_KEY_FILE" >> "$GITHUB_ENV"
 
+    - name: Map cluster name to target host
+      id: map-host
+      shell: bash
+      env:
+        HELM_CLUSTER: ${{ inputs.helm-cluster }}
+      run: |
+        case "$HELM_CLUSTER" in
+          internal_stage) echo "host=dsp1-stage.schmalzgroup.net" ;;
+          internal_prod) echo "host=dsp1.schmalzgroup.net" ;;
+          *) echo "Invalid cluster '$HELM_CLUSTER'. Must be 'internal_stage' or 'internal_prod'." && exit 1 ;;
+        esac >> "$GITHUB_OUTPUT"
+
     - name: Copy overrides file
       shell: bash
       env:
-        HELM_HOST: ${{ inputs.helm-host }}
+        HELM_HOST: ${{ steps.map-host.outputs.host }}
         SERVICE_NAME: ${{ inputs.service-name }}
         OVERRIDES_FILE: ${{ inputs.overrides-file }}
       run: |
@@ -63,7 +75,7 @@ runs:
     - name: Helm deploy
       shell: bash
       env:
-        HELM_HOST: ${{ inputs.helm-host }}
+        HELM_HOST: ${{ steps.map-host.outputs.host }}
         SERVICE_NAME: ${{ inputs.service-name }}
         NAMESPACE: ${{ inputs.namespace }}
         HELM_REPO: ${{ inputs.helm-repo }}

i18n-sync/README.md

@@ -0,0 +1,46 @@
+# i18n-sync
+
+Fetches the latest translations from i18n.schmalz.com, commits them to a `chore/i18n` branch, and opens a pull request against the destination branch.
+
+## Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `i18n-application` | Yes | — | Application key in i18n.schmalz.com (e.g. `calculator`) |
+| `locales-folder` | No | `locales` | Path to the locales directory relative to the repository root |
+| `format-folder` | No | `""` | Directory containing the `package.json` whose format script should be run after downloading translations. Leave empty to skip formatting. |
+| `format-script` | No | `format` | pnpm script name to run for formatting (e.g. `format`, `format:fix`) |
+| `jfrog-token` | No | `""` | JFrog npm auth token (required when `format-folder` is set) |
+| `forgejo-token` | Yes | — | Forgejo token with `contents:write` and `pull-requests:write` access |
+| `destination-branch` | No | `dev` | Target branch for the pull request |
+
+## Usage
+
+Minimal — no formatting:
+
+```yaml
+- uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/i18n-sync@i18n-sync-v1
+  with:
+    i18n-application: my-app
+    forgejo-token: ${{ secrets.FORGEJO_I18N_UPDATE_TOKEN }}
+```
+
+With formatting after download:
+
+```yaml
+- uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/i18n-sync@i18n-sync-v1
+  with:
+    i18n-application: my-app
+    locales-folder: frontend/locales
+    format-folder: frontend
+    jfrog-token: ${{ secrets.JFROG_TOKEN }}
+    forgejo-token: ${{ secrets.FORGEJO_I18N_UPDATE_TOKEN }}
+```
+
+## Notes
+
+- The action fails fast if the `chore/i18n` branch already exists, indicating a previous update is still pending review.
+- If no translation changes are detected after downloading, the action exits cleanly without creating a branch or PR.
+- Deleted languages (files removed from i18n.schmalz.com) are also staged for removal via `git add --all`.
+- `jq` is installed automatically if not present on the runner.
+- The `forgejo-token` must belong to a user or bot with `contents:write` and `pull-requests:write` permissions on the repository.

i18n-sync/action.yml

@@ -0,0 +1,131 @@
+name: i18n Sync
+description: >
+  Fetches the latest translations from i18n.schmalz.com, commits them to a
+  chore/i18n branch, and opens a pull request against the destination branch.
+
+inputs:
+  i18n-application:
+    description: Application key in i18n.schmalz.com (e.g. "calculator")
+    required: true
+  locales-folder:
+    description: Path to the locales directory relative to the repository root
+    required: false
+    default: locales
+  format-folder:
+    description: >
+      Directory containing the package.json whose format script should be run
+      after downloading translations. Leave empty to skip formatting.
+    required: false
+    default: ""
+  format-script:
+    description: pnpm script name to run for formatting (e.g. "format", "format:fix")
+    required: false
+    default: format
+  jfrog-token:
+    description: JFrog npm auth token (required when format-folder is set)
+    required: false
+    default: ""
+  forgejo-token:
+    description: Forgejo token with contents:write and pull-requests:write access
+    required: true
+  destination-branch:
+    description: Target branch for the pull request
+    required: false
+    default: dev
+
+runs:
+  using: composite
+  steps:
+    - 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: Configure git
+      shell: bash
+      env:
+        FORGEJO_TOKEN: ${{ inputs.forgejo-token }}
+      run: |
+        set -euo pipefail
+        git config user.name "github-actions[bot]"
+        git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+        ORIGIN_URL=$(git remote get-url origin)
+        CLEAN_URL=$(echo "$ORIGIN_URL" | sed 's|https://[^@]*@|https://|')
+        git remote set-url origin "$(echo "$CLEAN_URL" | sed "s|https://|https://github-actions[bot]:${FORGEJO_TOKEN}@|")"
+
+    - name: Check if i18n branch already exists
+      shell: bash
+      run: |
+        set -euo pipefail
+        if git ls-remote --exit-code --heads origin "refs/heads/chore/i18n" >/dev/null 2>&1; then
+          echo "Branch chore/i18n already exists. A previous i18n update is still pending."
+          exit 1
+        fi
+
+    - name: Download translations
+      shell: bash
+      env:
+        I18N_APPLICATION: ${{ inputs.i18n-application }}
+        LOCALES_FOLDER: ${{ inputs.locales-folder }}
+      run: |
+        set -euo pipefail
+        git checkout -b chore/i18n
+
+        echo "Fetching available languages for application: $I18N_APPLICATION"
+        languages_json=$(curl --fail-with-body -sSL "https://i18n.schmalz.com/api/languages?projectKey=$I18N_APPLICATION")
+
+        echo "$languages_json" | jq -r '.[]' | while read -r lang; do
+          echo "Downloading language: $lang"
+          curl --fail-with-body -sSL -o "${LOCALES_FOLDER}/${lang}.json" \
+            "https://i18n.schmalz.com/api/${I18N_APPLICATION}/${lang}.json"
+        done
+
+    - name: Format translations
+      if: ${{ inputs.format-folder != '' }}
+      uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/pnpm-build@pnpm-build-v1
+      with:
+        working-directory: ${{ inputs.format-folder }}
+        jfrog-token: ${{ inputs.jfrog-token }}
+        run-scripts: ${{ inputs.format-script }}
+        check-dedupe: "false"
+
+    - name: Commit and push translations
+      id: commit
+      shell: bash
+      env:
+        LOCALES_FOLDER: ${{ inputs.locales-folder }}
+      run: |
+        set -euo pipefail
+        git add --all "${LOCALES_FOLDER}/"
+
+        if git diff-index --cached --quiet HEAD; then
+          echo "No translation changes detected. Nothing to do."
+          echo "has_changes=false" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+
+        git commit -m "chore: update translations via i18n"
+        git push origin chore/i18n
+        echo "has_changes=true" >> "$GITHUB_OUTPUT"
+
+    - name: Create pull request
+      if: ${{ steps.commit.outputs.has_changes == 'true' }}
+      shell: bash
+      env:
+        TOKEN: ${{ inputs.forgejo-token }}
+        DESTINATION_BRANCH: ${{ inputs.destination-branch }}
+      run: |
+        set -euo pipefail
+        curl --fail-with-body -s -X POST \
+          -H "Authorization: token ${TOKEN}" \
+          -H "Content-Type: application/json" \
+          "${GITHUB_SERVER_URL}/api/v1/repos/${GITHUB_REPOSITORY}/pulls" \
+          -d "$(jq -n \
+            --arg title "chore: update translations via i18n" \
+            --arg head "chore/i18n" \
+            --arg base "$DESTINATION_BRANCH" \
+            --arg body "Automated translation update from i18n.schmalz.com" \
+            '{title: $title, head: $head, base: $base, body: $body, delete_branch_after_merge: true}'
+          )"

maven-build/action.yml

@@ -94,9 +94,11 @@ 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 \
+          -P "$MAVEN_PROFILE" \
           $EXTRA_ARGS
 
     - name: Deploy

playwright-merge/README.md

@@ -0,0 +1,39 @@
+# playwright-merge
+
+Download all Playwright blob reports from shard jobs, merge them into a single HTML + JUnit report, and optionally upload the HTML report to S3.
+
+## Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `working-directory` | No | `.` | Directory containing `package.json` and `playwright.config.ts` |
+| `node-version` | No | `24` | Node.js version |
+| `pnpm-version` | No | `10.33` | pnpm version |
+| `jfrog-token` | No | `""` | JFrog npm auth token |
+| `role-arn` | Yes | — | IAM role ARN for AWS authentication |
+| `aws-access-key-id` | Yes | — | AWS access key ID |
+| `aws-secret-access-key` | Yes | — | AWS secret access key |
+| `project-name` | Yes | — | Project name used as the folder in the report bucket (e.g. `hs-pricelist`) |
+| `publish-test-reports` | No | `true` | Whether to upload the report to S3 and print the URL at `https://test-reports.schmalz.com` |
+
+## Usage
+
+```yaml
+- uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/playwright-merge@playwright-merge-v1
+  with:
+    working-directory: frontend
+    node-version: 22
+    jfrog-token: ${{ secrets.JFROG_TOKEN }}
+    role-arn: arn:aws:iam::953815822701:role/deployment-role
+    aws-access-key-id: ${{ secrets.DB_STAGE_DEPLOYMENT_ACCESS_KEY }}
+    aws-secret-access-key: ${{ secrets.DB_STAGE_DEPLOYMENT_SECRET_ACCESS_KEY }}
+    project-name: hs-pricelist
+```
+
+## Notes
+
+- Intended as a follow-up job after all `playwright-run` shard jobs complete.
+- Downloads shard artifacts into `all-blob-reports/` and merges them with `playwright merge-reports`.
+- Generates HTML report in `playwright-report/` and JUnit XML in `test-results/junit.xml`.
+- Uploads report files to `s3://com.schmalz.db.stage.test-reports/reports/<project-name>/<timestamp>/` when `publish-test-reports` is `true`.
+- Prints the final report URL on `https://test-reports.schmalz.com`.

playwright-merge/action.yml

@@ -0,0 +1,104 @@
+name: Playwright Merge
+description: >
+  Download all blob reports from shard jobs, merge them into a single HTML + JUnit
+  report, upload the HTML report to S3, and upload the JUnit report as an artifact.
+  Call this in a follow-up job after all playwright-run shard jobs complete.
+
+inputs:
+  working-directory:
+    description: Directory containing package.json and playwright.config.ts
+    required: false
+    default: "."
+  node-version:
+    description: Node.js version
+    required: false
+    default: "24"
+  pnpm-version:
+    description: pnpm version
+    required: false
+    default: "10.33"
+  jfrog-token:
+    description: JFrog npm auth token
+    required: false
+    default: ""
+  role-arn:
+    description: IAM role ARN for AWS authentication
+    required: true
+  aws-access-key-id:
+    description: AWS access key ID
+    required: true
+  aws-secret-access-key:
+    description: AWS secret access key
+    required: true
+  project-name:
+    description: Project name used as the folder in the report bucket (e.g. hs-pricelist)
+    required: true
+  publish-test-reports:
+    description: Whether to upload the report to S3 and print the URL at https://test-reports.schmalz.com. Set to false to skip upload entirely.
+    required: false
+    default: "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: Configure AWS
+      uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/aws-configure@aws-configure-v1
+      with:
+        role-arn: ${{ inputs.role-arn }}
+        aws-access-key-id: ${{ inputs.aws-access-key-id }}
+        aws-secret-access-key: ${{ inputs.aws-secret-access-key }}
+
+    - name: Install dependencies
+      uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/pnpm-build@pnpm-build-v1
+      with:
+        working-directory: ${{ inputs.working-directory }}
+        node-version: ${{ inputs.node-version }}
+        pnpm-version: ${{ inputs.pnpm-version }}
+        jfrog-token: ${{ inputs.jfrog-token }}
+        run-scripts: ""
+        frozen-lockfile: "true"
+        check-dedupe: "false"
+
+    - name: Download blob reports
+      uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/download-artifact@download-artifact-v1
+      with:
+        path: ${{ inputs.working-directory }}/all-blob-reports/
+        merge-multiple: "true"
+
+    - name: Merge blob reports
+      shell: bash
+      env:
+        CI: "true"
+        WORKING_DIR: ${{ inputs.working-directory }}
+        PLAYWRIGHT_JUNIT_OUTPUT_NAME: test-results/junit.xml
+      run: |
+        cd "${WORKING_DIR}"
+        pnpm exec playwright merge-reports \
+          --reporter=html,junit \
+          all-blob-reports/
+
+    - name: Upload report to S3
+      if: ${{ inputs.publish-test-reports == 'true' }}
+      shell: bash
+      env:
+        WORKING_DIR: ${{ inputs.working-directory }}
+        PROJECT_NAME: ${{ inputs.project-name }}
+      run: |
+        TIMESTAMP=$(date +%s)
+        S3_BUCKET=com.schmalz.db.stage.test-reports
+        S3_PATH="s3://${S3_BUCKET}/reports/${PROJECT_NAME}/${TIMESTAMP}"
+        aws s3 sync "${WORKING_DIR}/playwright-report/" "${S3_PATH}/"
+        if [ -f "${WORKING_DIR}/test-results/junit.xml" ]; then
+          aws s3 cp "${WORKING_DIR}/test-results/junit.xml" "${S3_PATH}/junit.xml"
+        fi
+        echo "Report URL: https://test-reports.schmalz.com/reports/${PROJECT_NAME}/${TIMESTAMP}/index.html"

playwright-run/README.md

@@ -0,0 +1,62 @@
+# playwright-run
+
+Run Playwright E2E tests for one shard and upload the blob report as an artifact.
+
+## Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `working-directory` | No | `.` | Directory containing `package.json` and `playwright.config.ts` |
+| `node-version` | No | `24` | Node.js version |
+| `pnpm-version` | No | `10.33` | pnpm version |
+| `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: ${{ matrix.total }}
+          no-deps: "true"
+          projects: "chromium,firefox,webkit,Mobile Chrome,Mobile Safari"
+```
+
+## Notes
+
+- Intended for matrix shard jobs.
+- Uploads one artifact per shard named `blob-report-<shard-index>`.
+- Use `playwright-merge` in a follow-up job to merge shard reports.

playwright-run/action.yml

@@ -0,0 +1,108 @@
+name: Playwright Run
+description: >
+  Run Playwright E2E tests for one shard and upload the blob report as an artifact.
+  Call this from a matrix job. Use the playwright-merge action in a follow-up job
+  to produce the final HTML + JUnit report.
+
+inputs:
+  working-directory:
+    description: Directory containing package.json and playwright.config.ts
+    required: false
+    default: "."
+  node-version:
+    description: Node.js version
+    required: false
+    default: "24"
+  pnpm-version:
+    description: pnpm version
+    required: false
+    default: "10.33"
+  jfrog-token:
+    description: JFrog npm auth token
+    required: false
+    default: ""
+  shard-index:
+    description: Current shard index (1-based). Set to 1 when not sharding.
+    required: false
+    default: "1"
+  shard-total:
+    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
+    default: "3"
+
+runs:
+  using: composite
+  steps:
+    - name: Install dependencies
+      uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/pnpm-build@pnpm-build-v1
+      with:
+        working-directory: ${{ inputs.working-directory }}
+        node-version: ${{ inputs.node-version }}
+        pnpm-version: ${{ inputs.pnpm-version }}
+        jfrog-token: ${{ inputs.jfrog-token }}
+        run-scripts: ""
+        frozen-lockfile: "true"
+        check-dedupe: "false"
+
+    - name: Cache Playwright browsers
+      id: playwright-cache
+      uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/cache@cache-v1
+      with:
+        path: ~/.cache/ms-playwright
+        key: ${{ runner.os }}-playwright-${{ hashFiles('**/pnpm-lock.yaml') }}
+        restore-keys: ${{ runner.os }}-playwright-
+
+    - name: Install Playwright browsers
+      if: ${{ steps.playwright-cache.outputs.cache-hit != 'true' }}
+      shell: bash
+      env:
+        WORKING_DIR: ${{ inputs.working-directory }}
+      run: pnpm --prefix="${WORKING_DIR}" exec playwright install --with-deps
+
+    - name: Run Playwright tests
+      shell: bash
+      env:
+        CI: "true"
+        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
+        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() }}
+      uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/upload-artifact@upload-artifact-v1
+      with:
+        name: blob-report-${{ inputs.shard-index }}
+        path: ${{ inputs.working-directory }}/blob-report/
+        retention-days: ${{ inputs.artifact-retention-days }}
+        if-no-files-found: ignore

publish-npm-package/README.md

@@ -0,0 +1,28 @@
+# publish-npm-package
+
+Publish a PNPM package to JFrog Artifactory.
+
+## Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `working-directory` | No | `.` | Directory containing `package.json` |
+| `node-version` | No | `24` | Node.js version |
+| `pnpm-version` | No | `10.33` | pnpm version |
+| `jfrog-token` | Yes | — | JFrog npm auth token |
+| `registry-url` | No | `https://schmalz.jfrog.io/artifactory/api/npm/default-npm/` | npm registry URL |
+
+## Usage
+
+```yaml
+- uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/publish-npm-package@publish-npm-package-v1
+  with:
+    working-directory: .
+    jfrog-token: ${{ secrets.JFROG_TOKEN }}
+```
+
+## Notes
+
+- Publishes with `pnpm publish`.
+- Configures the registry auth token from `registry-url` and `jfrog-token`.
+- Third-party actions used internally are pinned to exact commit SHAs to prevent supply chain attacks.

publish-npm-package/action.yml

@@ -0,0 +1,64 @@
+name: publish-npm-package
+description: Publish a PNPM package to JFrog Artifactory.
+
+inputs:
+  working-directory:
+    description: Directory containing package.json
+    required: false
+    default: "."
+  node-version:
+    description: Node.js version
+    required: false
+    default: "24"
+  pnpm-version:
+    description: pnpm version
+    required: false
+    default: "10.33"
+  jfrog-token:
+    description: JFrog npm auth token
+    required: true
+  registry-url:
+    description: npm registry URL
+    required: false
+    default: "https://schmalz.jfrog.io/artifactory/api/npm/default-npm/"
+
+runs:
+  using: composite
+  steps:
+    # Pinned to commit SHA instead of a tag to prevent supply chain attacks.
+    # actions/setup-node v4.4.0 — https://code.forgejo.org/actions/setup-node/commits/tag/v4.4.0
+    - name: Setup Node
+      uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+      with:
+        node-version: ${{ inputs.node-version }}
+
+    # Pinned to commit SHA instead of a tag to prevent supply chain attacks.
+    # pnpm/action-setup v4.3.0 — https://code.forgejo.org/pnpm/action-setup/commits/tag/v4.3.0
+    - name: Install pnpm
+      uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1
+      env:
+        # pnpm/action-setup bootstraps itself via npm before pnpm is available,
+        # so it must reach the public npm registry.
+        NPM_CONFIG_REGISTRY: https://registry.npmjs.org
+      with:
+        version: ${{ inputs.pnpm-version }}
+
+    - name: Configure JFrog registry authentication
+      shell: bash
+      env:
+        JFROG_TOKEN: ${{ inputs.jfrog-token }}
+        REGISTRY_URL: ${{ inputs.registry-url }}
+      run: |
+        set -euo pipefail
+
+        pnpm set registry "${REGISTRY_URL}"
+
+        AUTHORITY="${REGISTRY_URL#https://}"
+        AUTHORITY="${AUTHORITY#http://}"
+        AUTHORITY="${AUTHORITY%/}"
+        pnpm set "//${AUTHORITY}/:_authToken" "${JFROG_TOKEN}"
+
+    - name: Publish
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      run: pnpm publish

publish-rust-crate/README.md

@@ -0,0 +1,29 @@
+# publish-rust-crate
+
+Publish a Rust crate to JFrog Artifactory.
+
+## Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `working-directory` | No | `.` | Directory containing `Cargo.toml` |
+| `rust-version` | No | `1.95.0` | Rust toolchain version |
+| `jfrog-token` | Yes | — | JFrog token for the Artifactory Cargo registry |
+| `registry-name` | No | `artifactory` | Cargo registry name |
+| `registry-index` | No | `sparse+https://schmalz.jfrog.io/artifactory/api/cargo/schmalz-cargo-local/index/` | Cargo registry index URL |
+
+## Usage
+
+```yaml
+- uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/publish-rust-crate@publish-rust-crate-v1
+  with:
+    working-directory: .
+    jfrog-token: ${{ secrets.JFROG_TOKEN }}
+```
+
+## Notes
+
+- Configures Cargo registry settings in `${CARGO_HOME}/config.toml` and `${CARGO_HOME}/credentials.toml`.
+- Falls back to `$HOME/.cargo` when `CARGO_HOME` is not set.
+- Publishes with `cargo publish --registry <registry-name>`.
+- Third-party actions used internally are pinned to exact commit SHAs to prevent supply chain attacks.

publish-rust-crate/action.yml

@@ -0,0 +1,64 @@
+name: publish-rust-crate
+description: Publish a Rust crate to JFrog Artifactory.
+
+inputs:
+  working-directory:
+    description: Directory containing Cargo.toml
+    required: false
+    default: "."
+  rust-version:
+    description: Rust toolchain version
+    required: false
+    default: "1.95.0"
+  jfrog-token:
+    description: JFrog token for the Artifactory Cargo registry
+    required: true
+  registry-name:
+    description: Cargo registry name
+    required: false
+    default: artifactory
+  registry-index:
+    description: Cargo registry index URL
+    required: false
+    default: "sparse+https://schmalz.jfrog.io/artifactory/api/cargo/schmalz-cargo-local/index/"
+
+runs:
+  using: composite
+  steps:
+    # Pinned to commit SHA instead of a tag to prevent supply chain attacks.
+    # dtolnay/rust-toolchain v1 (2026-03-27) — https://github.com/dtolnay/rust-toolchain/commit/3c5f7ea28cd621ae0bf5283f0e981fb97b8a7af9
+    - name: Setup Rust toolchain
+      uses: dtolnay/rust-toolchain@3c5f7ea28cd621ae0bf5283f0e981fb97b8a7af9
+      with:
+        toolchain: ${{ inputs.rust-version }}
+
+    - name: Configure Cargo registry (JFrog Artifactory)
+      shell: bash
+      env:
+        JFROG_TOKEN: ${{ inputs.jfrog-token }}
+        REGISTRY_NAME: ${{ inputs.registry-name }}
+        REGISTRY_INDEX: ${{ inputs.registry-index }}
+      run: |
+        set -euo pipefail
+
+        CARGO_HOME_DIR="${CARGO_HOME:-$HOME/.cargo}"
+        mkdir -p "${CARGO_HOME_DIR}"
+
+        cat >> "${CARGO_HOME_DIR}/config.toml" <<EOF
+        [registries.${REGISTRY_NAME}]
+        index = "${REGISTRY_INDEX}"
+        [registry]
+        global-credential-providers = ["cargo:token"]
+        EOF
+
+        cat >> "${CARGO_HOME_DIR}/credentials.toml" <<EOF
+        [registries.${REGISTRY_NAME}]
+        token = "Bearer ${JFROG_TOKEN}"
+        EOF
+
+    - name: Publish
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      env:
+        REGISTRY_NAME: ${{ inputs.registry-name }}
+      run: cargo publish --registry "${REGISTRY_NAME}"

publish-static-contents/action.yml

@@ -97,12 +97,12 @@ runs:
         fi
 
         # Bulk sync remaining files; versioned builds get immutable cache headers
-        CACHE_CONTROL_ARG=""
+        CACHE_CONTROL_ARG=()
         if [[ "${INPUT_VERSIONING}" == "true" ]]; then
-          CACHE_CONTROL_ARG="--cache-control 'public, max-age=31536000, immutable'"
+          CACHE_CONTROL_ARG=("--cache-control" "public, max-age=31536000, immutable")
         fi
 
-        aws s3 sync "${INPUT_DIST_DIR}" "s3://${INPUT_S3_BUCKET_NAME}" $CACHE_CONTROL_ARG "${EXCLUDE_ARGS[@]}"
+        aws s3 sync "${INPUT_DIST_DIR}" "s3://${INPUT_S3_BUCKET_NAME}" "${CACHE_CONTROL_ARG[@]}" "${EXCLUDE_ARGS[@]}"
 
     - name: Clean up old versioned static builds
       if: ${{ inputs.versioning == 'true' }}

rust-build/README.md

@@ -0,0 +1,42 @@
+# rust-build
+
+Set up Rust toolchain, configure Cargo registry, cache dependencies, run optional checks, and build via the project's `build.sh` script.
+
+## Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `working-directory` | No | `.` | Directory containing `Cargo.toml` and `build.sh` |
+| `rust-version` | No | `1.95.0` | Rust toolchain version |
+| `cross-target` | No | `x86_64-unknown-linux-musl` | Cross-compilation target triple |
+| `build-mode` | No | `release` | Build mode — `release` or `debug` |
+| `run-checks` | No | `""` | Comma-separated checks to run before building — `fmt`, `clippy`, `test` |
+| `jfrog-token` | No | `""` | JFrog token for the Artifactory Cargo registry |
+
+## Usage
+
+### PR check (checks + debug build)
+
+```yaml
+- uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/rust-build@rust-build-v1
+  with:
+    working-directory: backend-rs
+    build-mode: debug
+    run-checks: fmt,clippy,test
+    jfrog-token: ${{ secrets.JFROG_TOKEN }}
+```
+
+### Release build
+
+```yaml
+- uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/rust-build@rust-build-v1
+  with:
+    working-directory: backend-rs
+    jfrog-token: ${{ secrets.JFROG_TOKEN }}
+```
+
+## Notes
+
+- Requires a `build.sh` in `working-directory` that accepts `--target <triple>` and optionally `--release`. The script is responsible for running `cargo build` and copying binaries to `target/deploy/`.
+- Configures the Artifactory Cargo registry only if `jfrog-token` is provided.
+- Third-party actions used internally are pinned to exact commit SHAs to prevent supply chain attacks.

rust-build/action.yml

@@ -0,0 +1,112 @@
+name: rust-build
+description: >
+  Set up Rust toolchain, configure Cargo registry, cache dependencies,
+  run optional checks, and build via the project's build.sh script.
+
+inputs:
+  working-directory:
+    description: Directory containing Cargo.toml and build.sh
+    required: false
+    default: "."
+  rust-version:
+    description: Rust toolchain version (passed to dtolnay/rust-toolchain)
+    required: false
+    default: "1.95.0"
+  cross-target:
+    description: Cross-compilation target triple
+    required: false
+    default: x86_64-unknown-linux-musl
+  build-mode:
+    description: Build mode — 'release' or 'debug'
+    required: false
+    default: release
+  run-checks:
+    description: Comma-separated checks to run before building — 'fmt', 'clippy', 'test'
+    required: false
+    default: ""
+  jfrog-token:
+    description: JFrog token for the Artifactory Cargo registry
+    required: false
+    default: ""
+
+runs:
+  using: composite
+  steps:
+    - name: Install musl tools
+      shell: bash
+      run: |
+        if ! command -v musl-gcc &>/dev/null; then
+          sudo apt-get update -qq && sudo apt-get install -y -qq musl-tools
+        fi
+
+    # Pinned to commit SHA instead of a tag to prevent supply chain attacks.
+    # dtolnay/rust-toolchain v1 (2026-03-27) — https://github.com/dtolnay/rust-toolchain/commit/3c5f7ea28cd621ae0bf5283f0e981fb97b8a7af9
+    - name: Setup Rust toolchain
+      id: rust-toolchain
+      uses: dtolnay/rust-toolchain@3c5f7ea28cd621ae0bf5283f0e981fb97b8a7af9
+      with:
+        toolchain: ${{ inputs.rust-version }}
+        targets: ${{ inputs.cross-target }}
+        components: rustfmt,clippy
+
+    - name: Configure Cargo registry (JFrog Artifactory)
+      if: ${{ inputs.jfrog-token != '' }}
+      shell: bash
+      env:
+        JFROG_TOKEN: ${{ inputs.jfrog-token }}
+      run: |
+        mkdir -p "${CARGO_HOME}"
+        cat >> "${CARGO_HOME}/config.toml" <<'EOF'
+        [registries.artifactory]
+        index = "sparse+https://schmalz.jfrog.io/artifactory/api/cargo/schmalz-cargo-local/index/"
+        [registry]
+        global-credential-providers = ["cargo:token"]
+        EOF
+
+        cat >> "${CARGO_HOME}/credentials.toml" <<EOF
+        [registries.artifactory]
+        token = "Bearer ${JFROG_TOKEN}"
+        EOF
+
+    - name: Cache cargo registry
+      uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/cache@cache-v1
+      with:
+        path: |
+          ~/.cargo/registry/index
+          ~/.cargo/registry/cache
+          ~/.cargo/git/db
+        key: ${{ runner.os }}-cargo-${{ steps.rust-toolchain.outputs.cachekey }}-${{ inputs.cross-target }}-${{ hashFiles(format('{0}/Cargo.lock', inputs.working-directory)) }}
+        restore-keys: |
+          ${{ runner.os }}-cargo-${{ steps.rust-toolchain.outputs.cachekey }}-${{ inputs.cross-target }}-
+          ${{ runner.os }}-cargo-${{ steps.rust-toolchain.outputs.cachekey }}-
+
+    - name: Run checks
+      if: ${{ inputs.run-checks != '' }}
+      shell: bash
+      env:
+        WORKING_DIR: ${{ inputs.working-directory }}
+        CROSS_TARGET: ${{ inputs.cross-target }}
+        RUN_CHECKS: ${{ inputs.run-checks }}
+      run: |
+        IFS=',' read -ra CHECKS <<< "${RUN_CHECKS}"
+        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}" ;;
+            test)   cargo test --manifest-path="${WORKING_DIR}/Cargo.toml" ;;
+            *)      echo "Unknown check: ${check}"; exit 1 ;;
+          esac
+        done
+
+    - name: Build
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      env:
+        CROSS_TARGET: ${{ inputs.cross-target }}
+        BUILD_MODE: ${{ inputs.build-mode }}
+      run: |
+        BUILD_ARGS="--target ${CROSS_TARGET}"
+        if [ "${BUILD_MODE}" = "release" ]; then
+          BUILD_ARGS="${BUILD_ARGS} --release"
+        fi
+        ./build.sh ${BUILD_ARGS}

terraform-apply/action.yml

@@ -61,7 +61,7 @@ runs:
         TF_DIR: ${{ inputs.terraform-dir }}
         TF_WORKSPACE_NAME: ${{ inputs.workspace }}
       run: |
-        terraform -chdir="$TF_DIR" workspace select "$TF_WORKSPACE_NAME"
+        terraform -chdir="$TF_DIR" workspace select -or-create "$TF_WORKSPACE_NAME"
 
     - name: Terraform Apply
       shell: bash

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

upload-artifact/README.md

@@ -0,0 +1,37 @@
+# upload-artifact
+
+Upload files as a Forgejo Actions artifact. Thin wrapper around `forgejo/upload-artifact` pinned to a specific commit SHA to prevent supply chain attacks.
+
+## Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `name` | Yes | — | Artifact name |
+| `path` | Yes | — | File or directory path to upload |
+| `retention-days` | No | `30` | Number of days to retain the artifact |
+| `if-no-files-found` | No | `warn` | Behaviour when no files are found — `warn`, `error`, or `ignore` |
+
+## Usage
+
+```yaml
+- uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/upload-artifact@upload-artifact-v1
+  with:
+    name: my-artifact
+    path: dist/
+```
+
+Upload and ignore if no files exist:
+
+```yaml
+- uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/upload-artifact@upload-artifact-v1
+  with:
+    name: blob-report-${{ matrix.shard-index }}
+    path: frontend/blob-report/
+    retention-days: 3
+    if-no-files-found: ignore
+```
+
+## Notes
+
+- Wraps `forgejo/upload-artifact` v4 (node20), compatible with Ubuntu 22 runners.
+- The underlying action is pinned to a commit SHA rather than a mutable tag to prevent supply chain attacks.

upload-artifact/action.yml

@@ -0,0 +1,33 @@
+name: Schmalz Upload Artifact
+description: >
+  Upload files as a Forgejo Actions artifact.
+  Thin wrapper around forgejo/upload-artifact, pinned to a specific SHA.
+
+inputs:
+  name:
+    description: Artifact name
+    required: true
+  path:
+    description: File or directory path to upload
+    required: true
+  retention-days:
+    description: Number of days to retain the artifact
+    required: false
+    default: "30"
+  if-no-files-found:
+    description: Behaviour when no files are found — 'warn', 'error', or 'ignore'
+    required: false
+    default: warn
+
+runs:
+  using: composite
+  steps:
+    # Pinned to commit SHA instead of a tag to prevent supply chain attacks.
+    # forgejo/upload-artifact v4 — https://code.forgejo.org/forgejo/upload-artifact/commits/tag/v4
+    - name: Upload artifact
+      uses: https://code.forgejo.org/forgejo/upload-artifact@16871d9e8cfcf27ff31822cac382bbb5450f1e1e
+      with:
+        name: ${{ inputs.name }}
+        path: ${{ inputs.path }}
+        retention-days: ${{ inputs.retention-days }}
+        if-no-files-found: ${{ inputs.if-no-files-found }}

vacuum-lint/README.md

@@ -0,0 +1,25 @@
+# vacuum-lint
+
+Action for validating and linting OpenAPI specifications using [Vacuum](https://github.com/daveshanley/vacuum).
+
+## Inputs
+
+| Input | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `spec-dir` | No | `spec` | Directory containing the OpenAPI spec |
+| `spec-filename` | No | `openapi.json` | Filename of the OpenAPI spec |
+| `rules-filename` | No | `vacuum.rules.yaml` | Filename of the lint rules config file |
+| `ignore-filename` | No | `vacuum.ignore.yaml` | Filename of the lint ignore file |
+| `min-score` | No | `70` | Minimum linting score for the check to pass |
+
+## Usage
+
+```yaml
+- uses: https://schmalz-git.git.onstackit.cloud/schmalz/shared-actions/vacuum-lint@vacuum-lint-v1
+```
+
+## Notes
+
+- If `rules-filename` is found inside `spec-dir`, it is passed to Vacuum via `-r` to apply custom rulesets; otherwise Vacuum uses its default rules.
+- If `ignore-filename` is found inside `spec-dir`, it is passed to Vacuum via `--ignore-file` to suppress known violations.
+- The action fails when the computed linting score falls below `min-score`.

vacuum-lint/action.yml

@@ -0,0 +1,65 @@
+name: Vacuum Lint
+description: >
+  Validate and lint OpenAPI specifications using Vacuum.
+
+inputs:
+  spec-dir:
+    description: Directory containing OpenAPI spec
+    required: false
+    default: "spec"
+  spec-filename:
+    description: Filename of the OpenAPI spec 
+    required: false
+    default: "openapi.json"
+  rules-filename:
+    description: Filename of the lint rules config file
+    required: false
+    default: "vacuum.rules.yaml"
+  ignore-filename:
+    description: Filename of the lint ignore file
+    required: false
+    default: "vacuum.ignore.yaml"
+  min-score:
+    description: Minimum linting score for the check to pass
+    required: false
+    default: "70"
+
+runs:
+  using: composite
+  steps:
+      # Pinned to commit SHA instead of a tag to prevent supply chain attacks.
+      - name: Install Vacuum
+        shell: bash
+        run: curl -fsSL https://raw.githubusercontent.com/daveshanley/vacuum/8222bba0c8b21a3a94faf472e06c4db06f06c6ce/bin/install.sh | sudo sh > /dev/null 2>&1
+
+      - name: Lint Spec
+        shell: bash
+        env:
+          SPEC_DIR: ${{ inputs.spec-dir }}
+          SPEC_FILE: ${{ inputs.spec-filename }}
+          RULES_FILE: ${{ inputs.rules-filename }}
+          IGNORE_FILE: ${{ inputs.ignore-filename }}
+          MIN_SCORE: ${{ inputs.min-score }}
+        run: |
+          echo "Linting: [$SPEC_DIR/$SPEC_FILE]"
+
+          # base command
+          CMD="vacuum lint $SPEC_DIR/$SPEC_FILE -x --min-score $MIN_SCORE"
+
+          # check for rules file
+          if [ -f "$SPEC_DIR/$RULES_FILE" ]; then
+              CMD="$CMD -r $SPEC_DIR/$RULES_FILE"
+              echo "  - using ruleset [$SPEC_DIR/$RULES_FILE]"
+          fi
+
+          # check for ignore file
+          if [ -f "$SPEC_DIR/$IGNORE_FILE" ]; then
+              CMD="$CMD --ignore-file $SPEC_DIR/$IGNORE_FILE"
+              echo "  - using ignore file [$SPEC_DIR/$IGNORE_FILE]"
+          fi
+
+          # execute command
+          $CMD
+    
+          echo "Linted: [$SPEC_DIR/$SPEC_FILE]"
+          echo ""