@htekdev/actions-debugger 1.0.0 → 1.0.1

package/errors/runner-environment/macos-homebrew-path.yml

@@ -0,0 +1,90 @@
+id: runner-environment-011
+title: "macOS Runner Homebrew Binaries Not on PATH After brew install"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - homebrew
+  - PATH
+  - runner
+  - shell
+  - binary
+patterns:
+  - regex: "command not found.*brew"
+    flags: "i"
+  - regex: "brew: command not found"
+    flags: "i"
+  - regex: "/opt/homebrew/bin.*not found"
+    flags: "i"
+  - regex: "zsh: command not found"
+    flags: "i"
+error_messages:
+  - "zsh: command not found: <tool>"
+  - "Error: Process completed with exit code 127."
+  - "/usr/bin/env: '<tool>': No such file or directory"
+root_cause: |
+  GitHub Actions macOS runners (including `macos-14` and `macos-15` on Apple Silicon)
+  use zsh as the default shell. Homebrew installs binaries to `/opt/homebrew/bin` on
+  Apple Silicon (`macos-14`+) and `/usr/local/bin` on Intel (`macos-13`), but these
+  paths are not always added to `$PATH` for subsequent steps automatically.
+
+  When a step runs `brew install sometool` and then a **later step** attempts to use
+  `sometool`, the binary may not be on `$PATH` because Homebrew's shellenv was never
+  sourced into the Actions runner's shell environment.
+
+  Additionally, `macos-14` moved to Apple Silicon, changing the Homebrew prefix from
+  `/usr/local` to `/opt/homebrew`, which breaks hardcoded path assumptions in scripts
+  that worked on `macos-13`.
+fix: |
+  After installing with Homebrew, explicitly add the binary path to `$GITHUB_PATH`
+  (which persists across subsequent steps in the same job). Alternatively, use
+  `brew --prefix` to get the correct path regardless of architecture.
+fix_code:
+  - language: yaml
+    label: "WRONG — tool installed but not accessible in next step"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - name: Install tool
+              run: brew install sometool
+
+            - name: Use tool
+              run: sometool --version   # Error: zsh: command not found: sometool
+  - language: yaml
+    label: "CORRECT — add brew prefix to GITHUB_PATH"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - name: Install tool
+              run: |
+                brew install sometool
+                # Add homebrew bin to path for all subsequent steps
+                echo "$(brew --prefix)/bin" >> $GITHUB_PATH
+
+            - name: Use tool
+              run: sometool --version   # works
+  - language: yaml
+    label: "CORRECT — source shellenv in a single step"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest
+          steps:
+            - name: Install and run in same step
+              run: |
+                brew install sometool
+                eval "$(brew shellenv)"
+                sometool --version
+prevention:
+  - "After `brew install`, append `$(brew --prefix)/bin` to `$GITHUB_PATH` to persist it across steps."
+  - "Use `brew --prefix <formula>` to get formula-specific paths rather than hardcoding `/usr/local` or `/opt/homebrew`."
+  - "When upgrading from `macos-13` to `macos-14`+, audit any hardcoded `/usr/local` paths for the Homebrew prefix change."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#adding-a-system-path"
+    label: "Adding a system path (GITHUB_PATH)"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "GitHub-hosted runners — supported environments"

package/errors/runner-environment/node-runtime-deprecation.yml

@@ -1,56 +1,56 @@
-id: runner-environment-009
-title: "Node.js Runtime Deprecation"
-category: runner-environment
-severity: warning
-tags:
-  - node
-  - runtime
-  - deprecation
-  - marketplace-actions
-  - compatibility
-patterns:
-  - regex: "Node\\.js 16 actions are deprecated"
-    flags: "i"
-  - regex: "Please update the following actions to use Node\\.js 20"
-    flags: "i"
-  - regex: "runs using Node 16 are deprecated"
-    flags: "i"
-error_messages:
-  - "Node.js 16 actions are deprecated."
-  - "Please update the following actions to use Node.js 20."
-root_cause: |
-  Some marketplace actions bundle a Node.js runtime. When GitHub deprecates an older
-  runtime such as Node 16, workflows can start emitting warnings or eventually fail if the
-  referenced action version has not been updated.
-
-  This is usually caused by pinning an old major version of an action long after the runner
-  platform has moved on.
-fix: |
-  Upgrade the affected action to a maintained version that uses the current supported Node
-  runtime. Review pinned SHAs and major versions for checkout, setup, artifact, and cache
-  actions first because they are common sources of these warnings.
-fix_code:
-  - language: yaml
-    label: "Upgrade action versions to Node 20-compatible releases"
-    code: |
-      steps:
-        - uses: actions/checkout@v4
-        - uses: actions/setup-node@v4
-          with:
-            node-version: 20
-        - uses: actions/upload-artifact@v4
-          with:
-            name: build-output
-            path: dist/
-prevention:
-  - "Review GitHub Actions deprecation notices and keep marketplace action versions current."
-  - "Prefer supported major versions from official `actions/*` repositories."
-  - "Audit pinned SHAs periodically so old runtimes do not linger unnoticed."
-docs:
-  - url: "https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-javascript-actions"
-    label: "JavaScript action runtime metadata"
-  - url: "https://docs.github.com/en/actions/automating-your-workflow-with-github-actions/metadata-syntax-for-github-actions"
-    label: "Metadata syntax for GitHub Actions"
-source:
-  article: "https://htek.dev/articles/github-actions-debugging-guide"
-  section: "Node runtime deprecation warnings"
+id: runner-environment-009
+title: "Node.js Runtime Deprecation"
+category: runner-environment
+severity: warning
+tags:
+  - node
+  - runtime
+  - deprecation
+  - marketplace-actions
+  - compatibility
+patterns:
+  - regex: "Node\\.js 16 actions are deprecated"
+    flags: "i"
+  - regex: "Please update the following actions to use Node\\.js 20"
+    flags: "i"
+  - regex: "runs using Node 16 are deprecated"
+    flags: "i"
+error_messages:
+  - "Node.js 16 actions are deprecated."
+  - "Please update the following actions to use Node.js 20."
+root_cause: |
+  Some marketplace actions bundle a Node.js runtime. When GitHub deprecates an older
+  runtime such as Node 16, workflows can start emitting warnings or eventually fail if the
+  referenced action version has not been updated.
+
+  This is usually caused by pinning an old major version of an action long after the runner
+  platform has moved on.
+fix: |
+  Upgrade the affected action to a maintained version that uses the current supported Node
+  runtime. Review pinned SHAs and major versions for checkout, setup, artifact, and cache
+  actions first because they are common sources of these warnings.
+fix_code:
+  - language: yaml
+    label: "Upgrade action versions to Node 20-compatible releases"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v4
+          with:
+            node-version: 20
+        - uses: actions/upload-artifact@v4
+          with:
+            name: build-output
+            path: dist/
+prevention:
+  - "Review GitHub Actions deprecation notices and keep marketplace action versions current."
+  - "Prefer supported major versions from official `actions/*` repositories."
+  - "Audit pinned SHAs periodically so old runtimes do not linger unnoticed."
+docs:
+  - url: "https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-javascript-actions"
+    label: "JavaScript action runtime metadata"
+  - url: "https://docs.github.com/en/actions/automating-your-workflow-with-github-actions/metadata-syntax-for-github-actions"
+    label: "Metadata syntax for GitHub Actions"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Node runtime deprecation warnings"

package/errors/runner-environment/npm-ci-lockfile-mismatch.yml

@@ -0,0 +1,112 @@
+id: runner-environment-015
+title: "npm ci Fails with Lockfile Mismatch or Missing package-lock.json"
+category: runner-environment
+severity: error
+tags:
+  - npm
+  - npm-ci
+  - lockfile
+  - package-lock.json
+  - dependencies
+  - node
+  - reproducible
+patterns:
+  - regex: "npm ci.*can only install.*package-lock\\.json"
+    flags: "i"
+  - regex: "Missing script.*ci"
+    flags: "i"
+  - regex: "npm ERR! code EUSAGE"
+    flags: "i"
+  - regex: "npm warn saveError ENOENT.*package-lock\\.json"
+    flags: "i"
+  - regex: "npm ERR!.*lock file.*older npm"
+    flags: "i"
+  - regex: "EBADENGINE"
+    flags: "i"
+error_messages:
+  - "npm error The `npm ci` command can only install with an existing package-lock.json"
+  - "npm warn saveError ENOENT: no such file or directory, open '/home/runner/work/.../package-lock.json'"
+  - "npm error `npm ci` can only install packages when your package.json and package-lock.json are in sync."
+  - "npm error Missing: <package>@<version> from lock file"
+root_cause: |
+  `npm ci` is strict by design — it requires `package-lock.json` to be present and
+  exactly in sync with `package.json`. It fails in several common CI scenarios:
+
+  1. **No lockfile committed** — developers add `package-lock.json` to `.gitignore`
+     (common in library repos) — `npm ci` refuses to run.
+
+  2. **Lockfile out of sync** — a developer ran `npm install` locally which updated
+     the lockfile, but committed `package.json` without the updated lockfile, or vice versa.
+     `npm ci` reports "Missing: package@version from lock file."
+
+  3. **Lockfile from incompatible npm version** — npm v6 lockfiles (lockfileVersion 1)
+     cannot be used with `npm ci` in npm v7+ projects that use workspaces, and vice versa.
+
+  4. **Monorepo workspace packages not locked** — `package-lock.json` at root does not
+     lock workspace packages listed in `packages/*` if each sub-package has its own
+     `package.json` without being part of the root workspaces config.
+fix: |
+  Commit `package-lock.json` to the repository (do not gitignore it in apps). Keep
+  `package.json` and `package-lock.json` in sync by running `npm install` locally
+  after any manifest change and committing both files together.
+fix_code:
+  - language: yaml
+    label: "CORRECT — npm ci with Node version matrix and lockfile caching"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          strategy:
+            matrix:
+              node-version: ['18.x', '20.x']
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: actions/setup-node@v4
+              with:
+                node-version: ${{ matrix.node-version }}
+                cache: npm                 # caches ~/.npm using package-lock.json hash
+
+            - name: Install dependencies
+              run: npm ci                  # fails fast if lockfile is out of sync
+
+            - name: Run tests
+              run: npm test
+  - language: yaml
+    label: "Detect lockfile sync issues before CI"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v4
+          with:
+            node-version: 20
+
+        - name: Verify lockfile is up to date
+          run: |
+            npm install --package-lock-only
+            git diff --exit-code package-lock.json || {
+              echo "::error::package-lock.json is out of sync with package.json"
+              echo "Run 'npm install' locally and commit the updated lockfile"
+              exit 1
+            }
+
+        - run: npm ci
+  - language: bash
+    label: "Fix gitignore — ensure lockfile is tracked"
+    code: |
+      # If package-lock.json is gitignored, remove it from .gitignore
+      grep -v "package-lock.json" .gitignore > .gitignore.tmp && mv .gitignore.tmp .gitignore
+      git add package-lock.json
+      git commit -m "chore: track package-lock.json for reproducible CI"
+prevention:
+  - "Always commit `package-lock.json` to git — never gitignore it in application repos."
+  - "Run `npm install` (not just `npm ci`) locally after any `package.json` change and commit both files atomically."
+  - "Add a `Verify lockfile` step to CI that runs `npm install --package-lock-only && git diff --exit-code package-lock.json` to catch drift early."
+  - "Renovate Bot and Dependabot automatically keep lockfiles in sync when configured correctly."
+docs:
+  - url: "https://docs.npmjs.com/cli/v10/commands/npm-ci"
+    label: "npm ci (npmjs docs)"
+  - url: "https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#caching-npm-packages"
+    label: "Caching npm packages"
+  - url: "https://github.com/actions/setup-node#caching-global-packages-data"
+    label: "actions/setup-node — npm caching"

package/errors/runner-environment/self-hosted-stale-toolcache.yml

@@ -0,0 +1,73 @@
+id: runner-environment-013
+title: "Self-Hosted Runner Stale Tool Cache Serves Outdated Versions"
+category: runner-environment
+severity: silent-failure
+tags:
+  - self-hosted
+  - tool-cache
+  - setup-node
+  - setup-python
+  - setup-java
+  - outdated
+  - toolcache
+patterns:
+  - regex: "Found in cache"
+    flags: "i"
+  - regex: "Resolved .* from tool-cache"
+    flags: "i"
+  - regex: "Tool cache hit.*[0-9]+\\.[0-9]+"
+    flags: "i"
+error_messages:
+  - "Found in cache @ /opt/hostedtoolcache/node/18.12.0/x64"
+  - "Resolved Node 18.12.0 from tool-cache"
+root_cause: |
+  `actions/setup-node`, `actions/setup-python`, `actions/setup-java`, and similar setup
+  actions maintain a **tool cache** on the runner host. On GitHub-hosted runners this
+  cache is wiped between jobs (fresh VMs), but on **self-hosted runners** the cache
+  persists indefinitely across runs.
+
+  When a self-hosted runner's tool cache has a matching version range (e.g., `node-version: 18.x`)
+  it returns the cached version without downloading a fresh copy. If that cached version
+  contains a security vulnerability or a bug that was patched in a newer patch release,
+  workflows silently continue using the vulnerable version. There is no warning — the log
+  shows "Found in cache" and proceeds.
+
+  This also happens when teams pin to `18.x` intending to get the latest 18 minor but the
+  cache serves the version that was first downloaded months ago.
+fix: |
+  Pin to exact versions in production workflows. Periodically purge the tool cache on
+  self-hosted runners. Use the `check-latest` input to force setup actions to verify
+  whether a newer patch release is available.
+fix_code:
+  - language: yaml
+    label: "WRONG — loose version range silently serves cached old version"
+    code: |
+      steps:
+        - uses: actions/setup-node@v4
+          with:
+            node-version: 18     # resolves to whatever 18.x is in cache
+  - language: yaml
+    label: "CORRECT — pin exact version for reproducibility"
+    code: |
+      steps:
+        - uses: actions/setup-node@v4
+          with:
+            node-version: '18.20.4'   # exact version, cache miss forces fresh download
+  - language: yaml
+    label: "CORRECT — use check-latest to force freshness check"
+    code: |
+      steps:
+        - uses: actions/setup-node@v4
+          with:
+            node-version: '18.x'
+            check-latest: true    # verifies cache against upstream, downloads if newer available
+prevention:
+  - "Pin to exact tool versions (`18.20.4` not `18.x`) on self-hosted runners to ensure cache hits are intentional."
+  - "Schedule periodic purges of `/opt/hostedtoolcache` (or Windows equivalent) on self-hosted runners."
+  - "Use `check-latest: true` on self-hosted runners when using semver ranges."
+  - "Document your self-hosted runner's tool cache contents and last purge date."
+docs:
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners"
+    label: "About self-hosted runners"
+  - url: "https://github.com/actions/setup-node#check-latest-version"
+    label: "actions/setup-node — check-latest input"

package/errors/runner-environment/setup-node-version-file-missing.yml

@@ -0,0 +1,105 @@
+id: runner-environment-010
+title: "actions/setup-node Fails When .nvmrc or node-version-file Is Missing"
+category: runner-environment
+severity: error
+tags:
+  - setup-node
+  - nvmrc
+  - node-version
+  - node-version-file
+  - version-resolution
+patterns:
+  - regex: "The specified node version file at.*does not exist"
+    flags: "i"
+  - regex: "Unable to find Node version '\\$\\{.*\\}'"
+    flags: "i"
+  - regex: "Unable to find Node version '.*' for platform"
+    flags: "i"
+  - regex: "Cache service responded with 422"
+    flags: "i"
+error_messages:
+  - "The specified node version file at: /__w/actions/actions/.nvmrc does not exist"
+  - "##[error]Unable to find Node version '${NVMRC}' for platform linux and architecture x64."
+  - "##[error]Unable to find Node version '16.99.0' for platform linux and architecture x64."
+  - "Error: Cache service responded with 422"
+root_cause: |
+  `actions/setup-node` supports three ways to specify a Node.js version:
+  `node-version` (inline), `node-version-file` (reads from a file), or auto-detection.
+  These fail in distinct ways:
+
+  1. **Missing version file** (`node-version-file: '.nvmrc'` or `'.node-version'`):
+     If the file referenced by `node-version-file` does not exist on the runner at the
+     path provided, setup-node throws "The specified node version file … does not exist"
+     and the step fails. This commonly happens when the file exists in the repo root but
+     the workflow runs in a subdirectory, or when the checkout step runs after setup-node.
+
+  2. **Unresolved environment variable** (`node-version: '${{ env.NVMRC }}'`):
+     Using a shell env var (e.g., `$NVMRC`) instead of an Actions expression
+     (`${{ env.NVMRC }}`) means the value is never substituted — setup-node receives a
+     literal `${NVMRC}` string, which is not a valid version, and fails with "Unable to
+     find Node version '${NVMRC}'". Similarly, if `env.NVMRC` is not set at the point
+     setup-node runs, the expression evaluates to empty string.
+
+  3. **Non-existent or misspelled version** (`node-version: '16.99.0'`):
+     Requesting a version that GitHub's node distribution manifest does not list causes
+     "Unable to find Node version." This can happen after pinning to a patch version
+     that was later delisted.
+
+  4. **Old setup-node version + cache service 422**:
+     Older setup-node versions (v1/v2) use a deprecated cache service API that now
+     returns HTTP 422. The fix is upgrading to setup-node@v3 or v4.
+fix: |
+  1. Ensure `actions/checkout` runs **before** any `actions/setup-node` step that reads
+     `node-version-file` — the file must exist on the runner when setup-node reads it.
+  2. Use Actions expressions (`${{ env.VAR }}`) not shell syntax (`$VAR`) for
+     `node-version` values.
+  3. For `.nvmrc`, prefer the `node-version-file: '.nvmrc'` parameter directly rather
+     than reading the file in a shell step and passing it to `node-version`.
+  4. Upgrade to `actions/setup-node@v4` to avoid the deprecated cache service 422 error.
+fix_code:
+  - language: yaml
+    label: "Correct order: checkout before setup-node with node-version-file"
+    code: |
+      steps:
+        - uses: actions/checkout@v4       # Must come BEFORE setup-node
+        - uses: actions/setup-node@v4
+          with:
+            node-version-file: '.nvmrc'   # Reads .nvmrc from the checked-out repo
+            cache: 'npm'
+  - language: yaml
+    label: "Inline version — use Actions expression, not shell variable"
+    code: |
+      env:
+        NODE_VERSION: '20'
+
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v4
+          with:
+            node-version: ${{ env.NODE_VERSION }}   # ✅ Actions expression
+            # node-version: $NODE_VERSION           # ❌ Shell syntax — not expanded
+  - language: yaml
+    label: "Read .nvmrc manually when node-version-file is insufficient"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - name: Read .nvmrc
+          id: nvmrc
+          run: echo "version=$(cat .nvmrc)" >> $GITHUB_OUTPUT
+        - uses: actions/setup-node@v4
+          with:
+            node-version: ${{ steps.nvmrc.outputs.version }}
+prevention:
+  - "Always run `actions/checkout` before any step that reads files from the repository, including `node-version-file`."
+  - "Use `actions/setup-node@v4` — v1/v2 are deprecated and trigger cache service 422 errors."
+  - "Prefer `node-version-file: '.nvmrc'` over reading the file in a shell step to avoid shell escaping issues."
+  - "Pin to a Node.js major version (e.g., `20`) rather than a full SemVer patch to avoid version-not-found errors."
+docs:
+  - url: "https://github.com/actions/setup-node"
+    label: "actions/setup-node — README and usage"
+  - url: "https://github.com/actions/setup-node/issues/613"
+    label: "setup-node#613 — node-version-file does not exist error"
+  - url: "https://github.com/actions/setup-node/issues/32"
+    label: "setup-node#32 — Using .nvmrc with env variable substitution"
+  - url: "https://github.com/actions/setup-node/issues/1275"
+    label: "setup-node#1275 — Cache service 422 — upgrade to v3/v4"

package/errors/runner-environment/windows-execution-policy.yml

@@ -0,0 +1,83 @@
+id: runner-environment-012
+title: "Windows Runner PowerShell Execution Policy Blocks Custom Scripts"
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - powershell
+  - execution-policy
+  - scripts
+  - runner
+  - security
+patterns:
+  - regex: "cannot be loaded because running scripts is disabled"
+    flags: "i"
+  - regex: "execution policy"
+    flags: "i"
+  - regex: "UnauthorizedAccess.*\\.ps1"
+    flags: "i"
+  - regex: "File .+\\.ps1 cannot be loaded"
+    flags: "i"
+error_messages:
+  - "File C:\\...\\script.ps1 cannot be loaded because running scripts is disabled on this system."
+  - "UnauthorizedAccess: File C:\\...\\script.ps1 cannot be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies"
+root_cause: |
+  Windows GitHub-hosted runners default to the `RemoteSigned` execution policy, which
+  requires that downloaded scripts be digitally signed. Scripts created inline during a
+  workflow or checked out from the repo can trigger this restriction depending on how
+  they are invoked, especially when called via `powershell.exe` directly or from a
+  third-party action that spawns a new PowerShell session with a more restrictive default.
+
+  This is particularly common when a workflow uses `shell: powershell` (legacy
+  `powershell.exe` v5) where the execution policy is stricter, or when a script file
+  is written to disk by a previous step and then invoked.
+fix: |
+  Use `shell: pwsh` (PowerShell 7+) which defaults to `Bypass` execution policy in
+  GitHub Actions workflows. For `shell: powershell` sessions, prefix the script
+  invocation with `Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass`.
+fix_code:
+  - language: yaml
+    label: "WRONG — script fails with execution policy error"
+    code: |
+      jobs:
+        build:
+          runs-on: windows-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Run build script
+              shell: powershell
+              run: .\scripts\build.ps1   # may fail: execution policy
+  - language: yaml
+    label: "CORRECT — use pwsh (PowerShell 7) which defaults to Bypass"
+    code: |
+      jobs:
+        build:
+          runs-on: windows-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Run build script
+              shell: pwsh            # PowerShell 7+ — Bypass policy by default
+              run: .\scripts\build.ps1
+  - language: yaml
+    label: "CORRECT — explicitly bypass in legacy powershell session"
+    code: |
+      jobs:
+        build:
+          runs-on: windows-latest
+          steps:
+            - name: Run legacy PS script
+              shell: powershell
+              run: |
+                Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
+                .\scripts\build.ps1
+prevention:
+  - "Prefer `shell: pwsh` over `shell: powershell` for all new Windows workflows — it's PowerShell 7+ and more permissive."
+  - "Avoid calling `.ps1` files from non-PowerShell shells (cmd, bash) — invoke them via `pwsh -File script.ps1` instead."
+  - "Test Windows workflows locally with the same shell version (`pwsh` vs `powershell`) before pushing."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsshell"
+    label: "jobs.<job_id>.steps[*].shell"
+  - url: "https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy"
+    label: "Set-ExecutionPolicy (Microsoft Learn)"

package/errors/silent-failures/add-mask-no-retroactive-masking.yml

@@ -0,0 +1,75 @@
+id: silent-failures-006
+title: "add-mask Does Not Retroactively Redact Values Already Printed"
+category: silent-failures
+severity: silent-failure
+tags:
+  - secrets
+  - masking
+  - add-mask
+  - security
+  - log-redaction
+  - sensitive-data
+patterns:
+  - regex: "::add-mask::"
+    flags: "i"
+  - regex: "add_mask"
+    flags: "i"
+error_messages:
+  - "Warning: Secret value was printed to log before masking was applied."
+root_cause: |
+  The `add-mask` workflow command (`echo "::add-mask::$VALUE"`) tells the runner to
+  redact all future occurrences of `$VALUE` from log output. However, it only applies
+  **from the point it is issued forward** — any log lines already written before the
+  `add-mask` command are not retroactively redacted.
+
+  This creates a silent security failure when a step prints a sensitive value in an
+  earlier `run:` command and only calls `add-mask` later. The value appears in plain
+  text in the workflow log for the duration the log is retained (90 days by default).
+
+  A common pattern that triggers this: computing a token at the start of a long `run:`
+  script, printing it for debugging, and only masking it several lines later.
+fix: |
+  Issue `add-mask` as the very first operation after obtaining a sensitive value —
+  before any `echo`, `cat`, or other command that might emit it. Prefer using
+  built-in `secrets.*` context (which is auto-masked) over dynamically computed
+  sensitive values wherever possible.
+fix_code:
+  - language: yaml
+    label: "WRONG — value printed before add-mask is issued"
+    code: |
+      steps:
+        - name: Get dynamic token
+          run: |
+            TOKEN=$(curl -s https://api.example.com/token | jq -r .access_token)
+            echo "Got token: $TOKEN"        # PRINTED IN PLAIN TEXT
+            echo "::add-mask::$TOKEN"       # too late — above line already logged
+            echo "TOKEN=$TOKEN" >> $GITHUB_ENV
+  - language: yaml
+    label: "CORRECT — mask before any output"
+    code: |
+      steps:
+        - name: Get dynamic token
+          run: |
+            TOKEN=$(curl -s https://api.example.com/token | jq -r .access_token)
+            echo "::add-mask::$TOKEN"       # mask FIRST
+            echo "TOKEN=$TOKEN" >> $GITHUB_ENV
+            echo "Token acquired and masked successfully"  # no value, safe to log
+  - language: yaml
+    label: "CORRECT — use secrets context (auto-masked)"
+    code: |
+      steps:
+        - name: Use pre-configured secret
+          env:
+            API_TOKEN: ${{ secrets.API_TOKEN }}  # automatically masked everywhere
+          run: |
+            curl -H "Authorization: Bearer $API_TOKEN" https://api.example.com/data
+prevention:
+  - "Always call `add-mask` as the very first line after obtaining a sensitive value."
+  - "Prefer `secrets.*` context values over dynamically fetched tokens where possible."
+  - "Never print sensitive values for debugging — use `echo 'Token acquired (masked)'` instead."
+  - "Audit workflows that call external APIs and store tokens in env vars for missing `add-mask`."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#masking-a-value-in-a-log"
+    label: "Masking a value in a log"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions"
+    label: "Security hardening for GitHub Actions"