@htekdev/actions-debugger 1.0.111 → 1.0.112

package/errors/runner-environment/runner-environment-181.yml

@@ -0,0 +1,114 @@
+id: runner-environment-181
+title: 'Self-hosted Windows runner steps stuck "Waiting for a runner to pick up this job..." mid-job after v2.321.0 auto-update'
+category: runner-environment
+severity: error
+tags:
+  - self-hosted
+  - windows
+  - runner-update
+  - stuck
+  - queued
+  - multi-step
+  - message-queue
+patterns:
+  - regex: 'Waiting for a runner to pick up this job'
+    flags: 'i'
+  - regex: 'Current runner version.*2\.32[1-9]|v2\.32[1-9]\.'
+    flags: 'i'
+error_messages:
+  - "Waiting for a runner to pick up this job..."
+root_cause: |
+  After the GitHub Actions runner auto-updated to v2.321.0 (released November 2024),
+  Windows self-hosted runners began exhibiting a specific failure mode in multi-step
+  jobs: the first step of a job executes successfully, but subsequent steps hang
+  indefinitely in a queued state showing "Waiting for a runner to pick up this job..."
+
+  Root cause: The v2.321.0 update introduced a regression in the Windows runner's
+  inter-step message queue session management. After completing a step, the runner
+  sends a completion signal to the GitHub broker but fails to maintain the job session
+  channel open for the next step. GitHub's broker interprets the broken session as
+  the job needing a fresh runner allocation — hence the "waiting for runner" message
+  for a job that is technically already in-flight.
+
+  The runner service itself remains running and reports "idle" to GitHub, but the job
+  session token has already been invalidated or the queue socket closed. Restarting
+  the runner service re-establishes the connection and any subsequent cancel+rerun
+  immediately picks up because the session management is freshly initialized.
+
+  Characteristics:
+  - Specific to Windows self-hosted runners (not Ubuntu/macOS hosted runners)
+  - Only occurs in jobs with 2 or more steps
+  - Step 1 always completes; step 2+ hangs without timeout
+  - Cancel + rerun of the stuck job resolves it immediately
+  - Runner service restart also resolves it
+  - Began appearing after Nov 27, 2024 auto-update on Windows machines
+  - Still open as of May 2026 with 90+ reactions (actions/runner#3609)
+
+  Note: This is distinct from runner-environment-082 (runner stuck between JOBS in
+  the same workflow) — this failure occurs between STEPS within a single job.
+fix: |
+  Immediate mitigation:
+  1. Cancel the stuck run in the GitHub Actions UI and re-run it — the job typically
+     completes correctly on rerun because the session is re-initialized.
+  2. Restart the GitHub Actions runner service on the Windows host between runs:
+       Restart-Service -Name "actions.runner.*"
+     (replace wildcard with the actual runner service name from services.msc)
+
+  Permanent mitigation:
+  3. Upgrade the runner to the latest version (v2.334.0+) which includes session
+     management improvements. Check https://github.com/actions/runner/releases for
+     the latest stable version.
+  4. Disable auto-update and pin to a known-good runner version by setting
+     `RUNNER_ALLOW_RUNASROOT=false` and specifying the version in your runner
+     configuration script.
+  5. If operating ARC (Actions Runner Controller), upgrade the controller to use a
+     runner image version 2.334.0+ to pick up the fix.
+fix_code:
+  - language: yaml
+    label: 'Workflow with restart-runner step for self-hosted Windows runners (workaround)'
+    code: |
+      # Workaround: add a pre-step that verifies the runner session is healthy.
+      # This forces a new session token for each major step block.
+      jobs:
+        build:
+          runs-on: [self-hosted, windows]
+          steps:
+            - name: Verify runner session (workaround for runner#3609)
+              run: Write-Host "Runner session active — version $env:RUNNER_VERSION"
+              shell: pwsh
+
+            - uses: actions/checkout@v4
+
+            - name: Build
+              run: dotnet build
+              shell: pwsh
+  - language: yaml
+    label: 'Script to upgrade self-hosted runner to latest version on Windows'
+    code: |
+      # Run on each Windows runner host to upgrade to the latest runner version.
+      # Execute from PowerShell as Administrator.
+
+      # Stop the runner service
+      Stop-Service -Name "actions.runner.*" -Force
+
+      # Download and replace the runner binary
+      $version = (Invoke-RestMethod "https://api.github.com/repos/actions/runner/releases/latest").tag_name.TrimStart('v')
+      Invoke-WebRequest "https://github.com/actions/runner/releases/download/v$version/actions-runner-win-x64-$version.zip" -OutFile runner.zip
+      Expand-Archive runner.zip -DestinationPath . -Force
+
+      # Restart the service
+      Start-Service -Name "actions.runner.*"
+      Write-Host "Runner upgraded to v$version"
+prevention:
+  - 'Keep self-hosted runners updated to the latest runner version — regression fixes are frequent'
+  - 'Monitor runner logs at _diag/Runner_*.log for session/message-queue errors between steps'
+  - 'Set up automatic runner version checks in your infrastructure pipeline'
+  - 'For critical pipelines, disable auto-update and pin to a tested runner version then upgrade on schedule'
+  - 'On Windows hosts, ensure the runner service account has rights to re-establish named pipe connections between steps'
+docs:
+  - url: 'https://github.com/actions/runner/issues/3609'
+    label: 'actions/runner#3609: Self-hosted runner stuck "Waiting for runner" in multi-step jobs (90 reactions, open Dec 2024)'
+  - url: 'https://github.com/actions/runner/releases'
+    label: 'GitHub Actions Runner releases — check for v2.321.0 regression fixes'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners'
+    label: 'GitHub Docs: About self-hosted runners'

package/errors/runner-environment/setup-java-sudo-strips-java-home-env-reset.yml

@@ -0,0 +1,111 @@
+id: runner-environment-183
+title: "setup-java JAVA_HOME stripped by sudo env_reset on Ubuntu — wrong JDK used silently"
+category: runner-environment
+severity: silent-failure
+tags:
+  - setup-java
+  - sudo
+  - java
+  - ubuntu
+  - env-reset
+  - sudoers
+  - java-home
+patterns:
+  - regex: 'error: invalid target release: \d+'
+    flags: 'i'
+  - regex: '(bad source file|class file has wrong version).*\d+\.\d+'
+    flags: 'i'
+error_messages:
+  - "error: invalid target release: 25"
+  - "error: invalid target release: 21"
+  - "error: invalid target release: 23"
+  - "class file has wrong version"
+root_cause: |
+  Ubuntu's sudoers policy includes `env_reset` and `secure_path` by default. When a
+  workflow step runs any command via `sudo` (e.g., `sudo apt-get install ...`,
+  `sudo ant build`, `sudo mvn package`), the environment is completely reset: PATH
+  reverts to the sudoers secure_path and JAVA_HOME is cleared.
+
+  Because the runner image has JDK 17 registered as the system default via
+  `update-alternatives`, any subsequent Java invocation under sudo — including
+  tool-wrapped invocations via Debian-packaged `ant` (which uses `java-wrappers.sh`
+  to detect Java through system alternatives) — silently uses JDK 17 regardless of
+  what `actions/setup-java` configured.
+
+  This causes silent failures when the build silently compiles against JDK 17 and
+  produces wrong artifacts, and explicit errors when the requested JDK is newer
+  than 17 and javac refuses with "error: invalid target release: N".
+
+  The root cause is not a bug in setup-java — it correctly sets JAVA_HOME and PATH
+  via $GITHUB_ENV / $GITHUB_PATH, which only apply to non-sudo process contexts.
+  Ubuntu's sudoers env_reset is OS-level behaviour that strips those env variables.
+fix: |
+  1. Pass JAVACMD explicitly to sudo: `sudo JAVACMD=$JAVA_HOME/bin/java ant ...`
+     (Debian-packaged ant reads JAVACMD before system alternatives)
+  2. Register the setup-java JDK as the system default before any sudo steps:
+     sudo update-alternatives --install /usr/bin/java java "$JAVA_HOME/bin/java" 2000
+     sudo update-alternatives --set java "$JAVA_HOME/bin/java"
+  3. Avoid running Java build tools via sudo entirely — install build dependencies
+     first, then run the build as the runner user (without sudo).
+  4. Use `sudo -E` to preserve the current environment (requires sudoers NOPASSWD
+     with env_keep or SETENV; not available by default on GitHub-hosted runners).
+fix_code:
+  - language: yaml
+    label: "Workaround: pass JAVACMD explicitly to sudo ant/maven"
+    code: |
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          java-version: '25'
+          distribution: temurin
+
+      # Debian ant uses java-wrappers which ignores JAVA_HOME — pass JAVACMD directly
+      - name: Build with ant (sudo)
+        run: sudo JAVACMD=$JAVA_HOME/bin/java ant build
+
+  - language: yaml
+    label: "Workaround: register JDK as system default before sudo steps"
+    code: |
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          java-version: '25'
+          distribution: temurin
+
+      - name: Register JDK as system default (for sudo)
+        run: |
+          sudo update-alternatives --install /usr/bin/java java "$JAVA_HOME/bin/java" 2000
+          sudo update-alternatives --set java "$JAVA_HOME/bin/java"
+          sudo update-alternatives --install /usr/bin/javac javac "$JAVA_HOME/bin/javac" 2000
+          sudo update-alternatives --set javac "$JAVA_HOME/bin/javac"
+
+      - name: Build (sudo now uses correct JDK)
+        run: sudo ant build
+
+  - language: yaml
+    label: "Best practice: separate install from build to avoid sudo"
+    code: |
+      - name: Install build dependencies
+        run: sudo apt-get install -y build-essential
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          java-version: '25'
+          distribution: temurin
+
+      # No sudo here — JAVA_HOME is intact
+      - name: Build
+        run: ant build
+prevention:
+  - "Avoid running Java build tools (ant, mvn, gradle) via sudo — install OS dependencies before setup-java, build without sudo"
+  - "After setup-java, verify sudo sees the correct JDK: sudo java -version"
+  - "For Debian-packaged tools (apt install ant), always pass JAVACMD=$JAVA_HOME/bin/java when invoking via sudo"
+  - "If sudo is unavoidable, register the JDK via update-alternatives immediately after setup-java"
+docs:
+  - url: "https://github.com/actions/setup-java/issues/997"
+    label: "ubuntu-latest uses wrong JDK version under sudo (setup-java#997)"
+  - url: "https://github.com/actions/setup-java/pull/1013"
+    label: "Update README for Ubuntu sudo JAVA_HOME behavior (setup-java PR#1013)"
+  - url: "https://manpages.ubuntu.com/manpages/noble/en/man5/sudoers.5.html"
+    label: "sudoers(5) — env_reset and secure_path"

package/errors/runner-environment/setup-python-free-threaded-arm64-broken-symlink.yml

@@ -0,0 +1,98 @@
+id: runner-environment-184
+title: "setup-python free-threaded Python (3.13t/3.14t) on windows-11-arm64 installs broken 0-byte python.exe symlink"
+category: runner-environment
+severity: error
+tags:
+  - setup-python
+  - free-threaded
+  - python
+  - windows-11-arm64
+  - symlink
+  - arm64
+  - reparse-point
+patterns:
+  - regex: 'Fatal Python error: Failed to import encodings module'
+    flags: 'i'
+  - regex: 'ModuleNotFoundError: No module named .encodings.'
+    flags: 'i'
+  - regex: 'Remove-Item.*python\.exe.*does not exist'
+    flags: 'i'
+error_messages:
+  - "Fatal Python error: Failed to import encodings module"
+  - "ModuleNotFoundError: No module named 'encodings'"
+  - "Remove-Item : Cannot find path '...\\arm64-freethreaded\\python.exe' because it does not exist."
+  - "Error happened during pip installation / upgrade"
+root_cause: |
+  The `win32-arm64-freethreaded` distribution zip for Python 3.13t and 3.14t packages
+  `python.exe` and `python3.exe` as Windows reparse points (symlinks) pointing to
+  `python3.13t.exe` / `python3.14t.exe`.
+
+  When actions/setup-python extracts and copies the zip contents to the tool cache on
+  `windows-11-arm64`, the symlink target is not found at the expected relative path —
+  the copy operation leaves a dangling 0-byte reparse point (`-a---l 0 python.exe`)
+  instead of a real executable.
+
+  `setup.ps1:131` then fails to Remove-Item the dangling reparse point (PowerShell
+  cannot delete it because the path resolves as non-existent), and the tool cache
+  entry has no working Python interpreter. When the action invokes the installed
+  python, it immediately crashes with "Fatal Python error: Failed to import encodings
+  module" because the 0-byte stub cannot locate its stdlib.
+
+  Non-free-threaded arm64 builds (3.11, 3.12, 3.13, 3.14) are not affected — only
+  the `*t` (free-threaded / GIL-free) variants hit this issue on windows-11-arm64.
+fix: |
+  1. Workaround: Use the non-free-threaded variant (3.13 instead of 3.13t) unless
+     the GIL-free runtime is explicitly required.
+  2. Workaround for arm64 only: Install free-threaded Python from NuGet, which
+     ships real executables instead of symlinks. Gate on runner.arch == 'ARM64'.
+  3. Wait for actions/setup-python to land a fix that correctly resolves Windows
+     reparse points in free-threaded zip distributions (tracked in setup-python#1307).
+fix_code:
+  - language: yaml
+    label: "Workaround: use non-free-threaded Python on windows-11-arm64"
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          # Avoid '3.13t' / '3.14t' on windows-11-arm64 — use standard variant
+          python-version: '3.13'
+
+  - language: yaml
+    label: "Workaround: install free-threaded Python via NuGet on ARM64"
+    code: |
+      - name: Setup Python (non-ARM64)
+        if: runner.arch != 'ARM64'
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13t'
+
+      - name: Install free-threaded Python via NuGet (windows-11-arm64 workaround)
+        if: runner.os == 'Windows' && runner.arch == 'ARM64'
+        run: |
+          nuget install python -Version 3.13.3t -OutputDirectory "$env:RUNNER_TEMP\nuget" -NonInteractive
+          $pythonDir = Get-ChildItem "$env:RUNNER_TEMP\nuget" -Filter "python.3*" | Select-Object -First 1
+          Add-Content $env:GITHUB_PATH "$($pythonDir.FullName)\tools"
+          Add-Content $env:GITHUB_PATH "$($pythonDir.FullName)\tools\Scripts"
+
+  - language: yaml
+    label: "Verification step: confirm Python works after setup"
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13t'
+
+      - name: Verify Python installation
+        run: |
+          python --version
+          python -c "import sys; print(sys.version, sys._is_gil_enabled())"
+prevention:
+  - "Do not use free-threaded Python variants (3.13t, 3.14t) on windows-11-arm64 until setup-python#1307 is resolved"
+  - "Gate free-threaded Python tests: run on ubuntu-latest or windows-latest (x64), avoid windows-11-arm64 for *t variants"
+  - "Add a verification step (python -c 'import sys') after setup-python to catch broken installs before test steps"
+  - "Follow setup-python#1307 for the official fix — upgrade as soon as a patched version is released"
+docs:
+  - url: "https://github.com/actions/setup-python/issues/1307"
+    label: "setup-python fails for free-threaded Python (3.13t/3.14t) on windows-11-arm64 (setup-python#1307)"
+  - url: "https://github.com/onnx/onnx/pull/7869"
+    label: "Install free-threaded Python from NuGet on windows-11-arm (workaround reference)"
+  - url: "https://docs.python.org/3.13/whatsnew/3.13.html#free-threaded-cpython"
+    label: "Python 3.13 — Free-threaded CPython documentation"

package/errors/runner-environment/sparse-checkout-cone-mode-not-honored-git-pre-237.yml

@@ -0,0 +1,121 @@
+id: 'runner-environment-182'
+title: 'actions/checkout sparse-checkout-cone-mode: true not honored when container git < 2.37'
+category: 'runner-environment'
+severity: 'error'
+tags:
+  - sparse-checkout
+  - cone-mode
+  - git-version
+  - container
+  - checkout
+  - self-hosted
+patterns:
+  - regex: 'sparse-checkout-cone-mode.*true.*container'
+    flags: 'i'
+  - regex: 'git.*2\.[12][0-9]\.'
+    flags: 'i'
+  - regex: 'core\.sparseCheckoutConeMode.*not set'
+    flags: 'i'
+error_messages:
+  - "Expected full checkout but only subdirectory present"
+  - "Sibling files missing from sparse checkout cone"
+  - "core.sparseCheckoutConeMode"
+root_cause: |
+  `actions/checkout` enables sparse-checkout cone mode by setting
+  `core.sparseCheckoutConeMode = true` in the git config. However, the
+  `git sparse-checkout set` command requires the explicit `--cone` flag to
+  activate cone mode in Git versions **before 2.37.0**.
+
+  Starting with Git 2.37.0, cone mode became the default for `git sparse-checkout`.
+  In earlier Git versions, cone mode must be opted into with `--cone`. The
+  `actions/checkout` action does NOT pass `--cone` explicitly, so when running
+  inside a container image with Git < 2.37 (e.g., `ubuntu:22.04` ships with
+  Git 2.34.1), setting `sparse-checkout-cone-mode: true` has no effect.
+
+  The result is that cone mode is silently ignored. The checkout runs in non-cone
+  (gitignore pattern) mode instead, which means:
+  - Root-level sibling files that should be included in cone mode are absent
+  - Only the exact subdirectory specified is checked out, without the expected
+    parent-level files
+  - Subsequent steps that depend on root-level files (e.g., package.json, .env,
+    Makefile) fail with "file not found" errors that appear unrelated to checkout
+
+  Reported in actions/checkout#1868 (Aug 2024).
+fix: |
+  Option 1 (recommended): Upgrade Git in the container to 2.37.0 or later.
+  For containers based on Ubuntu 22.04, install a newer Git via PPA:
+    add-apt-repository ppa:git-core/ppa && apt-get install git
+
+  Option 2: Add an explicit `git sparse-checkout init --cone` step AFTER checkout
+  to force cone mode activation retroactively. This is a workaround for containers
+  where upgrading Git is not possible.
+
+  Option 3: Use GitHub-hosted runners (ubuntu-latest, ubuntu-24.04) which ship
+  with Git >= 2.43, where cone mode works correctly by default.
+
+  Option 4: If specific file patterns are required (not just directories), use
+  `sparse-checkout-cone-mode: false` with root-anchored `/pattern` patterns
+  instead of relying on cone mode.
+fix_code:
+  - language: yaml
+    label: 'Upgrade git in container before checkout (Ubuntu 22.04 example)'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          container:
+            image: ubuntu:22.04
+          steps:
+            - name: Upgrade git to 2.37+ for sparse-checkout cone mode support
+              run: |
+                apt-get update -qq
+                apt-get install -y software-properties-common
+                add-apt-repository -y ppa:git-core/ppa
+                apt-get update -qq
+                apt-get install -y git
+                git --version  # Verify >= 2.37
+
+            - uses: actions/checkout@v4
+              with:
+                sparse-checkout: |
+                  src
+                  config
+                sparse-checkout-cone-mode: true   # Now honored after Git 2.37+ installed
+  - language: yaml
+    label: 'Workaround: force --cone after checkout on old Git'
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout: src
+          sparse-checkout-cone-mode: true
+
+      # Explicitly enable cone mode on Git < 2.37 (workaround for actions/checkout#1868)
+      - name: Force cone mode on old git
+        run: |
+          git sparse-checkout init --cone
+          git sparse-checkout set src
+  - language: yaml
+    label: 'Use GitHub-hosted runner to avoid old git versions'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest  # Ships with Git 2.43+ — cone mode works correctly
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                sparse-checkout: |
+                  src
+                  config
+                # sparse-checkout-cone-mode: true  # Default, works on ubuntu-latest
+prevention:
+  - "Check the git version in container images before relying on sparse-checkout cone mode: run 'git --version' in a workflow step."
+  - "Upgrade container base images to Ubuntu 24.04 or Debian 12 which ship with Git >= 2.39."
+  - "Pin to GitHub-hosted runners (ubuntu-latest, ubuntu-24.04) for consistent Git versions that support cone mode."
+  - "After setting up sparse checkout, add a debug step printing 'git config core.sparseCheckoutConeMode' to verify cone mode is active."
+docs:
+  - url: 'https://github.com/actions/checkout/issues/1868'
+    label: 'actions/checkout#1868 — sparse-checkout-cone-mode not honored on git < 2.37'
+  - url: 'https://git-scm.com/docs/git-sparse-checkout/2.37.0'
+    label: 'Git 2.37 release notes — cone mode becomes the default for sparse-checkout'
+  - url: 'https://github.com/actions/checkout?tab=readme-ov-file'
+    label: 'actions/checkout — sparse-checkout inputs documentation'

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

@@ -0,0 +1,104 @@
+id: silent-failures-099
+title: 'setup-node registry-url auto-sets NODE_AUTH_TOKEN which blocks npm OIDC provenance publish'
+category: silent-failures
+severity: silent-failure
+tags:
+  - setup-node
+  - npm
+  - oidc
+  - provenance
+  - NODE_AUTH_TOKEN
+  - registry-url
+  - publish
+patterns:
+  - regex: 'npm publish.*--provenance'
+    flags: 'i'
+  - regex: 'npm (ERR!|error) code E401'
+    flags: 'i'
+  - regex: 'NODE_AUTH_TOKEN.*publish|npm.*oidc.*token'
+    flags: 'i'
+error_messages:
+  - "npm error code E401"
+  - "npm error 401 Unauthorized - PUT https://registry.npmjs.org/"
+  - "npm publish --provenance"
+root_cause: |
+  When actions/setup-node is used with `registry-url`, it automatically generates a
+  `.npmrc` file containing `//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}`. This
+  binds npm authentication to the NODE_AUTH_TOKEN environment variable at publish time.
+
+  For npm OIDC publishing (`npm publish --provenance`), npm requires that no
+  `_authToken` is set (or that it is empty string), so that npm can use the GitHub
+  Actions OIDC token to authenticate and attach a sigstore provenance attestation.
+
+  However, if NODE_AUTH_TOKEN is present in the environment — even set by setup-node's
+  own post-install logic (authutil.ts sets a default value when registry-url is
+  provided) — npm uses that token for auth instead of OIDC. This silently bypasses the
+  OIDC flow in one of two ways:
+    1. NODE_AUTH_TOKEN is set to a valid npm publish token → publish succeeds but
+       WITHOUT provenance attestation (silent failure, no error thrown).
+    2. NODE_AUTH_TOKEN is set to a wrong/expired value (e.g., GitHub token) → npm
+       rejects with E401 Unauthorized, making it seem like a credential problem.
+
+  Both cases confuse developers who believe setup-node + --provenance "just works".
+  The root: setup-node's auto-set NODE_AUTH_TOKEN takes precedence over OIDC.
+
+  Source: actions/setup-node#1440 (23 reactions, closed May 2026 — setup-node v5+ adds
+  a new behavior where OIDC is respected, but pre-v5 or misconfigured workflows still
+  hit this).
+fix: |
+  Option 1 (recommended — explicit unset in publish step):
+  Unset NODE_AUTH_TOKEN in the npm publish step's `env:` block so that OIDC can take
+  over. An empty string `""` causes npm to ignore the .npmrc token reference.
+
+  Option 2: Remove `registry-url` from setup-node if you don't need .npmrc written
+  (e.g., when publishing to npmjs.org with OIDC only). setup-node only writes .npmrc
+  when registry-url is explicitly set.
+
+  Option 3: Upgrade to actions/setup-node@v5+ which fixed the default NODE_AUTH_TOKEN
+  behavior to not override OIDC when the token is unset.
+
+  Option 4: Set `auth-token: ""` in the setup-node step (setup-node v5.5.0+).
+fix_code:
+  - language: yaml
+    label: 'Unset NODE_AUTH_TOKEN in the npm publish step to allow OIDC'
+    code: |
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Publish with provenance
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ''   # Explicitly empty so npm uses OIDC instead of token auth
+  - language: yaml
+    label: 'Correct OIDC provenance publish permissions'
+    code: |
+      permissions:
+        contents: read
+        id-token: write   # Required for OIDC token — without this npm --provenance fails
+
+      steps:
+        - uses: actions/setup-node@v4
+          with:
+            node-version: '20'
+            registry-url: 'https://registry.npmjs.org'
+
+        - run: npm publish --provenance --access public
+          env:
+            NODE_AUTH_TOKEN: ''
+prevention:
+  - 'Always set `id-token: write` permission when using npm --provenance OIDC publishing'
+  - 'Set `NODE_AUTH_TOKEN: ""` explicitly in the env of the npm publish step when using OIDC'
+  - 'Upgrade to actions/setup-node v5+ which corrected the default NODE_AUTH_TOKEN behavior'
+  - 'Verify provenance attestation was created: check the package page on npmjs.org for the attestations badge'
+  - 'Avoid setting registry-url in setup-node if only using OIDC and no npm install caching is needed'
+docs:
+  - url: 'https://github.com/actions/setup-node/issues/1440'
+    label: 'actions/setup-node#1440: Don''t default NPM_AUTH_TOKEN to support NPM OIDC (23 reactions, closed May 2026)'
+  - url: 'https://docs.npmjs.com/generating-provenance-statements'
+    label: 'npm Docs: Generating provenance statements'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds'
+    label: 'GitHub Docs: Artifact attestations for build provenance'
+  - url: 'https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md#publish-to-npmjs-and-gpr-with-npm'
+    label: 'setup-node advanced usage: publishing to npm'

package/errors/silent-failures/sparse-checkout-non-cone-gitignore-depth-extra-paths.yml

@@ -0,0 +1,96 @@
+id: 'silent-failures-100'
+title: 'sparse-checkout-cone-mode: false matches file patterns at any depth, checking out unintended paths'
+category: 'silent-failures'
+severity: 'silent-failure'
+tags:
+  - sparse-checkout
+  - cone-mode
+  - gitignore-patterns
+  - checkout
+  - extra-files
+patterns:
+  - regex: 'sparse-checkout-cone-mode:\s*false'
+    flags: 'i'
+  - regex: 'sparse.checkout.*cone.mode.*false'
+    flags: 'i'
+  - regex: 'non.cone mode.*sparse'
+    flags: 'i'
+error_messages:
+  - "Run actions/checkout@v4"
+  - "sparse-checkout-cone-mode: false"
+  - "Unexpected files present in workspace"
+root_cause: |
+  When `sparse-checkout-cone-mode: false` is set, `actions/checkout` uses
+  gitignore-style pattern matching for sparse checkout. In this non-cone mode,
+  a pattern like `myfile.yaml` (without a leading `/`) is interpreted as a
+  gitignore glob that matches `myfile.yaml` at ANY depth in the repository tree,
+  not just at the root. This causes `folderA/myfile.yaml`,
+  `folderB/subdir/myfile.yaml`, and all other path-depth occurrences of the
+  filename to be checked out alongside the intended root-level `myfile.yaml`.
+
+  Similarly, a pattern like `scripts` matches not just the top-level `scripts/`
+  directory but any directory or file named `scripts` at any depth.
+
+  The checkout step reports success with no error — the silent failure is that
+  the workspace contains more files than the developer expected, which can:
+  - Cause unintended files to be processed by downstream steps
+  - Inflate workspace size beyond what sparse checkout was intended to achieve
+  - Cause cache keys computed from workspace contents to be incorrect
+  - Introduce security risks if sensitive files at unexpected paths are included
+
+  Reported in actions/checkout#1628 (Feb 2024, multiple reproductions).
+  Non-cone mode is also deprecated by the Git project for these and other reasons.
+fix: |
+  Option 1 (recommended): Switch to cone mode (the default).
+  Cone mode only accepts directory names, not patterns. It always includes root-level
+  files and all files under the specified directories. It is faster and predictable.
+
+  Option 2: Anchor non-cone patterns to the root with a leading `/`.
+  In gitignore syntax, a leading `/` anchors the pattern to the root of the tree,
+  so `/myfile.yaml` matches only the root-level file, not `/subfolder/myfile.yaml`.
+
+  Option 3: Use `filter: blob:none` (partial clone) instead of sparse-checkout
+  when you need to avoid downloading specific large binary assets rather than
+  limiting which files are checked out.
+fix_code:
+  - language: yaml
+    label: 'Switch from non-cone to cone mode (recommended)'
+    code: |
+      # BEFORE (non-cone mode — patterns match at any depth)
+      # - uses: actions/checkout@v4
+      #   with:
+      #     sparse-checkout-cone-mode: false
+      #     sparse-checkout: |
+      #       myfile.yaml
+      #       scripts
+
+      # AFTER (cone mode — specify directory names; root files always included)
+      - uses: actions/checkout@v4
+        with:
+          # sparse-checkout-cone-mode: true  # This is the default — safe to omit
+          sparse-checkout: |
+            scripts
+            # Root-level files are always included in cone mode automatically
+  - language: yaml
+    label: 'Anchor non-cone patterns to root with leading / if you must use non-cone mode'
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          sparse-checkout-cone-mode: false
+          sparse-checkout: |
+            /myfile.yaml      # Leading / anchors to repo root only
+            /scripts          # Only the top-level scripts/ directory
+            # WITHOUT leading /, 'scripts' would match any 'scripts' dir at any depth
+prevention:
+  - "Avoid sparse-checkout-cone-mode: false unless you specifically need gitignore-style pattern matching."
+  - "When using non-cone mode, always prefix patterns with / to anchor them to the repository root."
+  - "After a sparse checkout, validate workspace contents by printing ls -R or find . to spot unexpected files."
+  - "Prefer cone mode (the default) — it is faster, predictable, and not deprecated."
+  - "For excluding large binary files rather than limiting directory scope, use partial clone with filter: blob:none."
+docs:
+  - url: 'https://github.com/actions/checkout/issues/1628'
+    label: 'actions/checkout#1628 — sparse-checkout checks out undefined paths in non-cone mode'
+  - url: 'https://git-scm.com/docs/git-sparse-checkout#_non_cone_problems'
+    label: 'Git docs — Non-cone mode problems and deprecation notice'
+  - url: 'https://github.com/actions/checkout?tab=readme-ov-file#fetch-only-a-single-file'
+    label: 'actions/checkout — Sparse-checkout usage and cone-mode default'