@htekdev/actions-debugger 1.0.23 → 1.0.24

package/errors/caching-artifacts/artifact-minimum-retention-one-day.yml

@@ -0,0 +1,153 @@
+id: caching-artifacts-024
+title: "Artifact Minimum Retention Is 1 Day — Cannot Set retention-days to 0 for Immediate Cleanup"
+category: caching-artifacts
+severity: limitation
+tags:
+  - artifact
+  - retention
+  - storage
+  - quota
+  - known-limit
+  - upload-artifact
+patterns:
+  - regex: "retention.days.*0|minimum.*retention.*1|retention.*must be between"
+    flags: "i"
+  - regex: "artifact.*storage.*quota|storage.*quota.*exceeded"
+    flags: "i"
+  - regex: "invalid.*retention|retention.*invalid"
+    flags: "i"
+error_messages:
+  - "Invalid retention days: must be between 1 and 90 inclusive"
+  - "Artifact storage quota has been exceeded"
+  - "retention-days must be between 1 and 90"
+  - "Artifact storage quota has been hit"
+root_cause: |
+  GitHub Actions enforces a minimum artifact retention period of 1 day. Setting
+  `retention-days: 0` in `actions/upload-artifact` causes a validation error. There is
+  no way to have artifacts automatically deleted at workflow completion — they persist for
+  at least 24 hours, consuming storage quota whether needed or not.
+
+  This limitation is tied to the backing storage system's minimum time-based retention
+  policy: "the minimum retention interval for a time-based retention policy is one day."
+
+  Practical consequences:
+  1. Workflows using artifacts for intra-workflow job-to-job data passing (build outputs,
+     test binaries, coverage reports) accumulate unwanted 1-day artifacts that count
+     against the repository's artifact storage quota.
+  2. Quota exhaustion can appear "sudden" because storage usage is recalculated every
+     6-12 hours — a burst of CI runs can drain the quota before the next recalculation.
+  3. The first signal of an impending quota problem is a failed upload: "Artifact storage
+     quota has been exceeded." There is no proactive warning in the UI.
+  4. Free/Pro plan organizations with small storage quotas (500 MB free tier) are
+     especially vulnerable when intermediate build artifacts accumulate across many runs.
+  5. Setting `retention-days: 1` (the minimum) still means 24 hours of quota usage per
+     artifact, which multiplies quickly in high-velocity repos with large CI matrices.
+
+  This is a known platform limitation with 301+ reactions on the tracking issue
+  (actions/upload-artifact#290, open since January 2022) and no committed resolution.
+
+  Source: actions/upload-artifact#290 (Allow retention-days: 0 for immediate cleanup)
+  Source: GitHub Docs — Artifact and log retention policies
+fix: |
+  There is no way to set `retention-days: 0`. Use these strategies to manage storage:
+
+  Mitigation 1 — Set retention-days: 1 (minimum possible):
+    Limits accumulation to 24 hours instead of the 90-day default. Use for all
+    intermediate build artifacts not needed for post-run debugging.
+
+  Mitigation 2 — Delete artifacts after use via workflow_run trigger:
+    Trigger a cleanup workflow via `workflow_run` that uses the GitHub REST API to
+    delete all artifacts from the completed run immediately after it finishes.
+
+  Mitigation 3 — Use GitHub Cache for intra-workflow job-to-job data:
+    Cache entries are auto-evicted after 7 days without access and when the 10 GB
+    repo cache limit is approached. For transient build outputs, cache is better than
+    artifacts because it has no minimum retention window.
+
+  Mitigation 4 — Use job outputs for small values:
+    For small job-to-job values (build numbers, git SHAs, test counts), use
+    `$GITHUB_OUTPUT` + `needs.<job>.outputs` instead of uploading an artifact entirely.
+
+  Mitigation 5 — Set a repository-level default retention policy:
+    In Settings → Actions → General, set a shorter default retention period (e.g., 7 days)
+    to limit the blast radius for workflows that forget to set `retention-days`.
+fix_code:
+  - language: yaml
+    label: "Set retention-days: 1 (minimum) for disposable intermediate artifacts"
+    code: |
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: always()   # Upload even on failure for debugging
+        with:
+          name: test-results-${{ matrix.os }}-${{ matrix.node }}
+          path: coverage/
+          retention-days: 1   # Minimum: deleted after ~24 hours
+
+  - language: yaml
+    label: "Post-run artifact cleanup via workflow_run trigger"
+    code: |
+      # .github/workflows/cleanup-artifacts.yml
+      name: Cleanup Run Artifacts
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+
+      jobs:
+        cleanup:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Delete all artifacts from completed run
+              run: |
+                ARTIFACT_IDS=$(gh api \
+                  "/repos/${{ github.repository }}/actions/runs/${{ github.event.workflow_run.id }}/artifacts" \
+                  --jq '.artifacts[].id')
+                for ID in $ARTIFACT_IDS; do
+                  gh api --method DELETE \
+                    "/repos/${{ github.repository }}/actions/artifacts/$ID"
+                  echo "Deleted artifact $ID"
+                done
+              env:
+                GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  - language: yaml
+    label: "Use cache instead of artifact for intra-workflow data (auto-evicted)"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: npm run build
+            - name: Cache build output for downstream jobs
+              uses: actions/cache/save@v4
+              with:
+                path: dist/
+                key: build-${{ github.run_id }}-${{ github.run_attempt }}
+                # Cache auto-evicts after 7 days or when repo 10 GB limit is approached
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - name: Restore build output
+              uses: actions/cache/restore@v4
+              with:
+                path: dist/
+                key: build-${{ github.run_id }}-${{ github.run_attempt }}
+            - name: Deploy
+              run: ./deploy.sh dist/
+prevention:
+  - "Always set `retention-days: 1` for intermediate build artifacts not needed after workflow completion."
+  - "Monitor artifact storage in Settings → Billing → Actions — spikes indicate uncleaned intermediate artifacts."
+  - "Set a repository-level default retention period in Settings → Actions → General to limit the default."
+  - "Use GitHub Cache for intra-workflow job-to-job data when persistence after the run is not required."
+  - "For matrix workflows, multiply the artifact size by matrix dimension count to estimate storage impact per run."
+docs:
+  - url: "https://github.com/actions/upload-artifact/issues/290"
+    label: "actions/upload-artifact#290: Allow retention-days: 0 (301 reactions, open since 2022)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-workflow-data-as-artifacts#configuring-a-custom-artifact-retention-period"
+    label: "GitHub Docs: Configuring a custom artifact retention period"
+  - url: "https://docs.github.com/en/actions/administering-github-actions/usage-limits-billing-and-administration#artifact-and-log-retention-policy"
+    label: "GitHub Docs: Artifact and log retention policy"

package/errors/caching-artifacts/cache-api-propagation-delay-post-save.yml

@@ -0,0 +1,128 @@
+id: caching-artifacts-023
+title: "Cache Saved Successfully But Unavailable for Restore for Several Minutes (API Propagation Lag)"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - actions/cache
+  - cache-miss
+  - propagation-delay
+  - api-lag
+  - restore
+  - gh-cache-list
+patterns:
+  - regex: "Cache not found for input keys"
+    flags: "i"
+  - regex: "Cache service responded with 404"
+    flags: "i"
+  - regex: "Saved successfully"
+    flags: "i"
+error_messages:
+  - "Cache not found for input keys"
+  - "Cache service responded with 404"
+  - "Received 0 of 0 (0.0 B), 0.0 MBs/sec"
+root_cause: |
+  There is a deliberate propagation delay between when the cache backend finishes
+  writing a cache entry (reporting "Saved successfully") and when that entry becomes
+  visible via the cache REST API or available for restore by subsequent jobs.
+
+  GitHub's cache service uses an eventually-consistent storage backend. After a cache
+  save completes, the cache metadata may not propagate to the query/restore API for
+  up to 4-5 minutes. During this window:
+
+  - `gh cache list` reports no cache for the key
+  - The Actions UI cache tab does not show the entry
+  - `actions/cache/restore@v5` reports a cache miss on the exact key
+
+  This is commonly hit when a workflow saves a cache in a "warm-up" job that is a
+  dependency for a fan-out matrix job. If the downstream jobs start before the cache
+  propagates, they all miss the cache and fall back to a cold install — often on a
+  schedule-triggered first-run-of-day workflow.
+
+  The issue was reported against `actions/cache` v4.2.2 with GitHub-hosted runners
+  and is not unique to any runner OS.
+fix: |
+  Design workflows to tolerate cache misses — always include a fallback install step
+  that runs when the cache is cold. Do not architect workflows where a cache miss
+  causes a hard failure.
+
+  For workflows that must read a cache from a previous job, add a `restore-keys`
+  fallback so a partial match is used while the exact key propagates:
+
+    restore-keys: |
+      build-deps-${{ runner.os }}-
+
+  If you need the exact cache entry, add a sleep + retry loop in the calling job
+  using `actions/cache/restore` wrapped with `nick-invision/retry`.
+
+  Alternatively, restructure the workflow so that cache-consuming jobs share the
+  same job context as the cache writer (using job outputs or artifacts) rather
+  than relying on cross-run cache availability.
+fix_code:
+  - language: yaml
+    label: "Always include restore-keys fallback to tolerate propagation lag"
+    code: |
+      steps:
+        - uses: actions/cache/restore@v5
+          id: cache-restore
+          with:
+            path: |
+              ~/.npm
+              node_modules
+            key: build-deps-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
+            restore-keys: |
+              build-deps-${{ runner.os }}-   # partial match handles lag window
+            fail-on-cache-miss: false        # never hard-fail on cache miss
+
+        - name: Install (runs on cache miss or during lag window)
+          if: steps.cache-restore.outputs.cache-hit != 'true'
+          run: npm ci
+  - language: yaml
+    label: "Warm-up job: save cache with explicit key confirmation before fan-out"
+    code: |
+      jobs:
+        warm-cache:
+          runs-on: ubuntu-latest
+          outputs:
+            cache-key: ${{ steps.cache-key.outputs.key }}
+          steps:
+            - uses: actions/checkout@v4
+            - id: cache-key
+              run: echo "key=build-deps-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}" >> "$GITHUB_OUTPUT"
+            - uses: actions/cache@v5
+              id: cache
+              with:
+                path: node_modules
+                key: ${{ steps.cache-key.outputs.key }}
+            - if: steps.cache.outputs.cache-hit != 'true'
+              run: npm ci
+            - if: steps.cache.outputs.cache-hit != 'true'
+              uses: actions/cache/save@v5
+              with:
+                path: node_modules
+                key: ${{ steps.cache-key.outputs.key }}
+
+        # Fan-out jobs include restore-keys fallback; tolerate lag window
+        build:
+          needs: warm-cache
+          strategy:
+            matrix:
+              target: [lint, test, typecheck]
+          steps:
+            - uses: actions/cache/restore@v5
+              with:
+                path: node_modules
+                key: ${{ needs.warm-cache.outputs.cache-key }}
+                restore-keys: build-deps-${{ runner.os }}-
+prevention:
+  - "Never hard-fail on cache miss (fail-on-cache-miss: false) — always include a fallback install."
+  - "Include restore-keys to allow partial matches during the propagation window."
+  - "Avoid architectures where downstream jobs strictly require a cache written in the same run's prior job."
+  - "Use job artifacts (upload-artifact/download-artifact) for dependencies that must be reliably shared within a run."
+  - "If using gh cache list to verify saves, wait at least 5 minutes before concluding a save failed."
+docs:
+  - url: "https://github.com/actions/cache/issues/1710"
+    label: "actions/cache#1710: Cache indexing lag / API propagation delay (15 reactions)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows"
+    label: "GitHub Docs: Caching dependencies to speed up workflows"
+  - url: "https://github.com/actions/cache/tree/main/restore"
+    label: "actions/cache/restore: restore-only action"

package/errors/caching-artifacts/cache-backend-internal-error-skipped.yml

@@ -0,0 +1,75 @@
+id: "caching-artifacts-026"
+title: "Cache backend internal error silently skips caching"
+category: "caching-artifacts"
+severity: "warning"
+tags:
+  - "cache"
+  - "backend"
+  - "internal-error"
+  - "github-status"
+  - "intermittent"
+  - "skipped"
+patterns:
+  - regex: "An internal error has occurred in cache backend"
+    flags: "i"
+  - regex: "The runner was not able to contact the cache service\\. Caching will be skipped"
+    flags: "i"
+error_messages:
+  - "Warning: An internal error has occurred in cache backend. Please check https://www.githubstatus.com/ for any ongoing issues in actions."
+  - "Warning: The runner was not able to contact the cache service. Caching will be skipped. If you are concerned about the results of this, you can contact GitHub support."
+root_cause: |
+  GitHub's distributed cache backend occasionally returns internal errors when the runner
+  attempts to save or restore a cache entry. This is a transient platform-side failure
+  unrelated to your workflow configuration or cache key. The runner catches this error
+  and emits a warning, then continues without failing the step or the job.
+
+  As a result, the cache is silently not saved (or not restored), and downstream steps
+  that depend on the cached state will see cache misses or stale data — but the overall
+  job still succeeds. This makes the problem invisible unless you inspect logs carefully.
+
+  These errors typically coincide with GitHub Actions infrastructure incidents. Checking
+  https://www.githubstatus.com/ during an active incident will confirm whether the issue
+  is platform-wide. The problem is not reproducible locally and usually self-resolves
+  within minutes to hours.
+fix: |
+  No workflow change can prevent this — it is a transient platform issue. Mitigations:
+
+  1. Check https://www.githubstatus.com/ when you see this error repeatedly.
+  2. Always verify that a cache restore actually produced the expected files rather than
+     relying solely on the cache-hit output (backend errors return empty cache-hit).
+  3. Make build steps tolerant of cold-cache starts: do not gate your pipeline on the
+     cache being present.
+  4. Use restore-keys as a fallback so a partial match reduces the blast radius.
+  5. For critical workflows, consider a self-hosted runner with a local file-system or
+     S3-backed cache to avoid the GitHub-hosted backend entirely.
+fix_code:
+  - language: yaml
+    label: "Always reinstall when cache-hit is not exactly 'true'"
+    code: |
+      - name: Cache npm dependencies
+        id: npm-cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-npm-
+
+      - name: Install dependencies
+        # cache-hit is empty string (not 'false') on backend errors — guard with != 'true'
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npm ci
+prevention:
+  - "Never assume the cache was saved — treat each cache entry as optional and ensure the build succeeds from scratch."
+  - "Use restore-keys to allow partial cache hits; a stale partial match is better than a full miss."
+  - "Add a post-restore verification step that checks for expected files rather than relying solely on cache-hit output."
+  - "Monitor https://www.githubstatus.com/ when you see repeated intermittent cache failures."
+docs:
+  - url: "https://github.com/actions/cache/issues/1611"
+    label: "actions/cache#1611 — Internal error in cache backend (39 reactions)"
+  - url: "https://github.com/actions/cache/issues/1621"
+    label: "actions/cache#1621 — Random restore failure (231 reactions)"
+  - url: "https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows"
+    label: "GitHub Docs — Caching dependencies to speed up workflows"
+  - url: "https://www.githubstatus.com/"
+    label: "GitHub Status — active incident tracker"

package/errors/caching-artifacts/cache-hit-step-id-case-sensitive-mismatch.yml

@@ -0,0 +1,95 @@
+id: caching-artifacts-022
+title: "cache-hit Output Always Empty Due to Case-Sensitive Step ID Mismatch"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - actions/cache
+  - cache-hit
+  - step-id
+  - case-sensitive
+  - conditional-install
+patterns:
+  - regex: 'steps\.[a-zA-Z0-9_-]+\.outputs\.cache-hit'
+    flags: "i"
+  - regex: 'cache-hit\s*!=\s*''true'''
+    flags: "i"
+  - regex: 'cache-hit\s*==\s*''true'''
+    flags: "i"
+error_messages:
+  - "Cache not found for input keys"
+  - "Post Cache: Saved successfully"
+root_cause: |
+  The `actions/cache` action sets a `cache-hit` output on the step that can be read
+  via `steps.<step-id>.outputs.cache-hit`. Step IDs in GitHub Actions are case-sensitive
+  and must exactly match between the `id:` field and the `steps.<id>.outputs.*` reference.
+
+  If the step ID in `id:` does not exactly match the ID in the `if:` condition — even
+  by a single character difference (hyphen vs underscore, camelCase vs kebab-case) —
+  the expression evaluates to an empty string, not `false`. No error or warning is emitted.
+
+  Common ID mismatches:
+  - `id: npm-cache` referenced as `steps.npmCache.outputs.cache-hit`
+  - `id: node_modules_cache` referenced as `steps.node-modules-cache.outputs.cache-hit`
+  - `id: Cache` referenced as `steps.cache.outputs.cache-hit` (capitalization)
+
+  The result is that the conditional install step (`if: steps.X.outputs.cache-hit !=
+  'true'`) ALWAYS runs (because empty string != 'true' is always true), wasting time
+  on every run even when the cache was a perfect hit.
+fix: |
+  Verify that the step `id:` field and all `steps.<id>.outputs.cache-hit` references
+  are identical character-for-character. Use lowercase kebab-case IDs to minimize
+  typo risk.
+
+  To debug: add a step that prints the cache-hit value before the conditional:
+    - run: echo "cache-hit=${{ steps.my-cache.outputs.cache-hit }}"
+
+  If the value is empty (not 'true' or 'false'), the ID is mismatched.
+fix_code:
+  - language: yaml
+    label: "Wrong: mismatched step IDs (cache-hit always empty)"
+    code: |
+      steps:
+        - name: Cache node_modules
+          uses: actions/cache@v4
+          id: npm-cache           # ID: npm-cache (hyphen)
+          with:
+            path: node_modules
+            key: npm-${{ hashFiles('package-lock.json') }}
+
+        - name: Install
+          # BUG: references npmCache (camelCase) — evaluates to empty string
+          if: steps.npmCache.outputs.cache-hit != 'true'
+          run: npm ci
+  - language: yaml
+    label: "Correct: matching step IDs (cache-hit works as expected)"
+    code: |
+      steps:
+        - name: Cache node_modules
+          uses: actions/cache@v4
+          id: npm-cache           # ID: npm-cache
+          with:
+            path: node_modules
+            key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
+            restore-keys: |
+              npm-${{ runner.os }}-
+
+        - name: Debug cache hit
+          run: echo "cache-hit=${{ steps.npm-cache.outputs.cache-hit }}"
+
+        - name: Install
+          # CORRECT: matches id exactly — cache-hit is 'true' or 'false'
+          if: steps.npm-cache.outputs.cache-hit != 'true'
+          run: npm ci
+prevention:
+  - "Always use identical lowercase kebab-case strings in id: and steps.<id>.outputs.cache-hit references."
+  - "Add a debug echo step to print the cache-hit value when troubleshooting unexpected installs."
+  - "Use actions/cache's save-always: true option to always save cache and remove the conditional entirely."
+  - "Lint workflows with actionlint — it catches step ID reference mismatches at the expression level."
+  - "Consider using the setup-* actions (setup-node, setup-python) which manage caching internally."
+docs:
+  - url: "https://github.com/actions/cache#outputs"
+    label: "actions/cache: Outputs (cache-hit)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#steps-context"
+    label: "GitHub Docs: steps context"
+  - url: "https://github.com/rhysd/actionlint"
+    label: "actionlint: Static checker for GitHub Actions workflow files"

package/errors/caching-artifacts/cache-save-post-step-skipped-on-failure.yml

@@ -0,0 +1,114 @@
+id: caching-artifacts-025
+title: "Cache Post-Step Skipped on Job Failure — Dependencies Not Saved"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - post-step
+  - job-failure
+  - save-always
+  - actions-cache
+  - dependency-caching
+patterns:
+  - regex: "Post job cleanup|Skipping.*save.*post-if|Cache not saved.*failure"
+    flags: "i"
+  - regex: "post-if.*success\\(\\)|cache.*post.*step.*skip"
+    flags: "i"
+error_messages:
+  - "Post job cleanup."
+  - "Cache not saved due to an early exit"
+  - "##[debug]Skipping: no reason to save state"
+root_cause: |
+  The actions/cache action hardcodes post-if: success() in its action.yml.
+  This means the post-step that actually saves the cache only runs when the
+  entire job succeeds. If any step after the cache restore step fails — a
+  build failure, a test failure, a linting error — the cache is silently
+  discarded and subsequent runs must re-download all dependencies from scratch.
+
+  This is particularly painful when an expensive dependency install succeeds
+  but a later step (npm run build, pytest, etc.) fails. The dependencies are
+  already installed and ready, but the cache save post-step is skipped because
+  job.status != success().
+
+  Original issue opened January 2020 (actions/cache#92, 500+ reactions).
+  Partially addressed in v3 via actions/cache/save sub-action and in v4 via
+  the save-always: true input.
+
+  The silent nature of the failure means developers often waste hours debugging
+  why subsequent runs are slow before realizing the cache was never saved.
+fix: |
+  Three approaches depending on the cache action version in use:
+
+  Option 1 — actions/cache@v4 with save-always: true (simplest):
+  Add save-always: true to the cache step. Note that steps between restore
+  and save must use continue-on-error: true, or the save step must be placed
+  immediately after the install step (before build/test steps that might fail).
+
+  Option 2 — Explicit save step with if: always() (v3+):
+  Split into actions/cache/restore and actions/cache/save steps. Place the
+  save step immediately after the install step and mark it with if: always()
+  so it runs regardless of subsequent step outcomes.
+
+  Option 3 — Job restructuring:
+  Move dependency installation into a dedicated setup job. The build/test job
+  depends on setup succeeding. Cache is always saved because the setup job
+  only contains the install step.
+fix_code:
+  - language: yaml
+    label: "actions/cache@v4 with save-always: true (simplest fix)"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - name: Restore cached dependencies
+          uses: actions/cache@v4
+          with:
+            path: ~/.npm
+            key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+            restore-keys: |
+              ${{ runner.os }}-npm-
+            save-always: true   # Save cache even if a later step fails
+        - name: Install dependencies
+          run: npm ci
+        - name: Build
+          run: npm run build   # Cache is saved even if this fails
+        - name: Test
+          run: npm test        # Cache is saved even if this fails
+  - language: yaml
+    label: "Explicit save step with if: always() (works with v3+)"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - name: Restore cached dependencies
+          id: cache-restore
+          uses: actions/cache/restore@v4
+          with:
+            path: ~/.npm
+            key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+            restore-keys: |
+              ${{ runner.os }}-npm-
+        - name: Install dependencies
+          run: npm ci
+        - name: Save cache (always, even on build/test failure)
+          if: always()
+          uses: actions/cache/save@v4
+          with:
+            path: ~/.npm
+            key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+        - name: Build
+          run: npm run build
+        - name: Test
+          run: npm test
+prevention:
+  - "Use save-always: true on actions/cache@v4 for dependency caches that should persist regardless of build outcome."
+  - "Split cache restore/save steps and use if: always() on the save step for fine-grained control."
+  - "Place the cache save step immediately after the install step — before build/test steps that might fail."
+  - "Add a post-install verification step (e.g., node --version, pip list) to confirm install succeeded before building."
+docs:
+  - url: "https://github.com/actions/cache/issues/92"
+    label: "actions/cache#92: Cache not saved on job failure (500+ reactions, opened 2020)"
+  - url: "https://github.com/actions/cache/tree/main/save#always-save-cache"
+    label: "actions/cache: always-save-cache documentation"
+  - url: "https://stackoverflow.com/questions/60491837/saving-cache-on-job-failure-in-github-actions"
+    label: "Stack Overflow: Saving cache on job failure in GitHub Actions (28 votes, 11K views)"
+  - url: "https://github.com/actions/cache?tab=readme-ov-file#v4"
+    label: "actions/cache v4 changelog: save-always parameter"

package/errors/concurrency-timing/deploy-pages-in-progress-deployment-wedged.yml

@@ -0,0 +1,70 @@
+id: concurrency-timing-020
+title: "deploy-pages deployment wedged after workflow cancellation — in progress forever"
+category: concurrency-timing
+severity: error
+tags:
+  - deploy-pages
+  - github-pages
+  - workflow-cancellation
+  - pages-deployment
+  - in-progress
+  - stuck
+patterns:
+  - regex: "Deployment request failed for .+ due to in progress deployment"
+    flags: "i"
+  - regex: "Please cancel .+ first or wait for it to complete"
+    flags: "i"
+  - regex: "Deployment cancellation failed"
+    flags: "i"
+error_messages:
+  - "Deployment request failed for 75152aed304ba9378fd527c226e9849ca39d5eda due to in progress deployment. Please cancel 4cb1cd27f0f1bceb7df2e4b7cb82785922dc978d first or wait for it to complete."
+  - "Error: Error: Request failed with status code 400"
+  - "Deployment cancellation failed Error: Request failed with status code 401"
+  - "Failed to create deployment (status: 400) with build version X. Responded with: Deployment request failed due to in progress deployment."
+root_cause: |
+  When an Actions workflow running actions/deploy-pages is cancelled mid-execution,
+  the action's post-step cleanup attempts to call the Pages deployment cancellation API.
+  If this cancellation API call fails (401/404, rate limit, or network timeout),
+  the Pages deployment remains permanently stuck in the "in_progress" state.
+  All subsequent deploy-pages runs fail with a 400 error because the GitHub Pages API
+  enforces a single active deployment per repo — new deployments are rejected until
+  the stuck one is explicitly cancelled or replaced.
+fix: |
+  To prevent the wedge: use a workflow-level concurrency group with cancel-in-progress: false
+  on your deploy job so cancellations cannot interrupt mid-deployment.
+
+  To recover from a stuck deployment: use the GitHub REST API to cancel or delete the
+  stuck Pages deployment. Find the stuck deployment ID from the error message, then
+  DELETE it via the deployments API.
+fix_code:
+  - language: yaml
+    label: "Prevent mid-deploy cancellation (recommended)"
+    code: |
+      jobs:
+        deploy:
+          concurrency:
+            group: pages-deploy
+            cancel-in-progress: false   # never cancel a running Pages deployment
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/deploy-pages@v4
+  - language: yaml
+    label: "Recover: cancel stuck deployment via GitHub API"
+    code: |
+      # Find stuck deployment ID from the error message, then:
+      # gh api repos/OWNER/REPO/deployments --jq '[.[] | select(.environment == "github-pages")]'
+      # gh api repos/OWNER/REPO/deployments/DEPLOYMENT_ID/statuses \
+      #   -X POST -f state=inactive
+      # gh api repos/OWNER/REPO/deployments/DEPLOYMENT_ID -X DELETE
+prevention:
+  - "Use concurrency: cancel-in-progress: false on all deploy jobs to prevent mid-deploy cancellation"
+  - "Avoid cancelling workflows while deploy-pages step is actively running"
+  - "Set up a separate deploy workflow triggered by workflow_run to decouple build from deploy"
+  - "Monitor the GitHub Pages deployment environment in your repo Settings for stuck states"
+docs:
+  - url: "https://github.com/actions/deploy-pages/issues/22"
+    label: "actions/deploy-pages#22: Workflow cancellation left pages deploy wedged"
+  - url: "https://docs.github.com/en/rest/deployments/deployments"
+    label: "GitHub REST API: Deployments (for manual cleanup)"
+  - url: "https://docs.github.com/en/actions/using-jobs/using-concurrency"
+    label: "GitHub Actions: Using concurrency"