@htekdev/actions-debugger 1.0.22 → 1.0.24

package/errors/silent-failures/cache-hit-output-string-not-boolean.yml

@@ -0,0 +1,96 @@
+id: silent-failures-031
+title: "cache-hit Output Is a String Not a Boolean — Bare true Comparison Always False"
+category: silent-failures
+severity: silent-failure
+tags:
+  - actions/cache
+  - cache-hit
+  - string-comparison
+  - boolean-coercion
+  - conditional
+  - step-outputs
+patterns:
+  - regex: "cache-hit\\s*[!=]=\\s*true(?!')"
+    flags: "i"
+  - regex: "if:\\s+steps\\.\\w+\\.outputs\\.cache-hit\\s*$"
+    flags: "im"
+error_messages:
+  - "steps.cache.outputs.cache-hit == true"
+  - "steps.cache.outputs.cache-hit != true"
+root_cause: |
+  The `cache-hit` output from `actions/cache` and `actions/cache/restore` is a **string** value
+  (`'true'` or `'false'`), not a native boolean. GitHub Actions expression syntax uses strict
+  equality for `==` — there is no implicit type coercion between strings and booleans.
+
+  This means:
+  - `steps.cache.outputs.cache-hit == true`  → ALWAYS false  (string 'true' ≠ boolean true)
+  - `steps.cache.outputs.cache-hit != true`  → ALWAYS true   (install step always runs)
+  - `if: steps.cache.outputs.cache-hit`      → ALWAYS true   ('false' is a non-empty string)
+
+  The most destructive case: `if: steps.cache.outputs.cache-hit != true` is intended to
+  skip the install step on cache hit, but it always evaluates to `true` (runs every time),
+  so the install always runs even after a successful cache restore. Build times remain
+  unchanged, no error is shown, and the caching appears to be broken.
+
+  This applies to ALL GitHub Actions step outputs — they are always strings. A separate
+  but related issue is `cache-hit-restore-keys-misleading` (cache-hit is 'true' on partial
+  key match); this entry covers the unquoted boolean comparison pattern specifically.
+fix: |
+  Always compare `cache-hit` to the string `'true'` with single quotes:
+
+  - Skip install on cache hit:  `if: steps.cache.outputs.cache-hit != 'true'`
+  - Confirm cache was used:     `if: steps.cache.outputs.cache-hit == 'true'`
+
+  Do NOT use bare `true` / `false` (without quotes) in comparisons with step outputs.
+  Do NOT use `if: steps.cache.outputs.cache-hit` as a truthy check — the string 'false'
+  is truthy in most contexts and will always pass.
+fix_code:
+  - language: yaml
+    label: "Correct string comparison for cache-hit (single quotes required)"
+    code: |
+      - name: Cache node_modules
+        id: cache
+        uses: actions/cache@v4
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+      # ❌ WRONG: string 'true' != boolean true → always runs (never skips on cache hit)
+      - name: Install (broken — always runs)
+        if: steps.cache.outputs.cache-hit != true
+        run: npm ci
+
+      # ✅ CORRECT: compare to string 'true' with single quotes
+      - name: Install (correct — skips on cache hit)
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: npm ci
+  - language: yaml
+    label: "Full cache-then-install pattern with correct comparisons"
+    code: |
+      - uses: actions/cache@v4
+        id: npm-cache
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-npm-
+
+      - name: Install dependencies
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npm ci
+
+      - name: Confirm cache was used
+        if: steps.npm-cache.outputs.cache-hit == 'true'
+        run: echo "Cache hit — install skipped"
+prevention:
+  - "Always compare step outputs to string literals with quotes: `== 'true'` not `== true`."
+  - "Remember: ALL GitHub Actions step outputs are strings — never native booleans or numbers."
+  - "Use `actionlint` to lint workflow YAML; it detects boolean vs string type mismatches in conditionals."
+  - "Verify caching is working by observing run time reduction — a successful cache hit noticeably speeds up installs."
+docs:
+  - url: "https://github.com/actions/cache#outputs"
+    label: "actions/cache README: outputs — cache-hit is a string"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#steps-context"
+    label: "GitHub Docs: steps context — all outputs are strings"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#operators"
+    label: "GitHub Docs: Expression operators — == uses strict equality"

package/errors/silent-failures/checkout-lfs-pointer-not-content.yml

@@ -0,0 +1,105 @@
+id: silent-failures-033
+title: "actions/checkout lfs: true Leaves LFS Pointer Metadata Instead of Actual File Content"
+category: silent-failures
+severity: silent-failure
+tags:
+  - checkout
+  - git-lfs
+  - lfs
+  - pointer-file
+  - large-file-storage
+  - self-hosted
+patterns:
+  - regex: "version https://git-lfs\\.github\\.com/spec/v1"
+    flags: "i"
+  - regex: "oid\\s+sha256:[0-9a-f]{64}"
+    flags: "i"
+  - regex: "lfs:\\s*true"
+    flags: "i"
+error_messages:
+  - "version https://git-lfs.github.com/spec/v1"
+  - "oid sha256:f23e4c2b1244bc93085dbccf17c447e54..."
+  - "size 58951008"
+root_cause: |
+  When actions/checkout runs with lfs: true, it configures LFS credentials and
+  attempts to download actual file content for LFS-tracked files. However, the
+  step can exit 0 (success) while leaving LFS pointer metadata files on disk
+  instead of the actual binary or text content.
+
+  This happens silently in several situations:
+
+  - Self-hosted runners without git-lfs installed: the LFS fetch is skipped
+    because the binary is not present. No error is emitted.
+  - LFS bandwidth quota exhausted: GitHub's LFS bandwidth limit (1 GB/month
+    free tier) is silently hit; pointer files remain without a clear warning.
+  - Private cross-repo LFS: checking out a different repository with lfs: true
+    using a token may fail LFS authentication without surfacing an error.
+  - Fork pull requests: LFS objects contributed from fork branches may not be
+    accessible to the base repository workflow.
+
+  The result: downstream tools receive a text file starting with
+  "version https://git-lfs.github.com/spec/v1" instead of actual content,
+  causing opaque failures in build tools, image processors, or test suites.
+fix: |
+  Add an explicit LFS fetch step after checkout. On GitHub-hosted runners,
+  lfs: true is generally sufficient if LFS is configured on the repository.
+  For self-hosted runners, ensure git-lfs is installed before the checkout
+  step runs:
+  - Ubuntu/Debian: sudo apt-get install git-lfs
+  - macOS: brew install git-lfs
+  - Windows: winget install GitHub.GitLFS
+
+  After installation, run the LFS initialization command (git lfs install)
+  once per runner to configure the global LFS hooks.
+
+  To detect unfetched pointer files, add a validation step that checks for
+  the LFS pointer header string in files that should contain real content.
+fix_code:
+  - language: yaml
+    label: "Self-hosted runner — install git-lfs before checkout"
+    code: |
+      steps:
+        - name: Ensure git-lfs is installed
+          run: |
+            sudo apt-get update -qq
+            sudo apt-get install -y git-lfs
+          shell: bash
+
+        - uses: actions/checkout@v4
+          with:
+            lfs: true
+
+        - name: Verify LFS content downloaded
+          run: |
+            if grep -rl "version https://git-lfs.github.com/spec/v1" . \
+               --include="*.bin" --include="*.png" --include="*.zip" 2>/dev/null | head -1 | grep -q .; then
+              echo "ERROR: LFS pointer files found — actual content was not downloaded"
+              exit 1
+            fi
+            echo "LFS check passed — no pointer files found"
+          shell: bash
+
+  - language: yaml
+    label: "GitHub-hosted runner — explicit lfs: true with verification"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+          with:
+            lfs: true
+            # lfs: true is usually sufficient on GitHub-hosted runners
+            # if LFS quota is not exhausted
+prevention:
+  - "Verify git-lfs is installed on all self-hosted runners before running checkout workflows."
+  - "Monitor GitHub LFS bandwidth usage in repository Settings > Billing to avoid silent quota exhaustion."
+  - "Add a post-checkout verification step that confirms LFS-tracked files contain real content, not pointer metadata."
+  - "For fork PRs from external contributors, be aware that LFS objects may not be accessible — consider disabling LFS-dependent tests for fork builds."
+  - "Use GitHub-hosted runners for LFS-heavy workflows to avoid manual git-lfs installation and configuration."
+docs:
+  - url: "https://stackoverflow.com/questions/61463578/github-actions-actions-checkoutv2-lfs-true-flag-not-converting-pointers-to-actual-files"
+    label: "Stack Overflow: actions/checkout lfs:true not converting pointers to actual files (Score: 48, 21K views)"
+  - url: "https://github.com/actions/checkout#usage"
+    label: "actions/checkout: lfs input documentation"
+  - url: "https://docs.github.com/en/repositories/working-with-files/managing-large-files/about-git-large-file-storage"
+    label: "GitHub Docs: About Git Large File Storage"
+  - url: "https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-git-large-file-storage/about-billing-for-git-large-file-storage"
+    label: "GitHub Docs: About billing for Git LFS"

package/errors/silent-failures/reusable-workflow-output-skipped-contains-secret.yml

@@ -0,0 +1,115 @@
+id: silent-failures-030
+title: "Reusable Workflow Output Silently Dropped When Value Contains a Secret Substring"
+category: silent-failures
+severity: silent-failure
+tags:
+  - reusable-workflows
+  - secrets-masking
+  - workflow-outputs
+  - workflow-call
+  - secret-substring
+  - output-propagation
+patterns:
+  - regex: "Skip output '\\w+' since it may contain secret"
+    flags: "i"
+  - regex: "Skip output.*may contain secret"
+    flags: "i"
+error_messages:
+  - "Skip output 'file-url' since it may contain secret."
+  - "Skip output 'artifact-path' since it may contain secret."
+  - "Skip output 'deploy-url' since it may contain secret."
+root_cause: |
+  When a reusable workflow (called via `workflow_call`) propagates a workflow-level `output`
+  whose value contains a substring matching any registered secret, the runner **silently drops
+  the entire output** and logs "Skip output 'X' since it may contain secret." in the callee
+  workflow's log. The calling workflow's `needs.<job>.outputs.X` resolves to an empty string
+  with no error or warning in the caller's logs.
+
+  The runner performs substring matching — if ANY registered secret appears anywhere within the
+  output string (even as a short substring), the runner refuses to propagate the output. Common
+  triggers:
+  - S3 URLs where part of the bucket path matches an AWS access key fragment
+  - File paths with directory components that happen to match a short registered secret
+  - Outputs containing account IDs, port numbers, or other short secrets that appear in
+    longer strings by coincidence
+  - Base64-encoded outputs whose encoding coincidentally contains a secret substring
+
+  This is distinct from `job-output-masked-as-secret-empty` (regular job step outputs masked
+  by actions/runner#1498). The "Skip output" message only appears in reusable workflow output
+  propagation and is ONLY visible in the callee's log — the caller shows no warning, making
+  diagnosis extremely difficult.
+fix: |
+  Avoid including values that contain (or match substrings of) registered secrets in reusable
+  workflow outputs. Structural approaches:
+
+  1. **Return only the non-secret portion** of a path or URL, and reconstruct the full value
+     in the calling workflow using `vars` context or a known prefix.
+  2. **Use artifacts** (`actions/upload-artifact` / `actions/download-artifact`) to pass files
+     or large data payloads between the callee and caller instead of workflow outputs.
+  3. **Check callee logs** for "Skip output" messages — they are invisible from the caller side.
+  4. **Review short secrets**: secrets shorter than ~8 characters risk false-positive substring
+     matches. Consider rotating short secrets to longer values.
+fix_code:
+  - language: yaml
+    label: "Return non-secret path portion; reconstruct in caller"
+    code: |
+      # ❌ BROKEN: output contains secret substring (S3 bucket name matches a secret)
+      on:
+        workflow_call:
+          outputs:
+            artifact-url:
+              value: ${{ jobs.build.outputs.url }}   # silently skipped if URL contains secret
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            url: ${{ steps.upload.outputs.file-url }}
+          steps:
+            - id: upload
+              run: |
+                echo "file-url=https://s3.amazonaws.com/${{ secrets.BUCKET_NAME }}/build-${{ github.run_id }}.zip" \
+                  >> "$GITHUB_OUTPUT"
+
+      ---
+
+      # ✅ WORKAROUND: return only the non-secret key; caller prepends known S3 prefix
+      on:
+        workflow_call:
+          outputs:
+            artifact-key:
+              value: ${{ jobs.build.outputs.key }}   # just "build-12345678.zip" — no secret
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            key: ${{ steps.upload.outputs.key }}
+          steps:
+            - id: upload
+              run: echo "key=build-${{ github.run_id }}.zip" >> "$GITHUB_OUTPUT"
+  - language: yaml
+    label: "Use artifacts to pass files between reusable workflow and caller"
+    code: |
+      # In the reusable workflow job:
+      - uses: actions/upload-artifact@v4
+        with:
+          name: build-output-${{ github.run_id }}
+          path: dist/
+
+      # In the calling workflow job (after the reusable workflow completes):
+      - uses: actions/download-artifact@v4
+        with:
+          name: build-output-${{ github.run_id }}
+          path: dist/
+prevention:
+  - "Never include secret-containing values (URLs, paths, credentials) as reusable workflow outputs."
+  - "Reserve workflow outputs for short, non-sensitive metadata: version strings, boolean flags, run IDs."
+  - "Use artifacts for any data payload that might contain a value related to a registered secret."
+  - "Always check callee workflow logs — not just caller logs — for 'Skip output' messages."
+  - "Register secrets that are long and unique enough not to appear as substrings in build output values."
+docs:
+  - url: "https://stackoverflow.com/questions/72536256/output-in-reusable-workflow-is-incorrectly-recognized-as-secret-github-actions"
+    label: "SO#72536256 — Output incorrectly recognized as secret in reusable workflow (5,709 views)"
+  - url: "https://stackoverflow.com/questions/75061897/github-actions-incorrectly-thinks-variable-is-a-secret-and-so-does-not-set-outpu"
+    label: "SO#75061897 — Actions incorrectly thinks variable is a secret (2,780 views)"
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows#using-outputs-from-a-reusable-workflow"
+    label: "GitHub Docs: Using outputs from a reusable workflow"

package/errors/silent-failures/setup-node-silent-download-exit-zero.yml

@@ -0,0 +1,105 @@
+id: silent-failures-028
+title: "setup-node Silently Exits 0 Without Installing Node.js on Self-Hosted Runners"
+category: silent-failures
+severity: silent-failure
+tags:
+  - setup-node
+  - self-hosted
+  - download-failure
+  - silent-exit
+  - node-not-found
+patterns:
+  - regex: 'Attempting to download [0-9]+\.[0-9]+\.[0-9]+\.\.\.'
+    flags: "i"
+  - regex: "exec: node: not found"
+    flags: "i"
+  - regex: "node: not found"
+    flags: "i"
+error_messages:
+  - "Attempting to download 24.15.0..."
+  - "exec: node: not found"
+  - "node: not found"
+  - "/usr/bin/bash: node: not found"
+root_cause: |
+  On self-hosted runners (particularly those using `gha-runner-scale-set` or ephemeral
+  ARC runners), `actions/setup-node` can sporadically print
+  "Attempting to download <version>..." and then silently exit 0 without completing
+  the download or install.
+
+  The step outcome is `success` and the runner logs show no error — the action
+  simply returns without installing Node.js. Subsequent steps that invoke `node`,
+  `npm`, `pnpm`, or other Node-dependent tools then fail with "exec: node: not found"
+  or equivalent errors, which are far from the actual root cause.
+
+  This is a transient network or HTTP client failure in the `@actions/tool-cache`
+  download path. When the initial download attempt encounters a non-fatal HTTP error
+  (connection reset, early EOF, or interrupted read), the action sometimes swallows
+  the error and exits cleanly rather than retrying or calling `core.setFailed()`.
+  The issue is more common on self-hosted runners where network conditions are more
+  variable than on GitHub-hosted runners.
+
+  The action version affected is v6.x on self-hosted runners with `gha-runner-scale-set`
+  0.13.x and runner 2.334.x. Retrying the job almost always succeeds.
+fix: |
+  Add an explicit Node version verification step after setup-node to catch silent
+  failures before they cause confusing downstream errors:
+
+    - run: node --version
+
+  If this step fails, the issue is with setup-node — not the downstream tool.
+
+  For persistent failures, add a retry wrapper around setup-node, or use the
+  runner's pre-installed Node.js version as a fallback by pinning node-version
+  to the runner's system Node.
+
+  Long-term: upgrade to the latest setup-node patch release — several network
+  resilience improvements have been made to the download path. File an issue at
+  actions/setup-node with runner version, scale-set version, and the relevant
+  log section.
+fix_code:
+  - language: yaml
+    label: "Add immediate verification to catch silent download failure"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-node@v6
+          with:
+            node-version-file: .nvmrc
+            cache: pnpm
+
+        # Catch silent exit-0 failures immediately
+        - name: Verify Node.js installed
+          run: |
+            node --version || (echo "::error::setup-node silently failed — Node.js not installed" && exit 1)
+            npm --version
+
+        - run: pnpm install --frozen-lockfile
+  - language: yaml
+    label: "Retry wrapper using nick-invision/retry"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - name: Setup Node.js with retry
+          uses: nick-invision/retry@v3
+          with:
+            timeout_minutes: 5
+            max_attempts: 3
+            command: |
+              # Re-run setup-node inline
+              echo "Attempt ${{ github.run_attempt }}"
+        - uses: actions/setup-node@v6
+          with:
+            node-version: 24
+prevention:
+  - "Always add a node --version step after setup-node on self-hosted runners to catch silent failures."
+  - "Use check-latest: true to ensure the action validates the installed version before proceeding."
+  - "Report sporadic failures with full runner version, scale-set version, and log output to actions/setup-node."
+  - "Consider using the runner's pre-cached Node.js version (omit node-version) to avoid downloads on self-hosted runners."
+  - "Monitor for setup-node step outcome === 'success' followed by downstream node-not-found — this pattern indicates silent download failure."
+docs:
+  - url: "https://github.com/actions/setup-node/issues/1555"
+    label: "actions/setup-node#1555: Sporadic silent failure when downloading Node.js (12 reactions)"
+  - url: "https://github.com/actions/download-artifact/issues/454"
+    label: "actions/download-artifact#454: Related silent download failure pattern"
+  - url: "https://github.com/actions/toolkit/tree/main/packages/tool-cache"
+    label: "actions/toolkit: tool-cache package (download internals)"

package/errors/silent-failures/setup-python-truncated-manifest-silent-exit.yml

@@ -0,0 +1,111 @@
+id: silent-failures-029
+title: "setup-python Silently Exits 0 Without Installing Python When versions-manifest.json Is Truncated"
+category: silent-failures
+severity: silent-failure
+tags:
+  - setup-python
+  - versions-manifest
+  - silent-exit
+  - truncated-response
+  - python-not-installed
+patterns:
+  - regex: "evaluating 0 versions"
+    flags: "i"
+  - regex: "Version .+ was not found in the local cache"
+    flags: "i"
+  - regex: "Node Action run completed with exit code 0"
+    flags: "i"
+error_messages:
+  - "evaluating 0 versions"
+  - "Version 3.11 - 3.13 was not found in the local cache"
+  - "Getting manifest from actions/python-versions@main"
+  - "##[debug]Node Action run completed with exit code 0"
+  - "##[debug]Finishing: Setup python"
+root_cause: |
+  `actions/setup-python` fetches `versions-manifest.json` from the
+  `actions/python-versions` repository via two GitHub API calls:
+
+  1. A git tree request to locate the blob URL.
+  2. A raw blob fetch with `Accept: application/vnd.github.VERSION.raw`.
+
+  Sporadically, the second call returns HTTP 200 with a **truncated body** — the
+  JSON is cut off mid-object and unparseable. The action catches the JSON parse
+  error silently, treats the result as an empty release list, logs
+  "evaluating 0 versions", and exits with code 0 **without installing Python**.
+
+  The truncated response has two consistent symptoms:
+  - A ~30-second server-side delay before any bytes arrive.
+  - Only affects authenticated requests (5,000 req/hour tier); anonymous requests
+    return the full manifest, but the 60 req/hour limit is too low for real CI.
+
+  After the step exits 0, subsequent steps that call `python`, `pip`, or `python3`
+  either use the system Python (which may differ in version) or fail with
+  "python: not found" — neither of which points back to the manifest fetch failure.
+fix: |
+  Add an explicit Python version check immediately after setup-python to catch the
+  silent exit before it causes confusing downstream errors:
+
+    - run: python --version
+
+  For a more robust workaround, set `python-version` to an exact version string
+  (e.g., "3.11.9") rather than a range — exact versions can fall back to the
+  runner's pre-cached toolcache without requiring a manifest fetch.
+
+  If you must use a version range, add a shell-level retry loop around the Python
+  invocation, or use the `setup-python` `check-latest: false` option with a pinned
+  version to reduce manifest fetches.
+
+  File the issue with captured truncated manifest bodies at actions/setup-python
+  to help maintainers add retry-with-backoff logic to the manifest fetch path.
+fix_code:
+  - language: yaml
+    label: "Catch silent exit immediately after setup-python"
+    code: |
+      steps:
+        - uses: actions/setup-python@v5
+          with:
+            python-version: "3.11 - 3.13"
+            cache: pip
+
+        # Catch silent manifest-fetch failure before downstream confusion
+        - name: Verify Python installed
+          run: |
+            python --version || (echo "::error::setup-python silently failed — Python not installed" && exit 1)
+            pip --version
+
+        - run: pip install -r requirements.txt
+  - language: yaml
+    label: "Use exact version to avoid manifest fetch entirely (uses toolcache)"
+    code: |
+      steps:
+        - uses: actions/setup-python@v5
+          with:
+            python-version: "3.11.9"   # exact version — uses pre-cached toolcache
+            cache: pip                  # no manifest fetch needed for exact match
+        - run: python --version
+        - run: pip install -r requirements.txt
+  - language: yaml
+    label: "Use .python-version file for explicit pinning"
+    code: |
+      # .python-version file: 3.12.7
+      steps:
+        - uses: actions/setup-python@v5
+          with:
+            python-version-file: .python-version  # exact pin, no manifest range fetch
+            cache: pip
+        - run: python --version
+prevention:
+  - "Always add a python --version verification step after setup-python to surface silent failures immediately."
+  - "Pin to an exact Python version (e.g., '3.11.9') rather than a range to use the pre-cached toolcache and avoid manifest fetches."
+  - "Use a .python-version file for reproducible, exact pinning that also works with pyenv locally."
+  - "Monitor for the symptom pattern: setup-python exits 0 + 'evaluating 0 versions' + downstream python-not-found."
+  - "If using version ranges, run setup-python with cache: false first in a debug context to isolate manifest vs. cache failures."
+docs:
+  - url: "https://github.com/actions/setup-python/issues/1318"
+    label: "actions/setup-python#1318: setup-python silently exits 0 on truncated versions-manifest.json"
+  - url: "https://github.com/actions/python-versions"
+    label: "actions/python-versions: Source of versions-manifest.json"
+  - url: "https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#specifying-a-python-version"
+    label: "GitHub Docs: Specifying a Python version"
+  - url: "https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md"
+    label: "setup-python: Advanced Usage"

package/errors/silent-failures/undefined-env-expression-empty-string-silent.yml

@@ -0,0 +1,115 @@
+id: silent-failures-032
+title: "Undefined env/context Variable Silently Evaluates to Empty String"
+category: silent-failures
+severity: silent-failure
+tags:
+  - env-context
+  - expression
+  - undefined-variable
+  - empty-string
+  - silent-failure
+  - jenkins-migration
+patterns:
+  - regex: '\$\{\{\s*env\.[A-Za-z_][A-Za-z0-9_]*\s*\}\}'
+    flags: "i"
+  - regex: "expression.*evaluates.*empty.*string|undefined.*variable.*no.*error"
+    flags: "i"
+error_messages:
+  - "(no error shown -- undefined env/context variables produce empty strings silently)"
+  - "(step proceeds with empty value, downstream steps receive blank input)"
+root_cause: |
+  GitHub Actions expression evaluation does not throw errors when referencing
+  variables that do not exist. An expression like ${{ env.SOME_VAR }} where
+  SOME_VAR is not defined in any env: block evaluates silently to an empty string.
+
+  This behavior affects all expression contexts:
+  - ${{ env.VAR_NAME }} -- undefined env variable evaluates to empty string
+  - ${{ inputs.param }} -- undefined workflow input evaluates to empty string
+  - ${{ vars.CONFIG }} -- undefined repository variable evaluates to empty string
+  - ${{ needs.job.outputs.value }} -- missing job output evaluates to empty string
+
+  Common causes:
+  1. Jenkins migration: GitHub Actions Importer generates env references for all
+     Jenkins variables, but not all are defined in the converted workflow env block.
+  2. Variable renaming: renamed in one place but old reference still used elsewhere.
+  3. Conditional env blocks: variable only set for certain trigger events.
+  4. Copy-paste across repos where the env block differs.
+
+  Silent empty values cause cascading failures:
+  - Docker image tags resolve to empty, pushing to wrong registry path silently
+  - Build version strings empty, artifacts built without version identifier
+  - Path variables empty, steps act on current directory unexpectedly
+  - Conditional checks always false because gating variable is always empty
+  - Upload artifact path empty, upload succeeds with zero files
+fix: |
+  Add explicit variable validation using shell parameter expansion to fail fast
+  with a clear error message when required variables are empty or unset.
+
+  The POSIX ${VAR:?message} syntax causes the step to exit non-zero with a clear
+  error immediately when VAR is empty or unset.
+
+  For non-shell contexts, use the GitHub Actions || operator to provide fallback
+  values or error markers.
+fix_code:
+  - language: yaml
+    label: "Shell validation with POSIX parameter expansion -- fail fast on empty"
+    code: |
+      jobs:
+        deploy:
+          env:
+            DEPLOY_TARGET: ${{ env.DEPLOY_TARGET }}
+            IMAGE_TAG: ${{ env.IMAGE_TAG }}
+          steps:
+            - name: Validate required environment variables
+              shell: bash
+              run: |
+                : "${DEPLOY_TARGET:?DEPLOY_TARGET is required but not set}"
+                : "${IMAGE_TAG:?IMAGE_TAG is required -- check the env: block}"
+                echo "All required variables validated"
+            - name: Deploy
+              run: ./deploy.sh "$DEPLOY_TARGET" "$IMAGE_TAG"
+  - language: yaml
+    label: "Expression fallback to make undefined variables visible in logs"
+    code: |
+      steps:
+        - name: Resolve configuration
+          env:
+            DEPLOY_TARGET: ${{ env.DEPLOY_TARGET || 'MISSING_DEPLOY_TARGET' }}
+          run: |
+            if [[ "$DEPLOY_TARGET" == "MISSING_DEPLOY_TARGET" ]]; then
+              echo "::error::DEPLOY_TARGET is not set -- add it to the env: block"
+              exit 1
+            fi
+            echo "Deploying to: $DEPLOY_TARGET"
+  - language: yaml
+    label: "Bulk audit for Jenkins-migrated workflows"
+    code: |
+      steps:
+        - name: Audit required environment variables
+          shell: bash
+          run: |
+            REQUIRED=(APP_VERSION DEPLOY_ENV BUILD_TARGET REGISTRY_URL)
+            MISSING=()
+            for VAR in "${REQUIRED[@]}"; do
+              [[ -z "${!VAR}" ]] && MISSING+=("$VAR")
+            done
+            if [[ ${#MISSING[@]} -gt 0 ]]; then
+              echo "::error::Missing env vars: ${MISSING[*]} -- add them to env: block"
+              exit 1
+            fi
+            echo "All required variables are set"
+prevention:
+  - "After Jenkins migration, audit all env expression references against the workflow env: block."
+  - "Add a validation step at job start using shell parameter expansion for all required variables."
+  - "Use repository variables (vars.X) instead of env for shared config -- gaps are visible in UI."
+  - "Use the || operator to make undefined variables visible: ${{ env.X || 'MISSING' }}."
+  - "Set required: true on workflow_dispatch inputs to prevent the undefined-input variant."
+docs:
+  - url: "https://stackoverflow.com/questions/76611427/how-to-verify-if-the-github-syntax-variables-actually-exist-in-github-actions-wo"
+    label: "Stack Overflow: Verify GitHub syntax variables exist in workflow YAML"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions"
+    label: "GitHub Docs: Evaluate expressions -- operators including || for defaults"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables"
+    label: "GitHub Docs: Store information in variables -- env, vars, inputs contexts"
+  - url: "https://pubs.opengroup.org/onlinepubs/009604499/utilities/xcu_chap02.html#tag_02_06_02"
+    label: "POSIX Shell: Parameter expansion with :? for unset/empty detection"