@htekdev/actions-debugger 1.0.31 → 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/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/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.31",
+  "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",