From d8c2ae88cdf750107d3773db5544ea9f2f7922ec Mon Sep 17 00:00:00 2001
From: JerrettDavis <mxjerrett@gmail.com>
Date: Sat, 18 Apr 2026 15:38:10 -0500
Subject: [PATCH] ci: validate release workflows with act

Add a workflow-validation CI job that installs actionlint and act,
checks the release and Docker workflows against checked-in event
fixtures, and shares the same validation script developers can run
locally.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/act/docker-version.json |  5 +++++
 .github/workflows/ci.yml        | 18 ++++++++++++++++++
 docs/content/docs/releases.mdx  | 14 ++++++++++++--
 scripts/validate-workflows.sh   |  8 ++++++++
 4 files changed, 43 insertions(+), 2 deletions(-)
 create mode 100644 .github/act/docker-version.json
 create mode 100644 scripts/validate-workflows.sh

diff --git a/.github/act/docker-version.json b/.github/act/docker-version.json
new file mode 100644
index 000000000..082cbaf34
--- /dev/null
+++ b/.github/act/docker-version.json
@@ -0,0 +1,5 @@
+{
+  "inputs": {
+    "version": "0.6.1"
+  }
+}
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index f02021f00..61bff5ef4 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -223,3 +223,21 @@ jobs:
       - uses: wagoid/commitlint-github-action@v5
         with:
           configFile: .commitlintrc.json
+
+  workflow-validation:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install actionlint
+        run: |
+          curl -fsSL https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash | bash
+          sudo mv ./actionlint /usr/local/bin/actionlint
+
+      - name: Install act
+        run: |
+          curl -fsSL https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
+
+      - name: Validate workflow files
+        run: |
+          bash scripts/validate-workflows.sh
diff --git a/docs/content/docs/releases.mdx b/docs/content/docs/releases.mdx
index 7b4b5cf64..016c9992c 100644
--- a/docs/content/docs/releases.mdx
+++ b/docs/content/docs/releases.mdx
@@ -185,7 +185,7 @@ winget install actionlint
 ### Dry-run Test
 
 ```bash
-act -W .github/workflows/release.yml -e .github/act/dry-run.json
+act workflow_dispatch -W .github/workflows/release.yml -e .github/act/dry-run.json
 ```
 
 This runs the full workflow end-to-end with `dry_run=true`, skipping all publish steps.
@@ -193,11 +193,19 @@ This runs the full workflow end-to-end with `dry_run=true`, skipping all publish
 ### Test a Specific Commit Type
 
 ```bash
-act -W .github/workflows/release.yml -e .github/act/push-feat.json
+act push -W .github/workflows/release.yml -e .github/act/push-feat.json
 ```
 
 The `push-feat.json` event file simulates a `feat:` commit on `main`.
 
+### Validate the Release and Docker Workflows
+
+```bash
+bash scripts/validate-workflows.sh
+```
+
+This runs `actionlint` plus `act -n` against the release and Docker workflows using the checked-in `.github/act/*.json` event fixtures. CI runs the same script in the `workflow-validation` job so branch changes to release automation are validated before merge.
+
 ### Local Secrets
 
 ```bash
@@ -220,6 +228,8 @@ cp .env.act.example .env.act
 | `scripts/verify-versions.py` | Pre-release version alignment check |
 | `.github/act/dry-run.json` | `act` event file for dry-run testing |
 | `.github/act/push-feat.json` | `act` event file for feat commit testing |
+| `.github/act/docker-version.json` | `act` event file for Docker workflow validation |
+| `scripts/validate-workflows.sh` | Shared `actionlint` + `act -n` workflow validation script |
 | `.actrc` | Default `act` flags (Ubuntu runner, reuse, quiet) |
 | `.actrc.local.example` | Local `act` override template |
 
diff --git a/scripts/validate-workflows.sh b/scripts/validate-workflows.sh
new file mode 100644
index 000000000..c6a59b93d
--- /dev/null
+++ b/scripts/validate-workflows.sh
@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+actionlint .github/workflows/*.yml
+
+act workflow_dispatch -W .github/workflows/release.yml -e .github/act/dry-run.json -n
+act push -W .github/workflows/release.yml -e .github/act/push-feat.json -n
+act workflow_dispatch -W .github/workflows/docker.yml -e .github/act/docker-version.json -n