@htekdev/actions-debugger 1.0.0 → 1.0.2

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"

package/errors/silent-failures/composite-boolean-inputs-as-strings.yml

@@ -0,0 +1,110 @@
+id: silent-failures-004
+title: "Composite Action Boolean Inputs Treated as Strings — Conditions Always True or Always False"
+category: silent-failures
+severity: silent-failure
+tags:
+  - composite-actions
+  - boolean
+  - inputs
+  - string-coercion
+  - if-condition
+patterns:
+  - regex: "if:\\s*\\$\\{\\{\\s*inputs\\.[a-zA-Z_-]+\\s*\\}\\}"
+    flags: "i"
+  - regex: "inputs\\.[a-zA-Z_-]+\\s*==\\s*true(?!')"
+    flags: "i"
+error_messages:
+  - "realRun==false"
+  - "Step was skipped because it is conditional"
+root_cause: |
+  Composite actions store all inputs internally as strings regardless of the `type:` field declared in
+  `action.yml`. The `type: boolean` annotation is accepted by the YAML parser but has no runtime effect —
+  all values are coerced to strings before expressions are evaluated.
+
+  This creates two distinct silent failure modes:
+
+  1. `if: ${{ inputs.enabled }}` — the string "false" is truthy in GitHub Actions expression syntax,
+     so the step ALWAYS runs even when the caller explicitly passes `enabled: false`.
+
+  2. `if: ${{ inputs.enabled == true }}` — the string "true" never equals the boolean `true` in
+     expression syntax, so the step NEVER runs regardless of the input value.
+
+  In both cases no error is thrown, no warning is emitted, and the workflow succeeds. Only the
+  observable behavior is wrong (unexpected steps run or expected steps are skipped entirely).
+
+  This also affects composite action outputs: any output whose `value:` expression produces a boolean
+  (e.g., `${{ fromJSON(steps.x.outputs.flag) }}`) is silently coerced back to a string before it
+  leaves the composite action.
+fix: |
+  Always compare composite action boolean inputs using string equality:
+
+  - `if: inputs.enabled == 'true'` ✅
+  - `if: ${{ inputs.enabled == 'true' }}` ✅
+  - `if: ${{ inputs.enabled }}` ❌ (always truthy — string "false" is truthy)
+  - `if: ${{ inputs.enabled == true }}` ❌ (never matches — string never equals boolean)
+
+  When passing a boolean workflow_dispatch input into a composite action, cast it to a string explicitly:
+
+  ```yaml
+  with:
+    enabled: ${{ inputs.enabled == true }}   # evaluates to string 'true' or 'false'
+  ```
+fix_code:
+  - language: yaml
+    label: "Use string comparison for boolean inputs inside composite actions"
+    code: |
+      # action.yml (composite action)
+      inputs:
+        enabled:
+          description: "Enable the feature"
+          required: false
+          default: "false"
+          # Note: type: boolean has no runtime effect in composite actions — default must be a string
+
+      runs:
+        using: composite
+        steps:
+          # ❌ WRONG — string "false" is truthy, step always runs
+          # - name: Feature step
+          #   if: ${{ inputs.enabled }}
+
+          # ❌ WRONG — string "true" != boolean true, step never runs
+          # - name: Feature step
+          #   if: ${{ inputs.enabled == true }}
+
+          # ✅ CORRECT — compare as string
+          - name: Feature step
+            if: inputs.enabled == 'true'
+            shell: bash
+            run: echo "Feature is enabled"
+  - language: yaml
+    label: "Cast boolean workflow_dispatch input before passing to composite action"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            run-tests:
+              type: boolean
+              default: false
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: ./.github/actions/my-composite
+              with:
+                # Explicitly cast to string — inputs.run-tests is boolean at this scope
+                run-tests: ${{ inputs.run-tests == true }}
+prevention:
+  - "Never rely on `type: boolean` in composite action inputs — it is parsed but not enforced at runtime."
+  - "Use string `'false'` not boolean `false` as default values in composite action input definitions."
+  - "Always compare composite action boolean inputs with `== 'true'` or `== 'false'` string comparison."
+  - "When passing boolean workflow inputs into composite actions, cast with `${{ inputs.flag == true }}`."
+  - "Document the string-only convention in the composite action README to prevent future contributors from introducing the bug."
+docs:
+  - url: "https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#inputs"
+    label: "Metadata syntax — inputs for composite actions"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions"
+    label: "Evaluate expressions in workflows and actions — truthiness rules"
+  - url: "https://github.com/actions/runner/issues/2238"
+    label: "actions/runner#2238 — Boolean inputs not actually booleans in composite actions (112 reactions)"

package/errors/silent-failures/conditional-output-null-downstream.yml

@@ -0,0 +1,82 @@
+id: silent-failures-007
+title: "Step Output Only Written When Condition Passes — Downstream Reads Empty String"
+category: silent-failures
+severity: silent-failure
+tags:
+  - outputs
+  - steps
+  - context
+  - conditionals
+  - GITHUB_OUTPUT
+  - empty-string
+patterns:
+  - regex: "steps\\.[a-z_-]+\\.outputs\\.[a-z_-]+"
+    flags: "i"
+  - regex: "GITHUB_OUTPUT"
+    flags: "i"
+error_messages:
+  - "Warning: Unexpected input(s) '', valid inputs are ['version']"
+root_cause: |
+  A step output written to `$GITHUB_OUTPUT` (or the deprecated `set-output` command)
+  only exists if the step that writes it actually executed **and** reached the `echo`
+  statement. When a step is conditional (`if: github.event_name == 'push'`) and the
+  condition is false, the step is skipped entirely — no output is written.
+
+  Downstream steps that reference `${{ steps.<id>.outputs.<key> }}` receive an empty
+  string rather than an error, making the failure silent. The workflow continues, but
+  subsequent steps silently operate on empty values — potentially deploying with no
+  version tag, pushing an empty config, or skipping critical logic without any warning.
+fix: |
+  Guard against empty outputs in consuming steps, or restructure so outputs are always
+  written unconditionally and logic is controlled by the value itself.
+fix_code:
+  - language: yaml
+    label: "WRONG — output only written on push, silently empty on PR"
+    code: |
+      steps:
+        - name: Compute version
+          id: version
+          if: github.event_name == 'push'
+          run: echo "tag=v$(date +%Y%m%d%H%M%S)" >> $GITHUB_OUTPUT
+
+        - name: Build Docker image
+          run: |
+            # On pull_request, steps.version.outputs.tag is "" — image tagged as ""
+            docker build -t myapp:${{ steps.version.outputs.tag }} .
+  - language: yaml
+    label: "CORRECT — always write output, vary value by condition"
+    code: |
+      steps:
+        - name: Compute version
+          id: version
+          run: |
+            if [ "${{ github.event_name }}" = "push" ]; then
+              echo "tag=v$(date +%Y%m%d%H%M%S)" >> $GITHUB_OUTPUT
+            else
+              echo "tag=dev-${{ github.sha }}" >> $GITHUB_OUTPUT
+            fi
+
+        - name: Build Docker image
+          run: docker build -t myapp:${{ steps.version.outputs.tag }} .
+  - language: yaml
+    label: "CORRECT — guard against empty value in consuming step"
+    code: |
+      steps:
+        - name: Deploy
+          if: steps.version.outputs.tag != ''
+          run: ./deploy.sh ${{ steps.version.outputs.tag }}
+
+        - name: Warn if no version
+          if: steps.version.outputs.tag == ''
+          run: |
+            echo "::warning::No version tag output — skipping deploy"
+            exit 1
+prevention:
+  - "Write a default/fallback value in the output step rather than skipping the entire step."
+  - "Validate critical outputs with `if: steps.<id>.outputs.<key> != ''` before consuming them."
+  - "Use `if: always()` or no condition on steps that must always emit outputs."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs"
+    label: "Passing information between jobs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-an-output-parameter"
+    label: "Setting an output parameter"

package/errors/silent-failures/continue-on-error-masks-failure.yml

@@ -0,0 +1,86 @@
+id: silent-failures-005
+title: "continue-on-error: true Masks Step Failures — Job Reports Success"
+category: silent-failures
+severity: silent-failure
+tags:
+  - continue-on-error
+  - failure
+  - masking
+  - job-status
+  - outcome
+patterns:
+  - regex: "continue-on-error"
+    flags: "i"
+  - regex: "steps\\.[a-z_-]+\\.outcome.*failure"
+    flags: "i"
+error_messages:
+  - "##[error]Process completed with exit code 1."
+  - "Error: Process completed with exit code 1."
+root_cause: |
+  When `continue-on-error: true` is set on a step, GitHub Actions marks the step's
+  `outcome` as `failure` but sets `conclusion` to `success` and allows the job to
+  continue. Critically, the **job itself reports success** even if one or more steps
+  failed — the failure is effectively swallowed.
+
+  This is frequently misunderstood: developers use `continue-on-error` to avoid blocking
+  a pipeline on non-critical steps, but they don't realise the overall job will show a
+  green checkmark even when those steps fail. Branch protection rules, required status
+  checks, and downstream `needs` jobs all see a passing job.
+
+  The `outcome` context (`steps.<id>.outcome`) still reports `failure`, but this is only
+  visible if explicitly checked in a later conditional.
+fix: |
+  If you need a step to be non-blocking, check its outcome explicitly in a downstream
+  step and surface the failure in a way that's visible (job summary, annotation, or
+  dedicated reporting step). Do not rely on `continue-on-error` as a silent suppressor.
+fix_code:
+  - language: yaml
+    label: "WRONG — failure silently swallowed, job shows green"
+    code: |
+      steps:
+        - name: Run flaky integration test
+          id: integration
+          continue-on-error: true
+          run: ./run-integration.sh
+
+        - name: Deploy
+          run: ./deploy.sh   # runs even if integration test failed, job still green
+  - language: yaml
+    label: "CORRECT — check outcome and fail loudly if needed"
+    code: |
+      steps:
+        - name: Run integration test
+          id: integration
+          continue-on-error: true
+          run: ./run-integration.sh
+
+        - name: Report integration failure
+          if: steps.integration.outcome == 'failure'
+          run: |
+            echo "::error::Integration test failed — review before shipping"
+            echo "## ⚠️ Integration Test Failed" >> $GITHUB_STEP_SUMMARY
+            exit 1   # fail the job explicitly if the failure matters
+  - language: yaml
+    label: "CORRECT — use outcome in branch protection-aware way"
+    code: |
+      steps:
+        - name: Lint (non-blocking)
+          id: lint
+          continue-on-error: true
+          run: npm run lint
+
+        - name: Annotate lint result
+          if: always()
+          run: |
+            if [ "${{ steps.lint.outcome }}" = "failure" ]; then
+              echo "::warning::Linting failed but is non-blocking for this branch"
+            fi
+prevention:
+  - "Treat `continue-on-error: true` as a visibility-reduction tool — always pair it with explicit outcome checking."
+  - "Add a final step that fails the job if any non-critical steps failed and the failure actually matters."
+  - "Prefer `allowed-failure` patterns at the matrix level for known-unstable configurations."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepscontinue-on-error"
+    label: "continue-on-error"
+  - url: "https://docs.github.com/en/actions/learn-github-actions/expressions#steps-context"
+    label: "Steps context — outcome vs conclusion"