@htekdev/actions-debugger 1.0.124 → 1.0.126

package/errors/silent-failures/silent-failures-115.yml

@@ -0,0 +1,130 @@
+id: silent-failures-115
+title: 'actions/cache save exits 0 and logs "Cache saved" despite 503 backend upload failures'
+category: silent-failures
+severity: silent-failure
+tags:
+  - actions/cache
+  - cache-save
+  - 503
+  - backend-error
+  - silent-success
+  - false-positive
+  - upload
+patterns:
+  - regex: 'Cache service responded with 503'
+    flags: 'i'
+  - regex: 'uploadChunk .+ failed: Cache service responded with'
+    flags: 'i'
+  - regex: 'Warning: Failed to save: uploadChunk .+ failed'
+    flags: 'i'
+error_messages:
+  - 'Warning: Failed to save: uploadChunk (start: 67108864, end: 100663295) failed: Cache service responded with 503'
+  - 'Cache saved with key: Linux-<run_id>-build'
+root_cause: |
+  When `actions/cache` (or `actions/cache/save@v4`) uploads a cache, it
+  splits the archive into chunks and uploads them in parallel using the Azure
+  SDK `BlobClient`. If the backend returns HTTP 503 errors for individual
+  chunks, the action retries once but ultimately logs the failure as a
+  `Warning:` line and continues.
+
+  The critical flaw is that the action then calls `commitCache()` to finalize
+  the cache entry regardless of whether all chunks uploaded successfully.
+  The cache entry is committed to the Actions service database even though
+  the underlying blob storage is corrupt or incomplete.
+
+  This results in a silently false "cache saved" state:
+  - The action logs `Cache saved with key: <key>` (green success)
+  - The job exits with code 0 (no failure)
+  - BUT the stored cache entry is corrupt or truncated
+
+  On the next run, `actions/cache/restore` (or the inline `actions/cache`
+  restore phase) either fails with a decompression/extraction error or
+  silently falls back to "Cache not found" — depending on the extent of
+  corruption. The developer sees a cache miss on the restore side and
+  investigates there, never realizing the root cause was a silent save failure
+  several runs earlier.
+
+  This pattern is especially harmful when:
+  - The cache backend is temporarily degraded (503 storms during peak usage)
+  - The cache key includes the run_id, making the corrupt entry unique and
+    never overwritten by a subsequent run with the same key
+  - The project has long build times that the cache was supposed to skip
+fix: |
+  1. **Add a post-save validation step** that calls the GitHub Actions cache
+     REST API to confirm the cache entry was actually committed:
+
+     ```bash
+     gh api "/repos/${{ github.repository }}/actions/caches?key=${{ steps.cache.outputs.cache-primary-key }}" \
+       | jq -e '.actions_caches | length > 0' || { echo "Cache save failed — no entry in API"; exit 1; }
+     ```
+
+  2. **Use `save-always: false` (the default)** — only invoke `actions/cache`
+     for save when you know the prior job succeeded. If you use the `save`
+     sub-action with `save-always: true`, be aware that backend failures are
+     swallowed.
+
+  3. **Separate save from restore** using the `actions/cache/save` and
+     `actions/cache/restore` sub-actions so you can add explicit error
+     handling around the save step via `continue-on-error: false`.
+
+  4. **Monitor for the upstream fix** in actions/cache#1416. Once the action
+     propagates chunk upload failures to the overall exit code, the job will
+     correctly fail on corrupt saves.
+fix_code:
+  - language: yaml
+    label: 'Validate cache was committed after save using the REST API'
+    code: |
+      - name: Cache node modules
+        id: cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
+
+      - name: Verify cache entry was committed
+        if: steps.cache.outputs.cache-hit != 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          KEY="${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}"
+          COUNT=$(gh api \
+            "/repos/${{ github.repository }}/actions/caches?key=${KEY}" \
+            --jq '.actions_caches | length')
+          if [ "$COUNT" -eq 0 ]; then
+            echo "::error::Cache save reported success but no entry found in API. Backend may have returned 503."
+            exit 1
+          fi
+  - language: yaml
+    label: 'Separate save from restore to add explicit error handling'
+    code: |
+      # In your build job:
+      - name: Restore cache
+        id: cache-restore
+        uses: actions/cache/restore@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
+
+      - run: npm ci
+
+      - name: Save cache
+        if: steps.cache-restore.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
+        # NOTE: If this step shows "Warning: Failed to save: uploadChunk..."
+        # but still exits 0, the cache is corrupt. Add the REST API validation
+        # step above to catch this scenario.
+prevention:
+  - 'Watch for "Warning: Failed to save: uploadChunk ... failed: Cache service responded with 503" in your workflow logs — this indicates a silent corrupt save even though the step shows green.'
+  - 'If you see intermittent cache misses that cannot be explained by key changes, check whether the previous save step logged any 503 chunk-upload warnings.'
+  - 'Use time-bounded cache keys (e.g. including the week number) so a corrupt entry from a bad save is overwritten on the next successful run rather than being cached indefinitely.'
+  - 'For critical caches that must succeed, add a post-save REST API validation step to fail fast when the backend silently corrupted the save.'
+docs:
+  - url: 'https://github.com/actions/cache/issues/1416'
+    label: 'actions/cache#1416 — actions/cache and actions/cache/save consider cache uploaded successfully even with backend errors'
+  - url: 'https://docs.github.com/en/rest/actions/cache?apiVersion=2022-11-28#list-github-actions-caches-for-a-repository'
+    label: 'GitHub REST API — List GitHub Actions caches for a repository'
+  - url: 'https://github.com/actions/cache/blob/main/tips-and-workarounds.md'
+    label: 'actions/cache — Tips and Workarounds'

package/errors/silent-failures/silent-failures-116.yml

@@ -0,0 +1,117 @@
+id: silent-failures-116
+title: 'actions/checkout sparse-checkout silently falls back to full REST API download when git < 2.28'
+category: silent-failures
+severity: silent-failure
+tags:
+  - checkout
+  - sparse-checkout
+  - git-version
+  - self-hosted
+  - rest-api-fallback
+  - silent
+  - git
+patterns:
+  - regex: 'Minimum Git version required for sparse checkout is 2\.28'
+    flags: 'i'
+  - regex: 'Failed to initialize CommandManager.*sparse'
+    flags: 'i'
+  - regex: 'Falling back to downloading using the GitHub REST API'
+    flags: 'i'
+error_messages:
+  - 'Minimum Git version required for sparse checkout is 2.28. Your git (/path/to/git) is 2.23'
+  - 'Falling back to downloading using the GitHub REST API'
+  - 'Warning: The git version installed on this runner is 2.x which is lower than the minimum required version 2.28 for sparse checkout'
+root_cause: |
+  actions/checkout supports `sparse-checkout` configuration, which requires git 2.28 or
+  later (because sparse-checkout with cone-mode patterns uses `git sparse-checkout init`,
+  introduced in that version).
+
+  When checkout attempts to initialise the git CommandManager and git is present on the
+  runner but too old to satisfy the sparse-checkout requirement, the action's
+  `getGitCommandManager` function throws an error. However, this error is caught in a
+  broad try/catch block:
+
+    } catch (err) {
+      // Git is required for LFS
+      if (settings.lfs) { throw err }
+      // otherwise: silently continue without git
+    }
+
+  Because `lfs` is not enabled, the error is swallowed without being logged to the
+  workflow output. Checkout falls back to downloading the repository as a ZIP archive
+  via the GitHub REST API and extracts it into the workspace.
+
+  The result is a **full clone** of the repository (subject to `fetch-depth`), not a
+  sparse checkout. All files are present in the workspace instead of only the requested
+  sparse paths. Workflows relying on sparse checkout to reduce disk usage or build time
+  proceed with the full repository content, potentially causing subtle downstream failures
+  (out-of-disk, dependency version mismatches, unexpected files in build artefacts) with
+  no indication that sparse-checkout was skipped.
+
+  This primarily affects **self-hosted runners** where a locally installed git binary is
+  older than 2.28 (e.g., git 2.17 shipped with Ubuntu 18.04, or git 2.23 on Amazon Linux
+  running in an older container). GitHub-hosted runners ship git 2.43+ and are not affected.
+
+  Reported in actions/checkout#2435 (May 2026).
+fix: |
+  **Step 1: Identify the failure.**
+  Add a step to print the git version before checkout:
+    - run: git --version
+
+  If the version is below 2.28, that is the root cause of the silent fallback.
+
+  **Step 2: Upgrade git on self-hosted runners.**
+  Install a modern git version (2.28+) on the runner. For Ubuntu:
+    sudo add-apt-repository ppa:git-core/ppa
+    sudo apt-get update && sudo apt-get install -y git
+
+  **Step 3: Until git is upgraded, disable sparse-checkout.**
+  Remove or guard the `sparse-checkout` input to avoid the silent fallback:
+    sparse-checkout: ''
+
+  **Alternative: require a minimum git version in the workflow.**
+  Fail fast with an explicit error rather than a silent fallback by checking the version
+  before the checkout step.
+fix_code:
+  - language: yaml
+    label: 'Add explicit git version gate before checkout with sparse-checkout'
+    code: |
+      - name: Verify git version supports sparse-checkout
+        run: |
+          GIT_VERSION=$(git --version | awk '{print $3}')
+          MIN_VERSION="2.28.0"
+          if [ "$(printf '%s\n' "$MIN_VERSION" "$GIT_VERSION" | sort -V | head -n1)" != "$MIN_VERSION" ]; then
+            echo "::error::git $GIT_VERSION is too old for sparse-checkout (requires >= 2.28)"
+            exit 1
+          fi
+
+      - uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            src/
+            tests/
+  - language: yaml
+    label: 'Upgrade git on Ubuntu self-hosted runner before checkout'
+    code: |
+      - name: Ensure git >= 2.28 for sparse-checkout support
+        run: |
+          sudo add-apt-repository -y ppa:git-core/ppa
+          sudo apt-get update -q
+          sudo apt-get install -y git
+          git --version
+
+      - uses: actions/checkout@v6
+        with:
+          sparse-checkout: |
+            src/
+prevention:
+  - 'Always confirm the git version on self-hosted runners meets the minimum requirements for checkout features you use; add a preflight check step if runners may have older git installs'
+  - 'Pin to a specific version of actions/checkout and audit the changelog when upgrading — the sparse-checkout silent fallback has existed across multiple major versions'
+  - 'If disk usage is a concern and sparse-checkout is required, add a post-checkout assertion that only the expected sparse paths exist, which will catch the REST API fallback'
+docs:
+  - url: 'https://github.com/actions/checkout/issues/2435'
+    label: 'actions/checkout#2435 — Errors from initializing gitCommandManager are silently ignored'
+  - url: 'https://github.com/actions/checkout#usage'
+    label: 'actions/checkout README — sparse-checkout input and requirements'
+  - url: 'https://git-scm.com/docs/git-sparse-checkout'
+    label: 'Git documentation — git-sparse-checkout (requires git 2.25+, cone mode 2.26+)'

package/errors/silent-failures/silent-failures-117.yml

@@ -0,0 +1,137 @@
+id: silent-failures-117
+title: 'if: always() runs steps even when the workflow is manually cancelled — use success() || failure() to respect cancellation'
+category: silent-failures
+severity: silent-failure
+tags:
+  - if-condition
+  - always
+  - cancelled
+  - cleanup
+  - notification
+  - status-check
+  - silent-failure
+patterns:
+  - regex: 'if:\s*always\(\)'
+    flags: 'i'
+  - regex: 'if:\s*\$\{\{\s*always\(\)\s*\}\}'
+    flags: 'i'
+error_messages:
+  - '(no error emitted — steps run unexpectedly during workflow cancellation)'
+root_cause: |
+  Developers commonly add `if: always()` to steps or jobs that should run even when
+  a previous step fails — for example, uploading test reports after a failed test run,
+  or sending failure notifications.
+
+  The silent failure is that `always()` evaluates to `true` in ALL cases including
+  when the workflow is manually cancelled. When a user or a concurrency group cancellation
+  triggers, any step or job with `if: always()` still executes. This is often unintended:
+  the developer expected "run on failure" not "run even when someone cancels".
+
+  GitHub Actions documentation explicitly warns about this:
+    "Consider using if: !cancelled() if you want the step or job to continue
+     executing when the current run is cancelled. [...] Using always() is not
+     recommended as it causes a step to run when a workflow is cancelled, which
+     can result in unintended behavior."
+
+  Common scenarios where this causes problems:
+  - Test report upload step runs when a PR author cancels a run, unnecessarily consuming
+    runner minutes and potentially posting partial results to a PR check.
+  - Slack/PagerDuty notification fires for a manual cancellation, producing false alerts.
+  - Deploy rollback job runs during a cancellation of a non-deployment workflow, triggering
+    rollback unexpectedly.
+  - Cleanup job executes with only partial data because the workflow was cut short.
+
+  The correct alternative for "run when success OR failure, but NOT when cancelled" is:
+    if: success() || failure()
+  or equivalently:
+    if: ${{ !cancelled() }}
+
+  Source: Stack Overflow q/58858429 (415 upvotes, 327k views), GitHub Docs always() warning,
+  test-summary/action#51 community discussion (Jan 2025).
+fix: |
+  Replace `if: always()` with `if: success() || failure()` for steps and jobs that
+  should run on success or failure but NOT when the workflow is cancelled.
+
+  Use `if: always()` only when you explicitly want the step to run even during
+  cancellation — for example, an emergency teardown that must run regardless.
+
+  Three options depending on intent:
+
+  1. Run on success or failure (skip on cancel): `if: success() || failure()`
+  2. Run on any non-success outcome (skip on cancel): `if: failure()`
+  3. Run always including on cancel (current behaviour): `if: always()`
+
+  GitHub also documents `if: ${{ !cancelled() }}` as equivalent to option 1 in
+  most contexts.
+fix_code:
+  - language: yaml
+    label: 'Before: if: always() fires even on manual cancellation'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - run: pytest --junitxml=results.xml
+
+            - name: Upload test results
+              if: always()          # fires even when the job is cancelled mid-run
+              uses: actions/upload-artifact@v4
+              with:
+                name: test-results
+                path: results.xml
+  - language: yaml
+    label: 'After: if: success() || failure() respects cancellation'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - run: pytest --junitxml=results.xml
+
+            - name: Upload test results
+              if: success() || failure()   # runs on pass or fail; skips on cancel
+              uses: actions/upload-artifact@v4
+              with:
+                name: test-results
+                path: results.xml
+  - language: yaml
+    label: 'Notification job: skip Slack alert on cancellation'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: make build
+
+        notify:
+          needs: build
+          # success() || failure() fires on build success or failure, not on cancel
+          if: success() || failure()
+          runs-on: ubuntu-latest
+          steps:
+            - name: Notify Slack
+              run: |
+                echo "Build result: ${{ needs.build.result }}"
+                # Sends alert only on success or failure — not on manual cancel
+
+        # Only use always() when you MUST run on cancellation too:
+        emergency-cleanup:
+          needs: build
+          if: always()       # intentional: must clean up even if cancelled
+          runs-on: ubuntu-latest
+          timeout-minutes: 4 # stay under the 5-min forced-kill window
+          steps:
+            - run: ./cleanup.sh
+prevention:
+  - 'Default to `if: success() || failure()` for upload, notification, and cleanup steps — reserve `if: always()` only for teardown steps that truly must run on cancellation'
+  - 'Remember: `always()` is not "run when failure"; it is "run even when cancelled" — the distinction matters for notification jobs'
+  - 'GitHub docs recommend `if: ${{ !cancelled() }}` as an alternative to `if: success() || failure()` for the same effect'
+  - 'Combine `if: always()` with `timeout-minutes:` on any job that runs after cancellation; GitHub force-kills all jobs after 5 minutes of the cancellation signal'
+  - 'Run a quick cancellation test: manually cancel the workflow and verify whether notification steps fire unexpectedly'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#always'
+    label: 'GitHub Docs: always() status check function — cancellation warning'
+  - url: 'https://stackoverflow.com/questions/58858429/how-to-run-a-github-actions-step-even-if-the-previous-step-fails-while-still-failing-the-job'
+    label: 'Stack Overflow 58858429: Run step on failure while still failing the job (415 votes)'
+  - url: 'https://github.com/test-summary/action/issues/51'
+    label: 'test-summary/action#51: Use success() || failure() instead of always() to prevent running on cancel'

package/errors/silent-failures/silent-failures-118.yml

@@ -0,0 +1,156 @@
+id: silent-failures-118
+title: 'Reusable workflow jobs.<name>.result is always empty string in on.workflow_call.outputs value'
+category: silent-failures
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - workflow_call
+  - outputs
+  - jobs-result
+  - empty-string
+  - silent-failure
+  - job-outcome
+patterns:
+  - regex: 'value:\s*\$\{\{\s*jobs\.[a-zA-Z0-9_-]+\.result\s*\}\}'
+    flags: 'i'
+  - regex: 'needs\.[a-zA-Z0-9_-]+\.outputs\.[a-zA-Z0-9_-]+.*result'
+    flags: 'i'
+error_messages:
+  - '(no error emitted — needs.<job>.outputs.<name> resolves to empty string in the caller)'
+root_cause: |
+  GitHub Actions documentation states that the `jobs` context is available in
+  reusable workflows and includes `jobs.<job_id>.result` — the job conclusion value
+  ("success", "failure", "cancelled", or "skipped"). Developers use this to expose job
+  outcomes to calling workflows via `on.workflow_call.outputs`.
+
+  However, `jobs.<job_id>.result` does NOT work when used in the `value:` expression of
+  `on.workflow_call.outputs`. It always resolves to an empty string ("") in the caller's
+  `needs.<called_job>.outputs.<name>`.
+
+  This is distinct from the two-level output declaration issue (sf-060) where developers
+  forget to declare outputs at the workflow_call level. Here the developer correctly
+  declares both levels, but uses `jobs.<name>.result` (the job outcome) instead of
+  `jobs.<name>.outputs.<step-output>` (a custom output). The `.result` property is
+  simply not available via this mechanism.
+
+  Workarounds discovered by the community:
+  1. Explicitly capture the outcome as a step output and then chain it through job outputs:
+       steps:
+         - id: capture
+           run: echo "result=${{ job.status }}" >> "$GITHUB_OUTPUT"
+       outputs:
+         result: ${{ steps.capture.outputs.result }}
+  2. Use `fromJSON(toJSON(jobs.build)).result` — this works because it forces the
+     expression evaluator to serialise and deserialise the jobs context object, which
+     happens to populate the result at evaluation time. This is an accidental workaround
+     and not guaranteed to remain stable.
+
+  The root cause is that the `jobs.<job_id>.result` property in the workflow_call outputs
+  `value:` expression is evaluated before job conclusions are fully committed to the
+  expression context, unlike `jobs.<job_id>.outputs.<name>` which goes through a different
+  code path.
+
+  Source: actions/runner#2495 (open since 2023, multiple upvotes),
+  actions/runner#3087 (Cannot access jobs.<id>.result from on.workflow_call.outputs..value).
+fix: |
+  Do NOT use `value: ${{ jobs.<name>.result }}` in on.workflow_call.outputs — it will
+  always be empty in the caller.
+
+  **Option 1 (recommended): Capture outcome via a step output.**
+  Add a final step that writes `job.status` to GITHUB_OUTPUT, then chain it up:
+    step output → job output → workflow_call output
+
+  **Option 2: Use fromJSON(toJSON(jobs.<name>)).result workaround.**
+  The fromJSON/toJSON wrapper forces the jobs context to be serialised at evaluation
+  time, which makes .result available. This is a workaround — prefer option 1.
+
+  **Option 3: Control caller behavior via job success/failure instead of reading result.**
+  If you only need to run downstream caller jobs conditionally based on the reusable
+  workflow succeeding or failing, use `if: needs.<job>.result == 'success'` — the
+  `needs.<job>.result` in the CALLER is always correct and does NOT need to go through
+  workflow_call outputs.
+fix_code:
+  - language: yaml
+    label: 'Broken: value: ${{ jobs.build.result }} is always empty in caller'
+    code: |
+      # .github/workflows/reusable.yml — BROKEN pattern
+      on:
+        workflow_call:
+          outputs:
+            build-result:
+              description: 'Job outcome of the build job'
+              value: ${{ jobs.build.result }}   # always empty string in caller
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: make build
+  - language: yaml
+    label: 'Fixed: capture outcome via step output and chain it through job outputs'
+    code: |
+      # .github/workflows/reusable.yml — CORRECT pattern
+      on:
+        workflow_call:
+          outputs:
+            build-result:
+              description: 'Job outcome of the build job'
+              value: ${{ jobs.build.outputs.result }}   # works correctly
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            result: ${{ steps.capture.outputs.result }}
+          steps:
+            - run: make build
+
+            - id: capture
+              if: always()
+              shell: bash
+              run: echo "result=${{ job.status }}" >> "$GITHUB_OUTPUT"
+  - language: yaml
+    label: 'Alternative workaround: fromJSON(toJSON(jobs.build)).result (fragile, prefer option 1)'
+    code: |
+      # .github/workflows/reusable.yml — accidental workaround (not recommended)
+      on:
+        workflow_call:
+          outputs:
+            build-result:
+              value: ${{ fromJSON(toJSON(jobs.build)).result }}
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: make build
+  - language: yaml
+    label: 'Caller: reading needs.<job>.result directly works and does NOT need workflow_call outputs'
+    code: |
+      # .github/workflows/caller.yml
+      # needs.<job>.result in the CALLER is always correct — no need to pass it through outputs
+      jobs:
+        call-build:
+          uses: ./.github/workflows/reusable.yml
+
+        deploy:
+          needs: call-build
+          # This works correctly — reads the reusable workflow conclusion directly
+          if: needs.call-build.result == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./deploy.sh
+prevention:
+  - 'Never use `value: ${{ jobs.<name>.result }}` in workflow_call outputs — capture it as a step output first'
+  - 'If you only need to gate downstream caller jobs on reusable workflow success/failure, use `needs.<job>.result` in the caller directly — it works without going through workflow_call outputs'
+  - 'Test output values by printing them in the caller with `run: echo "${{ needs.<job>.outputs.<name> }}"` before relying on them in logic'
+  - 'The `fromJSON(toJSON(...)).result` workaround works today but is fragile — prefer the step-output capture pattern'
+docs:
+  - url: 'https://github.com/actions/runner/issues/2495'
+    label: 'actions/runner#2495: Reusable workflow does not output individual job result'
+  - url: 'https://github.com/actions/runner/issues/3087'
+    label: 'actions/runner#3087: Cannot access jobs.<id>.result from on.workflow_call.outputs..value'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onworkflow_calloutputs'
+    label: 'GitHub Docs: on.workflow_call.outputs syntax reference'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#jobs-context'
+    label: 'GitHub Docs: jobs context (available only in reusable workflows)'