docs: sync KevinDeBenedetti/github-workflows@main

Author: github-actions[bot]

github-workflows/actions/actionlint.md

@@ -0,0 +1,33 @@
+# Action — actionlint
+
+Validates GitHub Actions workflow files with [actionlint](https://github.com/rhysd/actionlint).
+
+## Usage
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+
+  - uses: KevinDeBenedetti/github-workflows/.github/actions/actionlint@main
+    with:
+      paths: .github/workflows/
+```
+
+## Inputs
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `paths` | string | `.github/workflows/` | Space-separated list of workflow files or directories to validate |
+| `flags` | string | `''` | Extra flags passed to actionlint (e.g. `-ignore 'SC2086'`) |
+
+## Steps
+
+1. Download and install `actionlint` `1.7.11` into `$RUNNER_TEMP/actionlint`
+2. Collect all `.yml` / `.yaml` files from the given paths
+3. Run `actionlint [flags] <files>`
+
+## Notes
+
+- When `paths` points to a directory, all `.yml` and `.yaml` files within it are collected recursively.
+- Use `flags: '-ignore SC2086'` to suppress specific ShellCheck rules that actionlint embeds.
+- actionlint is downloaded fresh each run; no system-wide install is required.

github-workflows/actions/bats.md

@@ -0,0 +1,34 @@
+# Action — bats
+
+Installs [Bats](https://github.com/bats-core/bats-core) (Bash Automated Testing System) and
+runs shell unit tests.
+
+## Usage
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+    with:
+      submodules: true  # required if using bats helpers (bats-support, bats-assert, etc.)
+
+  - uses: KevinDeBenedetti/github-workflows/.github/actions/bats@main
+    with:
+      tests-dir: tests/
+```
+
+## Inputs
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `tests-dir` | string | `tests/` | Directory (or file) containing `.bats` test files |
+
+## Steps
+
+1. Install Bats `1.11.0` globally via npm
+2. Run `bats <tests-dir>`
+
+## Notes
+
+- Pass a specific `.bats` file path to `tests-dir` to run a single test file.
+- Bats helper libraries (`bats-support`, `bats-assert`, `bats-file`) are typically added as git
+  submodules — check out with `submodules: true` in your checkout step.

github-workflows/actions/detect-changes.md

@@ -0,0 +1,67 @@
+# Action — detect-changes
+
+Detects which subdirectories under `apps/` (or a custom directory) have changed since the
+last commit, and outputs a JSON matrix for use in downstream matrix jobs.
+
+## Usage
+
+```yaml
+jobs:
+  detect:
+    runs-on: ubuntu-latest
+    outputs:
+      changed-apps: ${{ steps.changes.outputs.changed-apps }}
+      has-changes:  ${{ steps.changes.outputs.has-changes }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: KevinDeBenedetti/github-workflows/.github/actions/detect-changes@main
+        id: changes
+        with:
+          apps-directory: apps
+
+  build:
+    needs: detect
+    if: needs.detect.outputs.has-changes == 'true'
+    strategy:
+      matrix:
+        app: ${{ fromJson(needs.detect.outputs.changed-apps) }}
+    runs-on: ubuntu-latest
+    steps:
+      - run: echo "Building ${{ matrix.app }}"
+```
+
+## Inputs
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `apps-directory` | string | `apps` | Root directory containing app subdirectories |
+| `base-ref` | string | `''` | Base git ref to compare against (auto-detected if empty) |
+
+## Outputs
+
+| Output | Description |
+|---|---|
+| `changed-apps` | JSON array of changed app names, e.g. `["api","web"]` |
+| `has-changes` | `"true"` or `"false"` — whether any app changed |
+| `changed-api` | `"true"` or `"false"` — whether `apps/api` changed |
+| `changed-web` | `"true"` or `"false"` — whether `apps/web` changed |
+| `changed-client` | `"true"` or `"false"` — whether `apps/client` changed |
+
+## Base ref resolution
+
+1. Uses `base-ref` input if provided
+2. Falls back to `github.event.pull_request.base.sha` on pull requests
+3. Falls back to `github.event.before` on push events
+4. Falls back to `HEAD~1` if the before SHA is empty or all zeros (e.g. first push to branch)
+
+## Notes
+
+- Requires `fetch-depth: 0` (or at least enough history to compare against the base ref) in your
+  checkout step.
+- Per-app boolean outputs (`changed-api`, `changed-web`, `changed-client`) are useful for
+  `if:` conditions when you don't need a matrix.
+- App names are sanitized (lowercased, non-alphanumeric characters replaced with `_`) in the
+  output key names.

github-workflows/actions/kubeconform.md

@@ -0,0 +1,37 @@
+# Action — kubeconform
+
+Validates Kubernetes manifests with [kubeconform](https://github.com/yannh/kubeconform).
+Optionally validates CRDs against the [Datree CRDs-catalog](https://github.com/datreeio/CRDs-catalog)
+(cert-manager, Traefik, etc.).
+
+## Usage
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+
+  - uses: KevinDeBenedetti/github-workflows/.github/actions/kubeconform@main
+    with:
+      paths: kubernetes/
+```
+
+## Inputs
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `paths` | string | `kubernetes/` | Directory containing Kubernetes manifests |
+| `exclude` | string | `*-values.yaml` | Filename pattern to exclude from `find` |
+| `include-crds-catalog` | boolean | `true` | Validate CRDs against the Datree CRDs-catalog |
+
+## Steps
+
+1. Download and install `kubeconform` `0.7.0` to `/usr/local/bin`
+2. Run `kubeconform -strict -summary` on all `*.yaml` files under `paths` (excluding `exclude`)
+
+## Notes
+
+- Run in strict mode — any unknown field causes a validation failure.
+- `include-crds-catalog: true` (default) adds the Datree CRDs-catalog as an extra schema source,
+  enabling validation of common CRD types beyond the built-in Kubernetes schemas.
+- Helm values files (`*-values.yaml`) are excluded by default since they are not valid Kubernetes
+  manifests.

github-workflows/actions/setup-node.md

@@ -0,0 +1,43 @@
+# Action — setup-node
+
+Installs Node.js and the correct package manager (**pnpm** or **bun**), restoring the
+appropriate dependency cache. Auto-detects the package manager from the lockfile.
+
+## Usage
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+
+  - uses: KevinDeBenedetti/github-workflows/.github/actions/setup-node@main
+    with:
+      node-version: '20'
+```
+
+## Inputs
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `node-version` | string | `'20'` | Node.js version to install |
+| `working-directory` | string | `'.'` | Directory to look for lockfile and run install |
+| `package-manager` | string | `auto` | `pnpm` \| `bun` \| `auto` — auto-detects from lockfile |
+| `install` | boolean | `true` | Run install after setup |
+
+## Outputs
+
+| Output | Description |
+|---|---|
+| `package-manager` | Resolved package manager (`pnpm` or `bun`) |
+| `cache-hit` | Whether the package cache was restored |
+
+## Steps
+
+1. Resolve package manager (`bun.lockb` / `bun.lock` → bun, otherwise → pnpm)
+2. Setup pnpm **or** bun (with Node.js)
+3. Restore cache (pnpm store or `~/.bun/install/cache`)
+4. Install dependencies (`--frozen-lockfile`)
+
+## Notes
+
+- `install: 'false'` skips the install step — useful when you only need the toolchain and want to restore a build cache before installing.
+- The `package-manager` output can be used in subsequent steps to conditionally run `pnpm` or `bun` commands.

github-workflows/actions/setup-python.md

@@ -0,0 +1,40 @@
+# Action — setup-python
+
+Installs Python with **uv** and restores the uv dependency cache.
+
+## Usage
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+
+  - uses: KevinDeBenedetti/github-workflows/.github/actions/setup-python@main
+    with:
+      python-version: '3.12'
+```
+
+## Inputs
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `python-version` | string | `'3.12'` | Python version to install |
+| `working-directory` | string | `'.'` | Directory containing `pyproject.toml` |
+| `install` | boolean | `true` | Run `uv sync` after setup |
+
+## Outputs
+
+| Output | Description |
+|---|---|
+| `cache-hit` | Whether the uv cache was restored |
+
+## Steps
+
+1. Install [uv](https://github.com/astral-sh/uv) (latest)
+2. Setup Python `python-version`
+3. Restore uv cache keyed on `uv.lock`
+4. Run `uv sync --frozen`
+
+## Notes
+
+- `install: 'false'` skips the `uv sync` step — useful when you only need the Python + uv toolchain.
+- Cache key is scoped to `runner.os`, `python-version`, and the hash of `uv.lock`, so cache is invalidated when dependencies change.

github-workflows/actions/shellcheck.md

@@ -0,0 +1,27 @@
+# Action — shellcheck
+
+Runs [ShellCheck](https://www.shellcheck.net/) on all `.sh` files in the repository.
+
+## Usage
+
+```yaml
+steps:
+  - uses: actions/checkout@v4
+
+  - uses: KevinDeBenedetti/github-workflows/.github/actions/shellcheck@main
+    with:
+      severity: warning
+```
+
+## Inputs
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `severity` | string | `warning` | Minimum severity level: `error` \| `warning` \| `info` \| `style` |
+| `exclude-paths` | string | `*/test_helper/*` | Glob passed to `find -not -path` to exclude from analysis |
+
+## Notes
+
+- Finds all `*.sh` files recursively under the current directory (excluding `exclude-paths`).
+- Reports issues in GCC format for clean integration with GitHub annotations.
+- Requires ShellCheck to be installed on the runner (available on all `ubuntu-*` runners).