Add workflow linting with actionlint

Author: Boyeep

.github/workflows/template-ci.yml

@@ -10,6 +10,26 @@ permissions:
   contents: read
 
 jobs:
+  workflow-lint:
+    name: Workflow Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: "1.25.1"
+
+      - name: Lint GitHub Actions workflows
+        run: npm run check:workflows
+
   contract-drift:
     name: Contract Drift
     runs-on: ubuntu-latest

AGENTS.md

@@ -49,6 +49,7 @@ Use these commands before finishing work:
 
 ```bash
 npm run check:contract
+npm run check:workflows
 npm run check
 ```
 

CONTRIBUTING.md

@@ -69,6 +69,12 @@ If Docker is available locally, you can also verify the production-style images:
 npm run check:images
 ```
 
+If Go is available locally, you can also lint GitHub Actions workflows:
+
+```bash
+npm run check:workflows
+```
+
 ## Changing the API Contract
 
 If you modify request or response shapes:

README.md

@@ -96,6 +96,7 @@ npm run dev:down
 npm run api:types
 npm run check:contract
 npm run check:images
+npm run check:workflows
 npm run check
 ```
 
@@ -112,6 +113,8 @@ The root check runs:
 
 `check:images` is separate and intended for environments where a Docker daemon is available.
 
+`check:workflows` lints `.github/workflows/` with a pinned `actionlint` version via Go.
+
 ## Releases
 
 - Release Drafter keeps a draft release updated from merged pull requests on `main` and can auto-label incoming pull requests by path.

package.json

@@ -9,6 +9,7 @@
     "check:contract": "node scripts/check-contract-drift.mjs",
     "check:images": "node scripts/check-docker-builds.mjs",
     "check:release-smoke": "node scripts/check-release-smoke.mjs",
+    "check:workflows": "node scripts/check-actionlint.mjs",
     "check": "node scripts/check.mjs"
   },
   "keywords": [

scripts/check-actionlint.mjs

@@ -0,0 +1,45 @@
+import { spawnSync } from "node:child_process";
+import process from "node:process";
+
+const ACTIONLINT_VERSION = process.env.ACTIONLINT_VERSION ?? "v1.7.11";
+const shell = process.platform === "win32";
+
+function run(command, args, options = {}) {
+  return spawnSync(command, args, {
+    stdio: options.capture ? "pipe" : "inherit",
+    encoding: options.capture ? "utf8" : undefined,
+    shell,
+  });
+}
+
+const goVersion = run("go", ["version"], { capture: true });
+
+if (goVersion.error || goVersion.status !== 0) {
+  const details = [goVersion.stdout, goVersion.stderr].filter(Boolean).join("\n").trim();
+  console.error(
+    "Go is required to run workflow lint locally. Install Go or rely on the CI workflow-lint job.",
+  );
+
+  if (details) {
+    console.error(details);
+  }
+
+  process.exit(goVersion.status ?? 1);
+}
+
+const args = [
+  "run",
+  `github.com/rhysd/actionlint/cmd/actionlint@${ACTIONLINT_VERSION}`,
+  "-shellcheck=",
+  "-pyflakes=",
+  ...process.argv.slice(2),
+];
+
+const result = run("go", args);
+
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);