@htekdev/actions-debugger 1.0.30 → 1.0.32

package/errors/caching-artifacts/download-artifact-v5-single-artifact-no-subdirectory.yml

@@ -0,0 +1,106 @@
+id: 'caching-artifacts-029'
+title: '`download-artifact` v5+ omits artifact subdirectory when only one artifact exists — dynamic workflows break intermittently'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - download-artifact
+  - v5-breaking-change
+  - path-behavior
+  - single-artifact
+  - subdirectory
+  - dynamic-matrix
+patterns:
+  - regex: 'uses:\s*actions/download-artifact@v[5-9]'
+    flags: 'i'
+  - regex: 'An extra directory with the artifact name will be created for each download'
+    flags: 'i'
+error_messages:
+  - 'No input name, artifact-ids or pattern filtered specified, downloading all artifacts'
+  - 'An extra directory with the artifact name will be created for each download'
+root_cause: |
+  In actions/download-artifact v5 (released August 2025) and later (v6, v7), when
+  downloading ALL artifacts without specifying name: or id:, and only ONE artifact exists
+  in the workflow run, the action does NOT create a subdirectory for that artifact.
+  Files are extracted directly into the destination path (default ./):
+
+    Expected (v4 and v5+ with >=2 artifacts): ./{artifact-name}/file.ext
+    Actual (v5+ with exactly 1 artifact):      ./file.ext
+
+  When two or more artifacts exist, subdirectories are created correctly. This
+  inconsistency breaks workflows where artifact count varies dynamically — e.g., matrix
+  strategies that produce 0, 1, or N artifacts based on test conditions.
+
+  The action logs "An extra directory with the artifact name will be created for each
+  download" even when it will NOT do this — making the bug invisible in logs.
+
+  Bug tracked in actions/download-artifact#455 (December 2025, still open).
+  Affected versions: v5.0.0+, v6.0.0+, v7.0.0+
+  v4 behavior (correct): always creates a named subdirectory, regardless of artifact count.
+
+  This is a regression from a path behavior fix introduced in v5 for single-artifact
+  downloads by ID (PR #416), which had an unintended side effect on the "all artifacts"
+  code path when n=1.
+fix: |
+  Option 1 (simplest): Pin to actions/download-artifact@v4, which always creates a
+  subdirectory regardless of artifact count. v4 remains maintained for GHES compatibility.
+
+  Option 2: Always specify name: for each download to avoid the "all artifacts" code path.
+
+  Option 3: In downstream steps, detect the n=1 case at runtime and normalize the
+  directory structure before relying on subdirectory paths.
+fix_code:
+  - language: yaml
+    label: 'Pin to download-artifact@v4 for consistent subdirectory behavior'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Download all artifacts
+              uses: actions/download-artifact@v4    # v4: always creates subdirs
+              with:
+                path: artifacts/
+              # Result: artifacts/{name}/... for every artifact, even when n=1
+
+            - name: Deploy each artifact directory
+              run: |
+                for dir in artifacts/*/; do
+                  name=$(basename "$dir")
+                  echo "Deploying $name from $dir"
+                done
+  - language: yaml
+    label: 'Workaround for v5+: download by name into named subdirectories explicitly'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: List artifact names for this run
+              id: list
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  const { data } = await github.rest.actions.listWorkflowRunArtifacts({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    run_id: context.runId
+                  });
+                  return data.artifacts.map(a => a.name);
+
+            - name: Download artifact into named subdirectory
+              uses: actions/download-artifact@v5
+              with:
+                name: my-artifact
+                path: artifacts/my-artifact/   # Explicit subdir — consistent always
+prevention:
+  - 'Pin to download-artifact@v4 if your deployment logic assumes each artifact lands in its own named subdirectory'
+  - 'Test your workflow with exactly one artifact in CI — the n=1 edge case is easy to miss in standard multi-run testing'
+  - 'Avoid relying on implicit subdirectory creation; always specify explicit path: values that include the artifact name'
+  - 'Track actions/download-artifact#455 for a fix in v5+ that restores consistent subdirectory behavior'
+docs:
+  - url: 'https://github.com/actions/download-artifact/issues/455'
+    label: 'actions/download-artifact#455: Single artifact omits subdirectory in v5+ (open, December 2025)'
+  - url: 'https://github.com/actions/download-artifact/releases/tag/v5.0.0'
+    label: 'download-artifact v5.0.0 release notes: path behavior breaking change'
+  - url: 'https://github.com/actions/download-artifact/blob/main/docs/MIGRATION.md'
+    label: 'download-artifact migration guide: v3/v4 to v5+'

package/errors/permissions-auth/ghs-token-new-jwt-format-breaks-length-pattern-validation.yml

@@ -0,0 +1,95 @@
+id: 'permissions-auth-031'
+title: 'GitHub App installation token new stateless JWT format (~520 chars) breaks hardcoded length and regex validation'
+category: permissions-auth
+severity: error
+tags:
+  - github-app-token
+  - ghs-token
+  - jwt-format
+  - token-validation
+  - installation-token
+  - breaking-change-2026
+patterns:
+  - regex: 'ghs_[A-Za-z0-9]{36}\b'
+    flags: ''
+  - regex: 'Data too long for column|token.*length.*40|varchar\s*\(\s*40\s*\)'
+    flags: 'i'
+error_messages:
+  - "Data too long for column 'access_token' at row 1"
+  - 'Token validation failed: token length 521 does not match expected 40'
+  - 'Invalid token format: expected 40 characters, got 523'
+  - 'ghs_[A-Za-z0-9]{36} pattern did not match token starting with ghs_'
+root_cause: |
+  Starting April 27, 2026, GitHub began a staged rollout that changes the format of all
+  GitHub App installation tokens (ghs_ prefixed tokens), including the GITHUB_TOKEN
+  issued to Actions workflows.
+
+  Old format: ghs_<36 alphanumeric chars> — exactly 40 characters, opaque string
+  New format: ghs_<AppID>_<JWT> — approximately 520 characters (variable length),
+              JWT payload is signed by a GitHub-internal issuer
+
+  Any code that validates or stores tokens with the old format assumption WILL break:
+  - Regex: ghs_[A-Za-z0-9]{36} — the {36} quantifier rejects the new variable-length JWT
+  - Length checks: len(token) == 40, token.length === 40, strlen($token) == 40
+  - Database columns: VARCHAR(40) or CHAR(40) — the new ~520-char token truncates or errors
+  - Secret scanning rules with exact-length matchers for ghs_ tokens miss leaked tokens
+
+  The rollout timeline:
+  - April 27 – mid-May 2026: GITHUB_TOKEN and first-party tokens (Dependabot, Slack, Teams)
+  - Mid-May to late-June 2026: staged rollout to all GitHub App installation tokens
+
+  Despite the new internal JWT structure, the token prefix ghs_ is unchanged. Clients
+  must treat the entire token as an opaque string and must NOT parse or validate the JWT.
+fix: |
+  Treat all ghs_ tokens as variable-length opaque strings. Remove any assumptions about
+  exact length or character structure after the ghs_ prefix:
+
+  1. Update regex patterns: replace ghs_[A-Za-z0-9]{36} with ghs_[A-Za-z0-9._-]+
+  2. Increase database columns: VARCHAR(40) or CHAR(40) → TEXT or VARCHAR(1024)
+  3. Remove hardcoded length checks: len(token) == 40 → len(token) > 3
+  4. Update secret scanning rules to match variable-length ghs_ tokens
+
+  To test your tooling against the new format BEFORE the rollout reaches your integration,
+  use the X-GitHub-Stateless-S2S-Token: enabled header on access token API requests.
+fix_code:
+  - language: yaml
+    label: 'Verify GITHUB_TOKEN length in a workflow — expect ~520 chars with new format'
+    code: |
+      jobs:
+        check-token-format:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Check GITHUB_TOKEN length
+              env:
+                TOKEN: ${{ secrets.GITHUB_TOKEN }}
+              run: |
+                echo "Token length: ${#TOKEN}"
+                # Old format: exactly 40 chars
+                # New format (post-April 2026 rollout): ~520 chars (variable)
+                # If your tooling uses this token, ensure it handles both lengths
+  - language: yaml
+    label: 'Correct regex for ghs_ tokens in secret scanning custom patterns'
+    code: |
+      # WRONG — only matches old 40-char opaque tokens:
+      #   ghs_[A-Za-z0-9]{36}
+      #
+      # CORRECT — matches old and new JWT format:
+      #   ghs_[A-Za-z0-9._-]+
+      #
+      # .github/secret_scanning.yml custom pattern (if scanning for leaked tokens):
+      custom_patterns:
+        - name: GitHub App installation token (all formats)
+          regex: 'ghs_[A-Za-z0-9._-]+'
+prevention:
+  - 'Treat all GitHub tokens as variable-length opaque strings — never hardcode expected length'
+  - 'Use TEXT or VARCHAR(1024) for any database column that stores GitHub App installation tokens'
+  - 'Validate ghs_ tokens by prefix only, not by exact length or post-prefix character class'
+  - 'Subscribe to the GitHub Changelog (github.blog/changelog) to catch token format changes early'
+  - 'Use X-GitHub-Stateless-S2S-Token: enabled header to test your tooling before the rollout reaches your repos'
+docs:
+  - url: 'https://github.blog/changelog/2026-04-24-notice-about-upcoming-new-format-for-github-app-installation-tokens/'
+    label: 'GitHub Changelog: Notice about upcoming new format for GitHub App installation tokens (April 24, 2026)'
+  - url: 'https://github.blog/changelog/2026-05-15-github-app-installation-tokens-per-request-override-header/'
+    label: 'GitHub Changelog: Per-request override header for testing the new token format (May 15, 2026)'
+  - url: 'https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app'
+    label: 'GitHub Docs: Generating an installation access token for a GitHub App'

package/errors/permissions-auth/tj-actions-changed-files-supply-chain-cve-2025-30066.yml

@@ -0,0 +1,99 @@
+id: 'permissions-auth-030'
+title: 'tj-actions/changed-files supply chain attack exposed CI/CD secrets in workflow logs (CVE-2025-30066)'
+category: permissions-auth
+severity: error
+tags:
+  - supply-chain
+  - tj-actions
+  - changed-files
+  - cve-2025-30066
+  - secrets-exposed
+  - security
+  - third-party-action
+patterns:
+  - regex: 'tj-actions/changed-files@(?:v(?:1|35|44)\b|0e58ed8671d6b60d0890c21b07f8835ace038e67)'
+    flags: 'i'
+  - regex: '(?:memdump\.py|gist\.githubusercontent\.com/nikitastupin)'
+    flags: 'i'
+error_messages:
+  - 'Unexpected base64-encoded output in tj-actions/changed-files step logs'
+  - 'Unauthorized outbound request to gist.githubusercontent.com detected in workflow run'
+root_cause: |
+  Between March 14 and March 15, 2025, attackers compromised the tj-actions/changed-files
+  GitHub Action (CVE-2025-30066, GHSA-mw4p-6x4p-x5m5) by retroactively modifying multiple
+  version tags to reference a malicious commit SHA
+  (0e58ed8671d6b60d0890c21b07f8835ace038e67).
+
+  The malicious commit injected a Python script that:
+  1. Downloaded a memory-dump utility from a public GitHub Gist
+  2. Scanned the GitHub Actions Runner Worker process memory for secrets
+  3. Base64-encoded the extracted memory content
+  4. Printed the encoded secrets directly to the workflow log
+
+  For repositories with public workflow logs, these secrets were immediately publicly
+  accessible. Over 23,000 repositories were affected.
+
+  The attack exploited a fundamental trust model weakness: when workflows pin to a version
+  tag (e.g., @v35 or @v44.5.1) rather than a specific commit SHA, an attacker who gains
+  write access to the upstream repository can silently redirect any tag to malicious code.
+  The workflow continues to run without any error — it just also exfiltrates secrets.
+
+  The compromised tags included: v1.0.0, v35.7.7-sec, v44.5.1, and others.
+  The vulnerability window was March 14–15, 2025. Tags have since been updated to safe
+  code, but any secrets exposed during that window must be treated as compromised.
+fix: |
+  Immediate actions if your workflows ran tj-actions/changed-files between March 14-15, 2025:
+  1. Inspect workflow logs for unexpected base64 output in the changed-files step
+  2. Decode any suspicious output: echo 'BLOB' | base64 -d | base64 -d
+  3. Rotate ALL secrets (API keys, tokens, SSH keys, cloud credentials) that were present
+     in any workflow that used the affected action during the vulnerability window
+
+  For all workflows (ongoing prevention):
+  - Pin third-party actions to specific commit SHAs instead of version tags
+  - Use tools like StepSecurity Harden-Runner to detect unexpected outbound network calls
+  - Use tools like pin-github-action or GitHub's allowed-actions list to enforce SHA pinning
+fix_code:
+  - language: yaml
+    label: 'Pin third-party actions to a specific commit SHA instead of a version tag'
+    code: |
+      steps:
+        # Vulnerable: tag can be silently repointed to malicious code
+        # - uses: tj-actions/changed-files@v44
+        # - uses: tj-actions/changed-files@v44.5.1
+
+        # Safe: commit SHA is immutable — attacker cannot redirect it
+        - name: Get changed files
+          id: changed-files
+          uses: tj-actions/changed-files@823fcebdb31bb97eca5b8e3cd20bb12abfa9b68d
+          with:
+            files: |
+              src/**
+  - language: yaml
+    label: 'Use StepSecurity Harden-Runner to detect unauthorized outbound network calls'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Harden runner
+              uses: step-security/harden-runner@v2
+              with:
+                egress-policy: audit   # or 'block' to prevent unauthorized calls
+            - name: Get changed files
+              uses: tj-actions/changed-files@823fcebdb31bb97eca5b8e3cd20bb12abfa9b68d
+prevention:
+  - 'Always pin third-party GitHub Actions to a specific commit SHA, not a version tag'
+  - 'Audit your workflows periodically for version-tagged (not SHA-pinned) third-party actions'
+  - 'Use StepSecurity Harden-Runner or similar tooling to detect anomalous outbound network requests in CI'
+  - 'Subscribe to security advisories for third-party actions your workflows depend on'
+  - 'Rotate secrets immediately if a supply chain compromise is announced for any action you use'
+  - 'Consider using a private action mirror with controlled updates rather than pulling from public repos'
+docs:
+  - url: 'https://github.com/tj-actions/changed-files/security/advisories/GHSA-mw4p-6x4p-x5m5'
+    label: 'GHSA-mw4p-6x4p-x5m5: tj-actions/changed-files supply chain attack advisory'
+  - url: 'https://www.cve.org/CVERecord?id=CVE-2025-30066'
+    label: 'CVE-2025-30066: NVD entry'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#using-third-party-actions'
+    label: 'GitHub Docs: Security hardening — using third-party actions'
+  - url: 'https://docs.stepsecurity.io/harden-runner/'
+    label: 'StepSecurity Harden-Runner documentation'

package/errors/runner-environment/immutable-actions-pkg-domain-not-allowlisted.yml

@@ -0,0 +1,97 @@
+id: 'runner-environment-085'
+title: 'Self-hosted runner fails to download immutable actions — `pkg.actions.githubusercontent.com` not in network allowlist'
+category: runner-environment
+severity: error
+tags:
+  - self-hosted-runner
+  - immutable-actions
+  - network
+  - allowlist
+  - firewall
+  - pkg.actions.githubusercontent.com
+  - action-download
+patterns:
+  - regex: 'Failed to download action.*pkg\.actions\.githubusercontent\.com'
+    flags: 'i'
+  - regex: 'Unable to locate executable.*pkg\.actions\.githubusercontent\.com'
+    flags: 'i'
+  - regex: 'Error: An error occurred while loading the action.*pkg\.actions'
+    flags: 'i'
+  - regex: 'connect(?:ion)? (?:refused|timed? ?out).*pkg\.actions\.githubusercontent\.com'
+    flags: 'i'
+error_messages:
+  - "Error: Failed to download action 'actions/checkout@v4'. Actions requiring immutable action downloads from pkg.actions.githubusercontent.com are blocked."
+  - "Error: An error occurred while loading the action. Connection refused: pkg.actions.githubusercontent.com"
+root_cause: |
+  Starting February 2025, GitHub began migrating GitHub-hosted runners to use
+  "Immutable Actions" — a system where action code is downloaded from a new dedicated
+  CDN host (`pkg.actions.githubusercontent.com`) rather than being cloned directly from
+  the action's GitHub repository.
+
+  Self-hosted runners behind corporate firewalls or with strict network egress allowlists
+  fail to download actions when this new domain is not permitted, causing the job to fail
+  immediately during the action download phase before any user step runs.
+
+  The failure is distinct from a runtime error: the runner itself cannot fetch the action
+  code, so no build output is produced. Logs show a network-level failure during the
+  "Getting action download info" or "Download action repository" phase.
+
+  Organizations that previously configured their allowlist with `*.github.com`,
+  `codeload.github.com`, or `github.com` for action downloads must now also add
+  `pkg.actions.githubusercontent.com`.
+
+  Note: If your allowlist already includes `*.actions.githubusercontent.com`, no change
+  is required — the wildcard matches the new subdomain.
+fix: |
+  Add `pkg.actions.githubusercontent.com` to your self-hosted runner's outbound network
+  allowlist. Runners that already allow `*.actions.githubusercontent.com` via wildcard
+  do not require any change.
+
+  For Azure private networking, also update your NSG template with the additional IP
+  ranges published by GitHub in the February 2025 changelog.
+
+  For GitHub Enterprise Server customers using GitHub Connect: update your self-hosted
+  runner allowlists to include the new domain before enabling immutable actions.
+fix_code:
+  - language: yaml
+    label: 'Required network allowlist domains for self-hosted runners (as of Feb 2025)'
+    code: |
+      # Ensure these domains/IPs are allowed for outbound HTTPS (443) from your runners:
+      #
+      # Existing required domains (unchanged):
+      #   github.com
+      #   api.github.com
+      #   *.actions.githubusercontent.com   <- wildcard covers new subdomain too
+      #   codeload.github.com
+      #   results-receiver.actions.githubusercontent.com
+      #
+      # New domain required for immutable actions (Feb 2025):
+      #   pkg.actions.githubusercontent.com
+      #
+      # If you use domain-specific (not wildcard) allowlists, add:
+      #   pkg.actions.githubusercontent.com
+  - language: yaml
+    label: 'Verify immutable actions network access with a diagnostic step'
+    code: |
+      jobs:
+        network-check:
+          runs-on: [self-hosted]
+          steps:
+            - name: Check immutable actions domain reachability
+              run: |
+                curl -sSf --max-time 10 \
+                  https://pkg.actions.githubusercontent.com \
+                  -o /dev/null -w "HTTP %{http_code}\n" \
+                  || echo "BLOCKED: pkg.actions.githubusercontent.com unreachable"
+prevention:
+  - 'Use wildcard domain entries (`*.actions.githubusercontent.com`) in your network allowlist rather than enumerating specific subdomains'
+  - 'Subscribe to GitHub Changelog (github.blog/changelog) to catch new domain requirements before they cause outages'
+  - 'Periodically run network reachability checks against all required GitHub Actions domains from your runner environment'
+  - 'Document your runner network requirements in runbooks and tie allowlist updates to a change management process'
+docs:
+  - url: 'https://github.blog/changelog/2025-02-12-notice-of-upcoming-deprecations-and-breaking-changes-for-github-actions/'
+    label: 'GitHub Changelog 2025-02-12: Immutable Actions migration and network allowlist updates'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#communication-between-self-hosted-runners-and-github'
+    label: 'GitHub Docs: Self-hosted runner network communication requirements'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#hardening-for-self-hosted-runners'
+    label: 'GitHub Docs: Security hardening for self-hosted runners'

package/errors/silent-failures/download-artifact-merge-multiple-parallel-file-clobber.yml

@@ -0,0 +1,119 @@
+id: 'silent-failures-038'
+title: '`download-artifact` `merge-multiple: true` silently corrupts files when multiple artifacts contain identical filenames'
+category: silent-failures
+severity: silent-failure
+tags:
+  - download-artifact
+  - merge-multiple
+  - file-corruption
+  - parallel-download
+  - race-condition
+  - artifacts
+patterns:
+  - regex: 'merge-multiple:\s*true'
+    flags: 'i'
+  - regex: 'Downloading artifact:.*\n.*Downloading artifact:'
+    flags: 'im'
+error_messages:
+  - 'Downloading artifact: build-linux to /home/runner/work/repo/repo/dist'
+  - 'Downloading artifact: build-macos to /home/runner/work/repo/repo/dist'
+root_cause: |
+  When actions/download-artifact (v4+) is used with merge-multiple: true and two or more
+  artifacts contain files with identical relative paths (e.g., multiple matrix builds each
+  upload a file named checksums.txt or report.json), the action downloads all artifacts
+  in parallel using a PARALLEL_DOWNLOADS worker pool.
+
+  All parallel workers write to the same destination directory concurrently. When two
+  workers attempt to write to the same filename simultaneously, the result is undefined:
+  - The output file may contain interleaved bytes from both sources
+  - The file may be truncated to the size of the smaller upload
+  - One artifact's version may completely overwrite the other (last writer wins)
+
+  The action exits with code 0 and emits no error or warning. The log shows both artifacts
+  downloading normally. The resulting corrupt file is indistinguishable from a valid one
+  unless explicitly checksummed.
+
+  Bug confirmed in actions/download-artifact#395 (March 2025, still open as of Jan 2026).
+  Affects: v4.x, v5.x, v6.x, v7.x
+
+  Common patterns that trigger this bug:
+  - Matrix builds across OS/arch each producing a same-named binary or manifest
+  - Release workflows where each artifact contains a same-named README.md or LICENSE
+  - Merge-and-sign workflows where each per-platform artifact has a checksums.txt
+fix: |
+  Option 1 — Rename artifact files to include OS/arch before uploading so no two
+  artifacts ever contain a file at the same relative path.
+
+  Option 2 — Download each artifact by name into a separate directory rather than using
+  merge-multiple: true.
+
+  Option 3 — Validate checksums of all critical files after downloading and before
+  using them, so corruption is detected rather than silently propagated.
+
+  Option 4 — Use pattern: to download specific artifact subsets one group at a time,
+  ensuring no overlapping filenames within each group.
+fix_code:
+  - language: yaml
+    label: 'Include OS/arch in output filenames to eliminate same-path collisions'
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              os: [ubuntu-latest, macos-latest, windows-latest]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - name: Build and rename output to include OS identifier
+              run: |
+                cp build/output dist/output-${{ runner.os }}-${{ runner.arch }}
+
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-${{ runner.os }}-${{ runner.arch }}
+                path: dist/output-${{ runner.os }}-${{ runner.arch }}
+
+        release:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - name: Download all artifacts (safe — all filenames are unique)
+              uses: actions/download-artifact@v4
+              with:
+                pattern: build-*
+                path: dist/
+                merge-multiple: true
+  - language: yaml
+    label: 'Download each artifact by name into a separate directory (avoids merge-multiple entirely)'
+    code: |
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-Linux
+                path: dist/linux/
+
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-macOS
+                path: dist/macos/
+
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-Windows
+                path: dist/windows/
+
+            # Files are in separate directories — no parallel write collision possible
+prevention:
+  - 'Always include a unique dimension (OS, arch, matrix value) in filenames when uploading from matrix jobs'
+  - 'Audit all artifacts before using merge-multiple: true to confirm no two artifacts share a file path'
+  - 'Verify checksums of all merged files before using them in signing, publishing, or deployment steps'
+  - 'Prefer downloading by name into separate directories over merge-multiple when file collisions are possible'
+docs:
+  - url: 'https://github.com/actions/download-artifact/issues/395'
+    label: 'actions/download-artifact#395: merge-multiple silently corrupts files when same-named files exist (open, March 2025)'
+  - url: 'https://github.com/actions/download-artifact/blob/main/docs/MIGRATION.md#merging-multiple-artifacts'
+    label: 'download-artifact migration guide: Merging multiple artifacts'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflows-do/storing-workflow-data-as-artifacts'
+    label: 'GitHub Docs: Storing workflow data as artifacts'

package/errors/silent-failures/github-ref-full-path-comparison-always-false.yml

@@ -0,0 +1,97 @@
+id: 'silent-failures-036'
+title: '`if: github.ref == ''main''` silently never matches — ref contains full `refs/heads/main` path'
+category: silent-failures
+severity: silent-failure
+tags:
+  - github-ref
+  - ref-name
+  - branch-comparison
+  - if-condition
+  - refs/heads
+  - silent-skip
+patterns:
+  - regex: 'github\.ref\s*[!=]=\s*[''"](?:main|master|develop|release|staging)[''"]'
+    flags: 'i'
+  - regex: 'github\.ref\s*[!=]=\s*[''"][a-z][a-z0-9_/-]*[^/][''"](?!\s*#.*refs/heads)'
+    flags: 'i'
+error_messages:
+  - "Step was skipped because the condition was false: github.ref == 'main'"
+  - "Job skipped: if: github.ref == 'master'"
+root_cause: |
+  `github.ref` always returns the full Git reference path, never just the branch name:
+  - Push to `main` branch: `refs/heads/main`
+  - Pull request: `refs/pull/123/merge`
+  - Tag push: `refs/tags/v1.0.0`
+
+  When a developer writes `if: github.ref == 'main'`, the condition always evaluates
+  to false because `'main'` != `'refs/heads/main'`. The step or job is silently skipped
+  with no error — only a "skipped" indicator in the UI, which is easy to overlook.
+
+  This is the most-viewed GitHub Actions question on Stack Overflow (SO #58033366,
+  478,000+ views), confirming how frequently developers encounter this mismatch.
+
+  Common variants:
+  - `if: github.ref == 'main'` → always false
+  - `if: github.ref == 'master'` → always false
+  - `if: github.ref != 'main'` → always true (everything runs)
+  - `if: github.ref == 'refs/heads/main' && github.ref == 'refs/tags/v*'` → impossible
+    (a ref cannot be both)
+  - On tag push: `if: github.ref == 'refs/heads/main'` → always false (it is `refs/tags/…`)
+fix: |
+  Option 1 — Use `github.ref_name` (recommended, available since runner 2.276.0 / Jan 2022):
+  `github.ref_name` returns just the branch or tag name without the `refs/heads/` or
+  `refs/tags/` prefix, making comparisons intuitive.
+
+  Option 2 — Compare against the full ref path:
+  Use `github.ref == 'refs/heads/main'` instead of `github.ref == 'main'`.
+
+  Option 3 — Match on event type:
+  Use `github.event_name == 'push'` to restrict steps to push (not PR) events, which is
+  often the underlying intent.
+fix_code:
+  - language: yaml
+    label: 'Use github.ref_name for simple branch/tag name comparison'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy to production
+              # github.ref_name returns 'main', 'v1.0.0', etc. (no refs/ prefix)
+              if: github.ref_name == 'main'
+              run: echo "Deploying"
+  - language: yaml
+    label: 'Use full ref path if you need github.ref specifically'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Only on main branch push (not tags or PRs)
+              if: github.ref == 'refs/heads/main'
+              run: echo "Deploying"
+            - name: Only on version tags
+              if: startsWith(github.ref, 'refs/tags/v')
+              run: echo "Releasing"
+  - language: yaml
+    label: 'Use event_name to distinguish push from pull_request'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Only on direct pushes, not PRs
+              if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+              run: echo "Deploying"
+prevention:
+  - 'Never compare `github.ref` to a bare branch name — it always includes the `refs/heads/` prefix'
+  - 'Prefer `github.ref_name` for branch/tag name comparisons when using runner 2.276.0+ (Jan 2022)'
+  - 'Verify your `if:` logic by inspecting the actual `github.ref` value in a debug step: `run: echo "${{ github.ref }}"`'
+  - 'Use the GitHub Actions context documentation to confirm which format each context variable uses'
+docs:
+  - url: 'https://docs.github.com/en/actions/learn-github-actions/contexts#github-context'
+    label: 'GitHub Docs: github context — github.ref and github.ref_name'
+  - url: 'https://stackoverflow.com/questions/58033366/how-to-get-the-current-branch-within-github-actions'
+    label: 'Stack Overflow #58033366 (428 votes, 478K views): How to get the current branch within GitHub Actions'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-conditions-to-control-job-execution'
+    label: 'GitHub Docs: Using conditions to control job execution'

package/errors/silent-failures/head-commit-null-on-pull-request.yml

@@ -0,0 +1,121 @@
+id: 'silent-failures-037'
+title: '`github.event.head_commit` is null on `pull_request` and `workflow_dispatch` events — commit message access silently fails'
+category: silent-failures
+severity: silent-failure
+tags:
+  - head-commit
+  - commit-message
+  - pull-request
+  - workflow-dispatch
+  - event-payload
+  - null-context
+  - silent-skip
+patterns:
+  - regex: 'github\.event\.head_commit\.(?:message|author|id|timestamp)'
+    flags: 'i'
+  - regex: 'github\.event\.head_commit\s+is\s+null'
+    flags: 'i'
+error_messages:
+  - "Error: Unhandled error: TypeError: Cannot read properties of null (reading 'message')"
+  - "Expression evaluation failed: github.event.head_commit is null"
+  - "Step was skipped because the condition was false: contains(github.event.head_commit.message, '[skip ci]')"
+root_cause: |
+  `github.event.head_commit` is only populated on `push` events. It is `null` (not an
+  empty object) on all other event types, including:
+  - `pull_request` and `pull_request_target`
+  - `workflow_dispatch`
+  - `workflow_call`
+  - `schedule`
+  - `release`
+  - `repository_dispatch`
+
+  This causes several silent failure patterns:
+  1. **Silent [skip ci] bypass**: A common pattern is
+     `if: "!contains(github.event.head_commit.message, '[skip ci]')"`.
+     On a `pull_request` event, `github.event.head_commit` is null, so the expression
+     evaluates as `!contains(null, '[skip ci]')` → `!false` → `true`. Every PR run
+     executes unconditionally, ignoring any [skip ci] intent.
+  2. **Runtime crash in scripts**: GitHub Script or shell steps that access
+     `${{ github.event.head_commit.message }}` on PR events receive an empty string
+     silently, or throw a TypeError if accessed via JavaScript.
+  3. **Commit metadata loss in multi-event workflows**: Workflows triggered by both
+     `push` and `pull_request` may use `head_commit` data in notifications or logs;
+     the PR trigger silently produces empty/null values for all commit fields.
+
+  This is documented in Stack Overflow question #63441440 (Score: 95, 100,000+ views).
+fix: |
+  Use a multi-event compatible approach to access commit messages:
+  - For `pull_request`: use `github.event.pull_request.head.sha` and fetch the commit
+    via the API, or use `github-script` with `octokit.rest.repos.getCommit()`
+  - For `push`: `github.event.head_commit.message` works directly
+  - For a robust cross-event solution: use `actions/checkout` with fetch-depth and
+    run `git log -1 --format=%s` in a shell step — this works regardless of event type
+  - For [skip ci] detection: use the `github.event.commits` array (available on `push`)
+    or check PR body/title instead of commit message for multi-event workflows
+fix_code:
+  - language: yaml
+    label: 'Guard head_commit access with event_name check'
+    code: |
+      steps:
+        - name: Get commit message (push events only)
+          if: github.event_name == 'push'
+          run: echo "Commit: ${{ github.event.head_commit.message }}"
+
+        - name: Get HEAD commit message (all events via shell)
+          run: |
+            MSG=$(git log -1 --format='%s')
+            echo "Commit: $MSG"
+  - language: yaml
+    label: 'Cross-event [skip ci] detection using shell git log'
+    code: |
+      jobs:
+        check-skip:
+          runs-on: ubuntu-latest
+          outputs:
+            skip: ${{ steps.skip-check.outputs.skip }}
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                fetch-depth: 2
+            - id: skip-check
+              run: |
+                MSG=$(git log -1 --format='%s')
+                if echo "$MSG" | grep -q '\[skip ci\]'; then
+                  echo "skip=true" >> "$GITHUB_OUTPUT"
+                else
+                  echo "skip=false" >> "$GITHUB_OUTPUT"
+                fi
+
+        build:
+          needs: check-skip
+          if: needs.check-skip.outputs.skip != 'true'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Building"
+  - language: yaml
+    label: 'Fetch commit message via API for pull_request events'
+    code: |
+      steps:
+        - name: Get PR head commit message
+          if: github.event_name == 'pull_request'
+          uses: actions/github-script@v7
+          with:
+            script: |
+              const { data } = await github.rest.repos.getCommit({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                ref: context.payload.pull_request.head.sha
+              });
+              console.log('Commit message:', data.commit.message);
+prevention:
+  - 'Always guard `github.event.head_commit` access with `if: github.event_name == ''push''`'
+  - 'For multi-event workflows needing commit messages, use `git log -1 --format=%s` after checkout rather than the event context'
+  - 'Do not use `github.event.head_commit.message` for [skip ci] detection — it silently fails on PRs and dispatches'
+  - 'Add `run: echo "${{ toJSON(github.event) }}"` to debug which event fields are available for each trigger'
+docs:
+  - url: 'https://docs.github.com/en/webhooks/webhook-events-and-payloads#push'
+    label: 'GitHub Docs: push event payload — head_commit field'
+  - url: 'https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request'
+    label: 'GitHub Docs: pull_request event payload (no head_commit field)'
+  - url: 'https://stackoverflow.com/questions/63441440/get-github-commit-message-in-pull-request-actions'
+    label: 'Stack Overflow #63441440 (95 votes, 100K views): Get GitHub commit message in pull request Actions'

package/errors/triggers/copilot-coding-agent-workflows-require-approval.yml

@@ -0,0 +1,104 @@
+id: 'triggers-027'
+title: 'Copilot coding agent PR workflows stuck in `action_required` — require human approval before running'
+category: triggers
+severity: error
+tags:
+  - copilot
+  - coding-agent
+  - approval-required
+  - action-required
+  - pull-request
+  - workflow-approval
+patterns:
+  - regex: 'action_required'
+    flags: 'i'
+  - regex: 'waiting for approval.*(?:outside contributor|fork|bot)|Approve and run'
+    flags: 'i'
+error_messages:
+  - 'This workflow is waiting for approval from a maintainer. Learn more about approving workflows from public forks.'
+  - 'Workflow run is in action_required state. Approval is required before jobs can start.'
+root_cause: |
+  Starting April 2025, GitHub treats the Copilot coding agent as an "outside contributor"
+  for GitHub Actions workflow approval purposes — the same policy applied to first-time
+  contributors from public forks.
+
+  When Copilot coding agent opens a pull request or pushes commits to a branch:
+  - Associated CI/CD workflows do NOT run automatically
+  - The check suite is created with conclusion: action_required
+  - No jobs start until a human with repository write access (or actions:write) manually
+    clicks "Approve and run workflows" in the PR UI, or approves via the REST API
+  - Unapproved runs are automatically deleted after 30 days with no notification
+
+  This is by design: Copilot-triggered workflows may have access to GITHUB_TOKEN,
+  repository secrets, and deployment environments. The approval gate prevents a
+  compromised or misbehaving AI agent from triggering arbitrary CI/CD actions.
+
+  However, this significantly slows AI-assisted development loops where developers rely
+  on CI feedback to validate Copilot's work. Teams discover this when:
+  - All Copilot-opened PRs show "Waiting for approval" with no CI results
+  - Required status checks never populate, blocking PR merges
+  - Automated pipelines that expected CI to run on all PRs silently stall
+
+  Affects: all GitHub Actions workflows triggered by pull_request, push, or
+  pull_request_target events on branches where Copilot coding agent is the commit author.
+fix: |
+  Option 1 (Recommended for trusted private repos): Enable automatic workflow runs for
+  Copilot coding agent in repository settings:
+  Settings → Actions → General → "Approval for running workflows triggered by Copilot
+  coding agent" → "Allow Copilot coding agent to trigger workflows without approval"
+  (Available since March 2026 changelog)
+
+  Option 2: Manually approve each run after Copilot opens a PR.
+  In the PR, click "Approve and run workflows" in the Checks section.
+
+  Option 3: Build a lightweight auto-approve workflow triggered by check_suite events
+  with action: requested, scoped to Copilot actor identity.
+fix_code:
+  - language: yaml
+    label: 'Approve a pending workflow run via GitHub CLI'
+    code: |
+      # List runs awaiting approval on a Copilot PR branch:
+      # gh run list --repo owner/repo --branch copilot/issue-123
+
+      # Approve a specific run (requires write access):
+      # gh run review <run-id> --approve --repo owner/repo
+
+      # Or approve via REST API:
+      # POST /repos/{owner}/{repo}/actions/runs/{run_id}/approve
+  - language: yaml
+    label: 'Auto-approve workflow: trigger CI immediately on Copilot PRs (use with caution)'
+    code: |
+      name: Auto-approve Copilot workflows
+      on:
+        workflow_run:
+          workflows: ['CI']
+          types: [requested]
+
+      jobs:
+        approve:
+          runs-on: ubuntu-latest
+          # Only auto-approve if triggered by Copilot coding agent
+          if: github.event.workflow_run.actor.login == 'copilot-swe-agent[bot]'
+          permissions:
+            actions: write
+          steps:
+            - name: Approve the workflow run
+              env:
+                RUN_ID: ${{ github.event.workflow_run.id }}
+                GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+              run: |
+                gh run review $RUN_ID --approve --repo ${{ github.repository }}
+prevention:
+  - 'Configure the "Allow Copilot coding agent to trigger workflows without approval" setting if your team uses Copilot heavily and the repo is trusted'
+  - 'Monitor for action_required check suite conclusions so stalled Copilot PRs do not block merges silently'
+  - 'Scope GITHUB_TOKEN permissions to the minimum required before enabling auto-approval, to reduce the blast radius if Copilot misbehaves'
+  - 'Set up required status checks carefully — if CI never runs, required checks will block PR merges indefinitely'
+docs:
+  - url: 'https://github.blog/changelog/2025-04-15-upcoming-breaking-changes-and-releases-for-github-actions/'
+    label: 'GitHub Changelog: Copilot events not automatically triggering GitHub Actions workflows (April 2025)'
+  - url: 'https://github.blog/changelog/2026-03-13-optionally-skip-approval-for-copilot-coding-agent-actions-workflows/'
+    label: 'GitHub Changelog: Optionally skip approval for Copilot coding agent Actions workflows (March 2026)'
+  - url: 'https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/approving-workflow-runs-from-public-forks'
+    label: 'GitHub Docs: Approving workflow runs from public forks'
+  - url: 'https://docs.github.com/en/copilot/using-github-copilot/using-copilot-coding-agent-to-work-on-tasks/configuring-settings-for-github-copilot-coding-agent'
+    label: 'GitHub Docs: Configuring settings for GitHub Copilot coding agent'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htekdev/actions-debugger",
-  "version": "1.0.30",
+  "version": "1.0.32",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",