@htekdev/actions-debugger 1.0.0 → 1.0.1

package/errors/caching-artifacts/cache-miss.yml

@@ -1,56 +1,56 @@
-id: caching-artifacts-001
-title: "Cache Miss Despite Recent Save"
-category: caching-artifacts
-severity: warning
-tags:
-  - cache
-  - artifacts
-  - restore-keys
-  - branch-scope
-  - performance
-patterns:
-  - regex: "Cache not found for input keys: .*"
-    flags: "i"
-  - regex: "Failed to restore: .*"
-    flags: "i"
-  - regex: "Received 429 response while trying to reserve cache"
-    flags: "i"
-error_messages:
-  - "Cache not found for input keys"
-  - "Received 429 response while trying to reserve cache"
-root_cause: |
-  GitHub Actions caches are scoped by key, version, and branch. A cache saved on one branch
-  is not always visible from another branch, and a small key mismatch can force a full miss.
-  High-volume repositories can also hit cache service throttling, which makes cache restore
-  or save behavior look flaky.
-
-  This is especially confusing when a previous run clearly saved a cache but the next run
-  still reports a miss.
-fix: |
-  Design cache keys intentionally, add `restore-keys` for partial matches, and understand the
-  branch visibility rules. Prime important caches on the default branch and avoid creating an
-  overly specific key for data that should be shared more broadly.
-fix_code:
-  - language: yaml
-    label: "Use restore keys and stable cache key prefixes"
-    code: |
-      - uses: actions/cache@v4
-        with:
-          path: |
-            ~/.npm
-            node_modules
-          key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}
-          restore-keys: |
-            ${{ runner.os }}-npm-
-prevention:
-  - "Keep cache keys stable enough to be reusable, but specific enough to avoid stale restores."
-  - "Use `restore-keys` for partial fallback instead of a single exact key."
-  - "Prime caches on the default branch for the widest reuse."
-docs:
-  - url: "https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows"
-    label: "Caching dependencies to speed up workflows"
-  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions"
-    label: "Workflow syntax for GitHub Actions"
-source:
-  article: "https://htek.dev/articles/github-actions-debugging-guide"
-  section: "Cache misses despite recent saves"
+id: caching-artifacts-001
+title: "Cache Miss Despite Recent Save"
+category: caching-artifacts
+severity: warning
+tags:
+  - cache
+  - artifacts
+  - restore-keys
+  - branch-scope
+  - performance
+patterns:
+  - regex: "Cache not found for input keys: .*"
+    flags: "i"
+  - regex: "Failed to restore: .*"
+    flags: "i"
+  - regex: "Received 429 response while trying to reserve cache"
+    flags: "i"
+error_messages:
+  - "Cache not found for input keys"
+  - "Received 429 response while trying to reserve cache"
+root_cause: |
+  GitHub Actions caches are scoped by key, version, and branch. A cache saved on one branch
+  is not always visible from another branch, and a small key mismatch can force a full miss.
+  High-volume repositories can also hit cache service throttling, which makes cache restore
+  or save behavior look flaky.
+
+  This is especially confusing when a previous run clearly saved a cache but the next run
+  still reports a miss.
+fix: |
+  Design cache keys intentionally, add `restore-keys` for partial matches, and understand the
+  branch visibility rules. Prime important caches on the default branch and avoid creating an
+  overly specific key for data that should be shared more broadly.
+fix_code:
+  - language: yaml
+    label: "Use restore keys and stable cache key prefixes"
+    code: |
+      - uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            node_modules
+          key: ${{ runner.os }}-npm-${{ hashFiles('package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-npm-
+prevention:
+  - "Keep cache keys stable enough to be reusable, but specific enough to avoid stale restores."
+  - "Use `restore-keys` for partial fallback instead of a single exact key."
+  - "Prime caches on the default branch for the widest reuse."
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows"
+    label: "Caching dependencies to speed up workflows"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions"
+    label: "Workflow syntax for GitHub Actions"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Cache misses despite recent saves"

package/errors/caching-artifacts/cache-save-cancelled-job.yml

@@ -0,0 +1,82 @@
+id: caching-artifacts-007
+title: "actions/cache Post-Save Step Skipped When Job Is Cancelled Mid-Run"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - cancellation
+  - save
+  - post-step
+  - cache-miss
+  - actions/cache
+patterns:
+  - regex: "Post job cleanup"
+    flags: "i"
+  - regex: "Cache save skipped"
+    flags: "i"
+  - regex: "Cache service responded with 503"
+    flags: "i"
+  - regex: "cache.*not saved.*cancelled"
+    flags: "i"
+error_messages:
+  - "Cache save skipped due to job cancellation."
+  - "Post job cleanup: Cache was not saved as the job was cancelled."
+root_cause: |
+  `actions/cache` saves the cache in a **post-job step** that runs after all workflow
+  steps complete. When a job is cancelled (via the UI, API, `concurrency: cancel-in-progress`,
+  or reaching the job timeout), the post-step save is skipped — GitHub does not allow
+  post-steps to run when the job is cancelled.
+
+  This causes a **cold cache** on the next run: a build that took 10 minutes to complete
+  its install phase is cancelled just before the cache save fires, so the next run starts
+  from scratch again. In high-frequency CI environments with auto-cancel enabled, this can
+  mean most runs never benefit from caching.
+fix: |
+  Use `actions/cache/save@v4` as an explicit step instead of relying on the post-job
+  hook. Save the cache immediately after the slow step completes rather than waiting for
+  job end. For `cancel-in-progress` workflows, save the cache before the cancellable steps.
+fix_code:
+  - language: yaml
+    label: "WRONG — cache save is a post-job hook, skipped on cancellation"
+    code: |
+      steps:
+        - uses: actions/cache@v4
+          with:
+            path: node_modules
+            key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+
+        - run: npm ci              # slow — if job cancelled here, cache never saves
+        - run: npm run build
+  - language: yaml
+    label: "CORRECT — explicit save step that always runs"
+    code: |
+      steps:
+        - name: Restore cache
+          id: cache
+          uses: actions/cache/restore@v4
+          with:
+            path: node_modules
+            key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+
+        - name: Install dependencies
+          if: steps.cache.outputs.cache-hit != 'true'
+          run: npm ci
+
+        - name: Save cache immediately after install
+          if: steps.cache.outputs.cache-hit != 'true'
+          uses: actions/cache/save@v4
+          with:
+            path: node_modules
+            key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+
+        # If job is cancelled after this point, cache is already saved
+        - run: npm run build
+prevention:
+  - "Use `actions/cache/restore` + `actions/cache/save` separately so cache saves happen as explicit steps, not post-hooks."
+  - "Save the cache immediately after the slow install/build step, before the steps most likely to be cancelled."
+  - "For very long builds, consider saving a partial cache at key checkpoints."
+docs:
+  - url: "https://github.com/actions/cache/blob/main/save/README.md"
+    label: "actions/cache/save — explicit save action"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows"
+    label: "Caching dependencies to speed up workflows"

package/errors/caching-artifacts/cache-v3-to-v4-breaking-changes.yml

@@ -0,0 +1,95 @@
+id: caching-artifacts-009
+title: "actions/cache v3 to v4 Breaking Changes — save-always and Path Handling"
+category: caching-artifacts
+severity: error
+tags:
+  - actions/cache
+  - v3
+  - v4
+  - migration
+  - save-always
+  - breaking-change
+  - upgrade
+patterns:
+  - regex: "Cache action is too slow.*v4"
+    flags: "i"
+  - regex: "save-always.*not a valid input"
+    flags: "i"
+  - regex: "Path .* does not exist"
+    flags: "i"
+  - regex: "Input 'enableCrossOsArchive' is deprecated"
+    flags: "i"
+error_messages:
+  - "Unexpected input(s) 'save-always', valid inputs are ['path', 'key', 'restore-keys', 'upload-chunk-size', 'enableCrossOsArchive', 'fail-on-cache-miss', 'lookup-only']"
+  - "Path /home/runner/.npm does not exist, not saving cache."
+root_cause: |
+  `actions/cache@v4` introduced several breaking changes from v3:
+
+  1. **`save-always` input removed** — v3's `save-always: true` (save even on failure) was
+     removed in v4. The replacement is the split `actions/cache/restore` + `actions/cache/save`
+     pattern with `if: always()` on the save step.
+
+  2. **Missing path no longer silently skipped** — v4 by default fails (or warns) when the
+     specified cache path does not exist at save time. In v3 this was a silent no-op.
+
+  3. **Stricter ZSTD compression** — v4 switched to ZSTD compression. Caches saved by v3
+     are incompatible with v4 and will cause a cache miss on first run after migration.
+
+  4. **`enableCrossOsArchive` default changed** — in v4 cross-OS cache sharing requires
+     explicit opt-in; v3 defaults were permissive.
+fix: |
+  When upgrading from v3 to v4, replace `save-always: true` with the explicit
+  restore+save pattern, add existence checks for cache paths, and expect a one-time
+  cache miss after migrating (old v3 cache entries are incompatible with v4).
+fix_code:
+  - language: yaml
+    label: "WRONG — v3 pattern with save-always (breaks in v4)"
+    code: |
+      steps:
+        - uses: actions/cache@v4     # upgraded from v3 but kept v3 inputs
+          with:
+            path: ~/.npm
+            key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+            save-always: true        # ERROR: not a valid input in v4
+  - language: yaml
+    label: "CORRECT — v4 pattern with explicit save on failure"
+    code: |
+      steps:
+        - name: Restore npm cache
+          id: cache
+          uses: actions/cache/restore@v4
+          with:
+            path: ~/.npm
+            key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+            restore-keys: |
+              ${{ runner.os }}-npm-
+
+        - run: npm ci
+
+        - name: Save npm cache (runs even on failure)
+          if: always() && steps.cache.outputs.cache-hit != 'true'
+          uses: actions/cache/save@v4
+          with:
+            path: ~/.npm
+            key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+  - language: yaml
+    label: "CORRECT — simple v4 usage without save-always"
+    code: |
+      steps:
+        - uses: actions/cache@v4
+          with:
+            path: ~/.npm
+            key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+            restore-keys: ${{ runner.os }}-npm-
+            # No save-always — cache saves on successful job completion only
+prevention:
+  - "Expect one cache miss when migrating from v3 to v4 — v3 and v4 cache entries are incompatible."
+  - "Replace `save-always: true` with the `actions/cache/restore` + `actions/cache/save` split pattern."
+  - "Test cache behavior in a draft PR before merging a v3→v4 migration to main."
+docs:
+  - url: "https://github.com/actions/cache/blob/main/RELEASES.md"
+    label: "actions/cache release notes (v3→v4 changes)"
+  - url: "https://github.com/actions/cache/blob/main/tips-and-workarounds.md"
+    label: "actions/cache tips and workarounds"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows"
+    label: "Caching dependencies to speed up workflows"

package/errors/caching-artifacts/cross-repo-artifacts-not-supported.yml

@@ -0,0 +1,102 @@
+id: caching-artifacts-008
+title: "Artifacts Are Repository-Scoped — Cross-Repo Download Not Supported"
+category: caching-artifacts
+severity: error
+tags:
+  - artifacts
+  - cross-repo
+  - download
+  - scoping
+  - workflow-run
+  - actions/download-artifact
+patterns:
+  - regex: "Unable to find any artifacts for the associated workflow"
+    flags: "i"
+  - regex: "No artifacts found for"
+    flags: "i"
+  - regex: "Artifact not found.*repository"
+    flags: "i"
+error_messages:
+  - "Unable to find any artifacts for the associated workflow run"
+  - "Error: No artifacts found for workflow run 1234567890"
+  - "HttpError: Not Found — artifacts are scoped to the repository that created them"
+root_cause: |
+  GitHub Actions artifacts are **repository-scoped**. A workflow in `org/repo-a` cannot
+  download artifacts produced by a workflow in `org/repo-b` using `actions/download-artifact`,
+  even if both repos are in the same organization and the caller has read access to both.
+
+  The `actions/download-artifact` action only fetches artifacts from the **current workflow
+  run**. To download artifacts from a different workflow run (same repo), you must use the
+  GitHub Actions REST API with a PAT or GitHub App token. Cross-repository artifact sharing
+  is entirely unsupported natively and requires external storage (S3, Azure Blob, GitHub
+  Releases, GitHub Packages) as an intermediary.
+
+  This surprises teams building release pipelines where a build repo produces artifacts
+  that a deploy repo needs to consume.
+fix: |
+  Use an external storage layer (GitHub Releases, GitHub Packages, S3, Azure Blob) for
+  cross-repo artifact sharing. Within the same repo, use the GitHub API with a PAT to
+  download artifacts from a different workflow run.
+fix_code:
+  - language: yaml
+    label: "WRONG — attempting cross-repo artifact download (always fails)"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            # This ONLY works for artifacts from THIS workflow run
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-output
+                # There is no 'repository' input — cross-repo not supported
+  - language: yaml
+    label: "CORRECT option 1 — upload to GitHub Releases for cross-repo sharing"
+    code: |
+      # In build repo (org/build-repo):
+      jobs:
+        build:
+          steps:
+            - name: Build
+              run: npm run build
+
+            - name: Upload to GitHub Release
+              uses: softprops/action-gh-release@v2
+              with:
+                files: dist/**
+                token: ${{ secrets.GITHUB_TOKEN }}
+
+      # In deploy repo (org/deploy-repo):
+      jobs:
+        deploy:
+          steps:
+            - name: Download from release
+              run: |
+                gh release download v1.0.0 --repo org/build-repo --pattern "*.tar.gz"
+              env:
+                GH_TOKEN: ${{ secrets.CROSS_REPO_PAT }}
+  - language: yaml
+    label: "CORRECT option 2 — GitHub API to download artifact from same repo, different run"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Download artifact from specific workflow run
+              uses: dawidd6/action-download-artifact@v6
+              with:
+                github_token: ${{ secrets.GITHUB_TOKEN }}
+                workflow: build.yml
+                run_id: ${{ github.event.workflow_run.id }}
+                name: build-output
+prevention:
+  - "Use GitHub Releases or GitHub Packages (Container Registry, npm registry) for artifacts that must cross repository boundaries."
+  - "Design pipelines so build and deploy are in the same repo if artifact passing is needed."
+  - "Document artifact storage architecture explicitly in repo README — don't let teams discover the limitation at deploy time."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow"
+    label: "Storing and sharing data from a workflow"
+  - url: "https://docs.github.com/en/rest/actions/artifacts"
+    label: "GitHub REST API — Artifacts"
+  - url: "https://github.com/dawidd6/action-download-artifact"
+    label: "dawidd6/action-download-artifact (cross-run downloads)"

package/errors/caching-artifacts/upload-artifact-no-files-found.yml

@@ -0,0 +1,92 @@
+id: caching-artifacts-005
+title: "upload-artifact: No Files Found — Artifact Silently Not Uploaded"
+category: caching-artifacts
+severity: warning
+tags:
+  - upload-artifact
+  - paths
+  - working-directory
+  - if-no-files-found
+  - silent-failure
+patterns:
+  - regex: "No files were found with the provided path[^.]*\\."
+    flags: "i"
+  - regex: "No artifacts will be uploaded"
+    flags: "i"
+  - regex: "ENOENT: no such file or directory.*lstat"
+    flags: "i"
+error_messages:
+  - "No files were found with the provided path: dist. No artifacts will be uploaded."
+  - "Warning: No files were found with the provided path"
+  - "Error: ENOENT: no such file or directory, lstat '/home/runner/work/..."
+root_cause: |
+  The `actions/upload-artifact` action resolves `path:` values relative to the workspace root
+  (`$GITHUB_WORKSPACE`, typically `/home/runner/work/{repo}/{repo}`). The five most common
+  failure causes:
+
+  1. Build step outputs to a different directory than expected (e.g., `./build` vs `dist/`).
+  2. A prior step uses `working-directory:` which does not affect how upload-artifact resolves
+     its `path:` — the path must still be relative to `$GITHUB_WORKSPACE`, not to that step's CWD.
+  3. The build step failed silently (non-zero exit code masked by `continue-on-error: true` or
+     a multi-command run where the failure was not the last command) so the output directory was
+     never created.
+  4. A wildcard `path:` glob matches nothing — the directory exists but no files match the pattern.
+  5. The artifact `path:` references a file or directory whose name includes a space or special
+     character that was not quoted correctly.
+
+  By default, `upload-artifact` exits with a WARNING (not an error) when no files match. The
+  job succeeds and the missing artifact is only discovered downstream when a dependent step or
+  job tries to download it — often failing with a cryptic "artifact not found" error.
+fix: |
+  Set `if-no-files-found: error` to turn the silent warning into an immediate job failure.
+  Add a debug step before the upload to confirm the exact path that was actually written.
+fix_code:
+  - language: yaml
+    label: "Add if-no-files-found: error and a debug step to verify the path"
+    code: |
+      steps:
+        - name: Build
+          run: npm run build
+          # outputs to ./dist by default
+
+        - name: Debug — verify build output exists
+          if: always()
+          run: |
+            echo "=== workspace contents ==="
+            ls -la
+            echo "=== dist/ contents ==="
+            ls -la dist/ || echo "dist/ does not exist"
+
+        - uses: actions/upload-artifact@v4
+          with:
+            name: dist-bundle
+            path: dist/
+            if-no-files-found: error   # fail immediately instead of silently skipping
+            retention-days: 7
+  - language: yaml
+    label: "Fix working-directory path mismatch"
+    code: |
+      steps:
+        - name: Build in subdirectory
+          working-directory: packages/app
+          run: npm run build
+          # outputs to packages/app/dist — NOT ./dist relative to workspace root
+
+        - uses: actions/upload-artifact@v4
+          with:
+            name: app-bundle
+            path: packages/app/dist/   # always relative to $GITHUB_WORKSPACE
+            if-no-files-found: error
+prevention:
+  - "Always set `if-no-files-found: error` — the default `warn` silently hides missing artifacts."
+  - "Add a debug `ls` or `find` step before upload-artifact when setting up a new workflow."
+  - "Remember that `path:` is always relative to `$GITHUB_WORKSPACE`, not to any step's `working-directory:`."
+  - "If a build can legitimately produce no files (e.g., no changed files), use `if-no-files-found: ignore` explicitly so the intent is clear."
+  - "Avoid masking build failures with `continue-on-error: true` on steps that produce upload artifacts."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow"
+    label: "Storing and sharing data from a workflow"
+  - url: "https://github.com/actions/upload-artifact#inputs"
+    label: "upload-artifact README — if-no-files-found input"
+  - url: "https://github.com/actions/upload-artifact/issues/232"
+    label: "actions/upload-artifact#232 — No files were found with the provided path"

package/errors/caching-artifacts/upload-artifact-v4-breaking.yml

@@ -1,67 +1,67 @@
-id: caching-artifacts-004
-title: "upload-artifact v3 → v4 Breaking Changes"
-category: caching-artifacts
-severity: error
-tags:
-  - artifacts
-  - upload-artifact
-  - download-artifact
-  - v4
-  - compatibility
-patterns:
-  - regex: "Artifact not found for name: .*"
-    flags: "i"
-  - regex: "Unable to find any artifacts for the associated workflow"
-    flags: "i"
-  - regex: "The requested artifact was not found"
-    flags: "i"
-error_messages:
-  - "Artifact not found for name: build-output"
-  - "Unable to find any artifacts for the associated workflow"
-  - "The requested artifact was not found"
-root_cause: |
-  The v4 artifact actions use a different backend and behavior than v3. Mixing
-  `actions/upload-artifact@v3` with `actions/download-artifact@v4` can produce confusing
-  artifact-not-found failures even when the earlier upload step seemed successful.
-
-  The safest rule is to keep upload and download artifact actions on the same major version,
-  and preferably migrate both sides to v4 together.
-fix: |
-  Upgrade both upload and download steps to v4 in the same workflow or workflow chain.
-  Re-test artifact names exactly as written, because name mismatches compound the version
-  mismatch problem.
-fix_code:
-  - language: yaml
-    label: "Use matching artifact action versions"
-    code: |
-      jobs:
-        build:
-          runs-on: ubuntu-latest
-          steps:
-            - uses: actions/checkout@v4
-            - run: npm run build
-            - uses: actions/upload-artifact@v4
-              with:
-                name: build-output
-                path: dist/
-
-        consume:
-          runs-on: ubuntu-latest
-          needs: build
-          steps:
-            - uses: actions/download-artifact@v4
-              with:
-                name: build-output
-                path: dist/
-prevention:
-  - "Upgrade upload and download artifact actions together, not one side at a time."
-  - "Keep artifact names consistent and explicit across jobs."
-  - "Retest cross-workflow artifact usage after action major-version upgrades."
-docs:
-  - url: "https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts"
-    label: "Store and share data with workflow artifacts"
-  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions"
-    label: "Workflow syntax for GitHub Actions"
-source:
-  article: "https://htek.dev/articles/github-actions-debugging-guide"
-  section: "Artifact v4 breaking changes"
+id: caching-artifacts-004
+title: "upload-artifact v3 → v4 Breaking Changes"
+category: caching-artifacts
+severity: error
+tags:
+  - artifacts
+  - upload-artifact
+  - download-artifact
+  - v4
+  - compatibility
+patterns:
+  - regex: "Artifact not found for name: .*"
+    flags: "i"
+  - regex: "Unable to find any artifacts for the associated workflow"
+    flags: "i"
+  - regex: "The requested artifact was not found"
+    flags: "i"
+error_messages:
+  - "Artifact not found for name: build-output"
+  - "Unable to find any artifacts for the associated workflow"
+  - "The requested artifact was not found"
+root_cause: |
+  The v4 artifact actions use a different backend and behavior than v3. Mixing
+  `actions/upload-artifact@v3` with `actions/download-artifact@v4` can produce confusing
+  artifact-not-found failures even when the earlier upload step seemed successful.
+
+  The safest rule is to keep upload and download artifact actions on the same major version,
+  and preferably migrate both sides to v4 together.
+fix: |
+  Upgrade both upload and download steps to v4 in the same workflow or workflow chain.
+  Re-test artifact names exactly as written, because name mismatches compound the version
+  mismatch problem.
+fix_code:
+  - language: yaml
+    label: "Use matching artifact action versions"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm run build
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-output
+                path: dist/
+
+        consume:
+          runs-on: ubuntu-latest
+          needs: build
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-output
+                path: dist/
+prevention:
+  - "Upgrade upload and download artifact actions together, not one side at a time."
+  - "Keep artifact names consistent and explicit across jobs."
+  - "Retest cross-workflow artifact usage after action major-version upgrades."
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/storing-workflow-data-as-artifacts"
+    label: "Store and share data with workflow artifacts"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions"
+    label: "Workflow syntax for GitHub Actions"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Artifact v4 breaking changes"