@htekdev/actions-debugger 1.0.42 → 1.0.44

package/errors/caching-artifacts/upload-artifact-v4-duplicate-name-hard-error.yml

@@ -0,0 +1,114 @@
+id: caching-artifacts-033
+title: 'upload-artifact@v4 requires unique artifact names per run — duplicate name is a hard error'
+category: caching-artifacts
+severity: error
+tags:
+  - upload-artifact
+  - v4
+  - duplicate-name
+  - breaking-change
+  - matrix
+patterns:
+  - regex: 'An artifact with this name already exists on the workflow run'
+    flags: 'i'
+  - regex: 'Failed to CreateArtifact.*already exists'
+    flags: 'i'
+error_messages:
+  - 'An artifact with this name already exists on the workflow run'
+  - 'Failed to CreateArtifact: Artifact already exists'
+root_cause: |
+  actions/upload-artifact@v4 changed artifact name uniqueness enforcement from v3:
+
+  v3 behavior: uploading with a duplicate name silently merged the new files
+  into the existing artifact, potentially overwriting same-named files.
+
+  v4 behavior: uploading with a name that already exists in the same workflow
+  run is a hard error. The step fails immediately with:
+    "An artifact with this name already exists on the workflow run"
+
+  Common triggers:
+  1. Matrix jobs all writing to a fixed artifact name (e.g., name: build-output)
+     without including a matrix dimension in the name.
+  2. Multiple upload-artifact steps in the same job with the same name: value.
+  3. Reusable workflows invoked multiple times in one run using identical names.
+  4. Two upload steps with no name: parameter — both default to "artifact".
+
+  Workflows that relied on v3's merge behavior and were silently uploading
+  duplicate names will fail immediately after upgrading to v4.
+fix: |
+  Include a unique identifier in the artifact name for each upload step.
+  For matrix jobs, include a matrix dimension value. For independent parallel
+  jobs, include the job name or a specific run-scoped identifier.
+
+  If you need to consolidate artifacts from multiple sources, have each job
+  upload with a unique name, then use a final consolidation job that downloads
+  all artifacts and re-uploads a merged set.
+fix_code:
+  - language: yaml
+    label: 'Matrix jobs — include matrix dimension in artifact name'
+    code: |
+      strategy:
+        matrix:
+          os: [ubuntu-latest, windows-latest, macos-latest]
+
+      steps:
+        - name: Build
+          run: make build
+
+        - uses: actions/upload-artifact@v4
+          with:
+            name: build-output-${{ matrix.os }}   # Unique per matrix cell
+            path: dist/
+  - language: yaml
+    label: 'Multiple upload steps — use distinct explicit names'
+    code: |
+      steps:
+        - uses: actions/upload-artifact@v4
+          with:
+            name: test-results       # Distinct name
+            path: test-output/
+
+        - uses: actions/upload-artifact@v4
+          with:
+            name: coverage-report    # Different name — no conflict
+            path: coverage/
+  - language: yaml
+    label: 'Merge artifacts across matrix jobs in a downstream job'
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              os: [ubuntu-latest, windows-latest]
+          steps:
+            - uses: actions/upload-artifact@v4
+              with:
+                name: dist-${{ matrix.os }}
+                path: dist/
+
+        package:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                pattern: dist-*
+                merge-multiple: true
+                path: all-dist/
+
+            - uses: actions/upload-artifact@v4
+              with:
+                name: final-package
+                path: all-dist/
+prevention:
+  - 'Always specify an explicit name: for each upload-artifact step rather than relying on the default "artifact"'
+  - 'For matrix jobs, include at least one matrix variable in the artifact name'
+  - 'Audit workflows being migrated from v3 to v4 for any step that omits name: or uses the same name twice'
+  - 'Two steps with no name: both default to "artifact" and will always conflict in v4'
+docs:
+  - url: 'https://github.com/actions/upload-artifact/blob/main/docs/MIGRATION.md'
+    label: 'upload-artifact v3 to v4 migration guide'
+  - url: 'https://github.com/actions/upload-artifact'
+    label: 'actions/upload-artifact repository'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-workflow-data-as-artifacts'
+    label: 'GitHub Docs — Storing workflow data as artifacts'

package/errors/known-unsolved/environment-matrix-one-review-per-job.yml

@@ -0,0 +1,100 @@
+id: known-unsolved-034
+title: 'environment deployment protection with required reviewers creates one review request per matrix job — no batch approval'
+category: known-unsolved
+severity: limitation
+tags:
+  - environment
+  - matrix
+  - deployment
+  - required-reviewers
+  - approvals
+  - no-fix
+patterns:
+  - regex: 'Waiting for.*review'
+    flags: 'i'
+  - regex: 'Review required before this job runs'
+    flags: 'i'
+error_messages:
+  - 'Waiting for a reviewer'
+  - 'Review required before this job runs'
+root_cause: |
+  GitHub Actions environments with required reviewers enforce approval at the
+  individual job level. When a job using environment: with required reviewers
+  also uses strategy: matrix, each matrix cell creates a separate deployment
+  instance requiring its own approval.
+
+  A 3x3 matrix (os x environment) produces 9 separate "Waiting for reviewer"
+  prompts in the GitHub Actions UI — one for each matrix combination. Each
+  must be approved individually; there is no "approve all" button for
+  matrix deployments.
+
+  This behavior stems from GitHub's deployment model: each job run creates a
+  discrete deployment record in the repository's deployment history. Matrix
+  jobs are independent job runs, so each creates its own deployment record
+  and independently triggers the environment protection review gate.
+
+  This is confirmed expected behavior per GitHub staff in community discussions.
+  There is no configuration option to batch or group matrix job deployment approvals.
+fix: |
+  There is no supported way to batch-approve matrix jobs targeting a protected
+  environment. The workaround is architectural: separate the build/test matrix
+  from the deployment job, using a single non-matrix deploy job that depends
+  on all matrix results via needs:.
+
+  This "build in matrix, deploy once" pattern also aligns with security best
+  practice — production deployments should be a single auditable event.
+fix_code:
+  - language: yaml
+    label: 'Anti-pattern — matrix job with protected environment (creates N review requests)'
+    code: |
+      jobs:
+        deploy:
+          strategy:
+            matrix:
+              region: [us-east-1, eu-west-1, ap-southeast-1]
+          environment: production   # 3 separate review requests
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "deploying to ${{ matrix.region }}"
+  - language: yaml
+    label: 'Workaround — single non-matrix deploy job collects matrix artifacts and deploys once'
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              region: [us-east-1, eu-west-1, ap-southeast-1]
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build for region
+              run: make build REGION=${{ matrix.region }}
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-${{ matrix.region }}
+                path: dist/
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          environment: production   # Single review request for all regions
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                pattern: build-*
+                merge-multiple: true
+                path: all-dist/
+            - name: Deploy all regions
+              run: make deploy-all ARTIFACTS_DIR=all-dist/
+prevention:
+  - 'Design deployment workflows so the job with environment: protection is never a matrix job'
+  - 'Use build-in-matrix, deploy-once pattern: matrix for build/test, single serial job for protected deploy'
+  - 'If per-region deployments must be parallel and require environment protection, accept the N-approvals UX'
+  - 'Document this limitation in team runbooks before adopting matrix + environment patterns in production pipelines'
+docs:
+  - url: 'https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment'
+    label: 'GitHub Docs — Managing environments for deployment'
+  - url: 'https://github.com/orgs/community/discussions/15690'
+    label: 'GitHub Community — Matrix deployment creates multiple approval requests'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-a-matrix-for-your-workflow'
+    label: 'GitHub Docs — Using a matrix for your workflow'

package/errors/permissions-auth/attest-build-provenance-missing-attestations-write.yml

@@ -0,0 +1,100 @@
+id: permissions-auth-035
+title: 'actions/attest-build-provenance fails with 403 — missing attestations: write permission'
+category: permissions-auth
+severity: error
+tags:
+  - attestations
+  - attest-build-provenance
+  - GITHUB_TOKEN
+  - permissions
+  - 403
+  - supply-chain
+patterns:
+  - regex: 'HttpError.*403.*attestation'
+    flags: 'i'
+  - regex: 'Resource not accessible by integration'
+    flags: 'i'
+  - regex: 'Failed to create attestation'
+    flags: 'i'
+error_messages:
+  - 'HttpError: 403 — Resource not accessible by integration'
+  - 'Failed to create attestation'
+  - 'Error: Resource not accessible by integration'
+root_cause: |
+  actions/attest-build-provenance (introduced GitHub Changelog, May 2024) requires
+  the GITHUB_TOKEN to have the attestations: write scope. This permission did not
+  exist before the attestations feature was released and is NOT included in the
+  GitHub Actions default token permissions, nor in commonly used broad permission
+  sets like contents: write or id-token: write.
+
+  When the workflow omits attestations: write from its permissions block, the
+  action fails with a 403 "Resource not accessible by integration" error. The
+  error message does not explicitly mention "attestations: write" as the missing
+  scope, making the root cause difficult to identify.
+
+  Common mistake: developers copy the attest-build-provenance action from
+  documentation examples or third-party tutorials that may not include the full
+  permissions block, or they use a minimal permissions block that covers other
+  needs (contents: read, packages: write) without adding attestations: write.
+
+  Organization policy note: if the organization has disabled the attestations
+  feature, even a correctly-permissioned workflow will fail. Check org-level
+  Actions settings under Settings > Actions > General.
+fix: |
+  Add attestations: write to the permissions block of the job (or workflow)
+  that runs actions/attest-build-provenance. If using OIDC for cloud auth,
+  id-token: write is also required for the attestation signature.
+fix_code:
+  - language: yaml
+    label: 'Add attestations: write to job permissions'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: read
+            attestations: write   # Required for attest-build-provenance
+            id-token: write       # Required for OIDC-based attestation signing
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build artifact
+              run: make build
+
+            - uses: actions/attest-build-provenance@v2
+              with:
+                subject-path: dist/my-artifact
+  - language: yaml
+    label: 'Container registry publish with attestation'
+    code: |
+      jobs:
+        publish:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: read
+            packages: write
+            attestations: write   # Required
+            id-token: write       # Required
+          steps:
+            - uses: actions/checkout@v4
+            - uses: docker/build-push-action@v6
+              id: push
+              with:
+                push: true
+                tags: ghcr.io/${{ github.repository }}:latest
+            - uses: actions/attest-build-provenance@v2
+              with:
+                subject-name: ghcr.io/${{ github.repository }}
+                subject-digest: ${{ steps.push.outputs.digest }}
+prevention:
+  - 'Always include both attestations: write and id-token: write when using attest-build-provenance'
+  - 'Check action release notes when adding actions that use newer GitHub platform features'
+  - 'The missing scope is not always named in 403 error messages — cross-reference the action docs for required permissions'
+  - 'Enable required_workflows or org-level policies to verify attestation is permitted before deploying'
+docs:
+  - 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 — Using artifact attestations to establish provenance'
+  - url: 'https://github.com/actions/attest-build-provenance'
+    label: 'actions/attest-build-provenance repository'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token'
+    label: 'GitHub Docs — Controlling permissions for GITHUB_TOKEN'

package/errors/permissions-auth/job-level-permissions-replaces-workflow-level.yml

@@ -0,0 +1,123 @@
+id: permissions-auth-034
+title: 'Job-level permissions: block replaces workflow-level permissions — undeclared scopes are silently removed'
+category: permissions-auth
+severity: silent-failure
+tags:
+  - permissions
+  - GITHUB_TOKEN
+  - job-level
+  - workflow-level
+  - 403
+patterns:
+  - regex: 'Resource not accessible by integration'
+    flags: 'i'
+  - regex: 'HttpError.*403'
+    flags: 'i'
+error_messages:
+  - 'Resource not accessible by integration'
+  - 'HttpError: Resource not accessible by integration'
+  - '403 Forbidden'
+root_cause: |
+  The permissions: block in GitHub Actions is a REPLACEMENT at the scope where
+  it is applied — it does NOT inherit or merge with permissions defined at a
+  parent scope.
+
+  Example: if a workflow defines top-level permissions:
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+
+  And a job within that workflow also defines permissions:
+    permissions:
+      deployments: write
+
+  Then that job's GITHUB_TOKEN has ONLY deployments: write. The
+  contents: write, issues: write, and pull-requests: write scopes are
+  completely dropped for that job.
+
+  Developers expect job-level permissions to be ADDITIVE (adding new
+  permissions on top of the workflow-level set). The actual behavior is the
+  opposite: job-level permissions creates an entirely new permission set for
+  that job, discarding all workflow-level grants not re-declared.
+
+  The failure is silent — no warning is emitted about the permission reduction.
+  Steps produce 403 or "Resource not accessible by integration" only when
+  they actually attempt to use the silently-removed permission.
+fix: |
+  When using a job-level permissions: block, re-declare ALL permissions
+  that the job needs — not just the new ones you want to add.
+
+  Alternatively, if all jobs in the workflow need the same permission set,
+  set permissions only at the workflow level and omit job-level overrides.
+
+  Best practice: prefer job-level permissions over workflow-level for the
+  principle of least privilege — each job explicitly declares only what it
+  needs, with no inheritance confusion.
+fix_code:
+  - language: yaml
+    label: 'Wrong: job-level block silently drops workflow-level grants'
+    code: |
+      # Workflow level
+      permissions:
+        contents: write
+        issues: write
+
+      jobs:
+        deploy:
+          permissions:
+            deployments: write   # This REPLACES the above — contents and issues are now GONE
+          steps:
+            - name: Comment on issue
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  # This will 403 — issues: write was silently removed
+                  await github.rest.issues.createComment({ issue_number: 1, body: 'deployed' })
+  - language: yaml
+    label: 'Correct: re-declare all needed permissions at job level'
+    code: |
+      # No workflow-level permissions block needed when using job-level
+
+      jobs:
+        deploy:
+          permissions:
+            contents: write      # Re-declared (was at workflow level)
+            issues: write        # Re-declared (was at workflow level)
+            deployments: write   # New permission added
+          steps:
+            - name: Comment on issue
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  await github.rest.issues.createComment({ issue_number: 1, body: 'deployed' })
+  - language: yaml
+    label: 'Minimal job permissions — each job declares only what it needs'
+    code: |
+      # No workflow-level permissions block — all scoped to jobs
+
+      jobs:
+        test:
+          permissions:
+            checks: write
+            contents: read
+          steps:
+            - uses: actions/checkout@v4
+
+        deploy:
+          permissions:
+            contents: read
+            deployments: write
+            id-token: write
+          steps:
+            - run: echo "deploying"
+prevention:
+  - 'When adding a job-level permissions block, start by listing every permission the job needs from scratch'
+  - 'Do not assume any permissions flow down from the workflow level when a job block is present'
+  - 'Prefer defining all permissions at the job level (not workflow level) to make the permission set explicit'
+  - 'The GitHub Docs explicitly state: permissions at the job level override the workflow-level setting'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token'
+    label: 'GitHub Docs — Controlling permissions for GITHUB_TOKEN'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idpermissions'
+    label: 'GitHub Docs — jobs.<job_id>.permissions syntax'

package/errors/runner-environment/setup-python-version-range-resolves-to-313-distutils-removed.yml

@@ -0,0 +1,107 @@
+id: runner-environment-099
+title: "setup-python python-version '3' resolves to Python 3.13 — distutils and other removed modules cause ImportError"
+category: runner-environment
+severity: error
+tags:
+  - setup-python
+  - python-3-13
+  - distutils
+  - breaking-change
+  - version-pinning
+patterns:
+  - regex: 'ModuleNotFoundError.*distutils'
+    flags: 'i'
+  - regex: 'No module named .distutils.'
+    flags: 'i'
+  - regex: 'ImportError.*distutils'
+    flags: 'i'
+error_messages:
+  - "ModuleNotFoundError: No module named 'distutils'"
+  - "No module named 'distutils'"
+  - "error: can't find distutils"
+root_cause: |
+  Python 3.12 moved distutils into setuptools (no longer stdlib), and Python 3.13
+  fully removed it from the standard library (PEP 632, deprecated since 3.10).
+
+  GitHub Actions workflows using a floating python-version constraint:
+    python-version: '3'
+    python-version: '3.x'
+    python-version: 'latest'
+  ...resolved to Python 3.13 when it became the latest stable release (October 2024).
+  Runner images updated to include 3.13 as the available version for these constraints.
+
+  Any project that imports distutils directly (setup.py, older NumPy, Cython, some
+  SWIG bindings) or tools that internally import it will fail with:
+    ModuleNotFoundError: No module named 'distutils'
+
+  Additional modules removed in Python 3.12-3.13 that break CI:
+  - cgi, imghdr (removed 3.13)
+  - aifc, sunau, chunk, crypt (removed 3.13)
+  - imp module (removed 3.12)
+  - asynchat, asyncore (removed 3.12)
+
+  The failure is from the floating version constraint resolving higher than intended,
+  not from the runner image itself. Pinned workflows on 3.11 or 3.12 are unaffected.
+fix: |
+  Pin python-version to a specific minor version instead of using a floating
+  constraint. If distutils is required, use the setuptools-provided shim.
+
+  Migration options for distutils usage:
+  - Replace distutils.core.setup with setuptools.setup
+  - Replace distutils.util.strtobool with a custom bool parser
+  - Replace distutils.version.LooseVersion with packaging.version.Version
+  - Install setuptools on Python 3.13 to restore the distutils shim
+fix_code:
+  - language: yaml
+    label: 'Pin to specific minor version to avoid 3.13+ resolution'
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'   # Pinned — won't resolve to 3.13+
+          # OR: '3.12'  (distutils still available via setuptools shim)
+  - language: yaml
+    label: 'Use setuptools shim on Python 3.13'
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - name: Install setuptools for distutils compatibility
+        run: pip install setuptools   # Restores distutils shim on 3.13+
+  - language: yaml
+    label: 'Pin version via .python-version file'
+    code: |
+      # .python-version file in repo root:
+      # 3.11.9
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version-file: '.python-version'   # Reads from repo file
+  - language: yaml
+    label: 'Matrix across versions to catch breakage early'
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              python-version: ['3.11', '3.12', '3.13']
+          steps:
+            - uses: actions/setup-python@v5
+              with:
+                python-version: ${{ matrix.python-version }}
+            - run: pip install setuptools   # Shim for 3.13
+            - run: pip install -e .
+            - run: pytest
+prevention:
+  - 'Never use python-version: 3 or python-version: 3.x in production workflows without testing each new minor release'
+  - 'Pin to a specific minor version (3.11, 3.12) or use a .python-version file in the repo'
+  - 'Run CI on a matrix of python versions to catch version-specific breakage early'
+  - 'Audit setup.py for direct distutils imports and replace with setuptools equivalents before upgrading to 3.13'
+docs:
+  - url: 'https://docs.python.org/3/whatsnew/3.13.html#removed-modules'
+    label: 'Python 3.13 — Removed Modules'
+  - url: 'https://peps.python.org/pep-0632/'
+    label: 'PEP 632 — Deprecate distutils'
+  - url: 'https://github.com/actions/setup-python'
+    label: 'actions/setup-python repository'
+  - url: 'https://docs.github.com/en/actions/use-cases-and-examples/building-and-testing/building-and-testing-python'
+    label: 'GitHub Docs — Building and testing Python'

package/errors/silent-failures/composite-action-outputs-not-propagated.yml

@@ -0,0 +1,99 @@
+id: silent-failures-048
+title: 'Composite action outputs not propagated — outputs: declaration required in action.yml'
+category: silent-failures
+severity: silent-failure
+tags:
+  - composite
+  - outputs
+  - action.yml
+  - step-outputs
+  - empty-string
+patterns:
+  - regex: 'steps\.\w+\.outputs\.'
+    flags: 'i'
+error_messages: []
+root_cause: |
+  In composite actions, step outputs from internal steps are NOT automatically
+  visible to the action's callers. The composite action's action.yml must
+  declare an outputs: block that explicitly maps each output name to a value
+  expression referencing an internal step's output:
+
+    outputs:
+      my-result:
+        description: "The result"
+        value: ${{ steps.build.outputs.result }}
+
+  Without this declaration, ${{ steps.my-action.outputs.my-result }} in the
+  calling workflow evaluates to empty string with no error or warning.
+
+  This is different from regular workflow jobs, where step outputs are
+  accessible within the same job via steps.<id>.outputs.<name> without any
+  explicit mapping. Composite actions require explicit wiring because the
+  action boundary creates an isolation layer — internal step IDs are not
+  exposed to callers.
+
+  Common mistake pattern: developer tests the composite action, sees that
+  internal steps set outputs correctly, but the caller always receives "".
+  The action.yml outputs: block is missing or references a wrong step id.
+fix: |
+  1. Open the composite action's action.yml file.
+  2. Add an outputs: block (after the inputs: block if present).
+  3. For each output you need to expose, add an entry with:
+       value: ${{ steps.<internal-step-id>.outputs.<output-name> }}
+  4. Ensure the referenced internal step has a matching id: field.
+  5. Ensure the internal step writes outputs via GITHUB_OUTPUT:
+       echo "result=value" >> $GITHUB_OUTPUT
+fix_code:
+  - language: yaml
+    label: 'action.yml — declare outputs with value expressions'
+    code: |
+      # .github/actions/my-build/action.yml
+      name: 'My Build Action'
+      description: 'Builds the project and returns the version'
+
+      outputs:
+        build-version:
+          description: 'The version that was built'
+          value: ${{ steps.get-version.outputs.version }}
+        artifact-path:
+          description: 'Path to the built artifact'
+          value: ${{ steps.build.outputs.artifact }}
+
+      runs:
+        using: composite
+        steps:
+          - id: get-version
+            shell: bash
+            run: echo "version=$(cat version.txt)" >> $GITHUB_OUTPUT
+
+          - id: build
+            shell: bash
+            run: |
+              make build
+              echo "artifact=dist/app.tar.gz" >> $GITHUB_OUTPUT
+  - language: yaml
+    label: 'Calling workflow — accessing composite action outputs'
+    code: |
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - id: build
+              uses: ./.github/actions/my-build
+
+            - name: Use outputs
+              run: |
+                echo "Version: ${{ steps.build.outputs.build-version }}"
+                echo "Artifact: ${{ steps.build.outputs.artifact-path }}"
+prevention:
+  - 'Every composite action output must have a corresponding entry in the outputs: block of action.yml'
+  - 'Internal steps must have an id: field for the outputs value: expression to reference'
+  - 'The step id in the value: expression must exactly match the internal step id: value'
+  - 'Add a debug step in the action to print $GITHUB_OUTPUT contents when troubleshooting'
+docs:
+  - url: 'https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#outputs-for-composite-actions'
+    label: 'GitHub Docs — Outputs for composite actions'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs'
+    label: 'GitHub Docs — Passing information between jobs'

package/errors/silent-failures/github-output-heredoc-delimiter-collision.yml

@@ -0,0 +1,83 @@
+id: silent-failures-049
+title: 'GITHUB_OUTPUT multiline heredoc value silently truncated when content contains the delimiter string'
+category: silent-failures
+severity: silent-failure
+tags:
+  - GITHUB_OUTPUT
+  - multiline
+  - heredoc
+  - delimiter-collision
+  - environment-files
+patterns:
+  - regex: 'echo\s+\"\w+<<EOF\"'
+    flags: 'i'
+error_messages: []
+root_cause: |
+  GitHub Actions environment files (GITHUB_OUTPUT, GITHUB_ENV, GITHUB_STEP_SUMMARY)
+  use a heredoc-style syntax for multiline values:
+
+    echo "BODY<<EOF" >> $GITHUB_OUTPUT
+    echo "first line" >> $GITHUB_OUTPUT
+    echo "second line" >> $GITHUB_OUTPUT
+    echo "EOF" >> $GITHUB_OUTPUT
+
+  If the multiline content itself contains the exact delimiter string ("EOF" in
+  the example above) on a line by itself, the runner stops reading at that point
+  and silently truncates the value. No error is raised and the step exits 0.
+
+  Common scenarios:
+  1. A release body or commit message that happens to contain "EOF" on its own line.
+  2. A generated file that includes shell script snippets (which often use EOF).
+  3. A changelog that uses EOF as a delimiter in a code example.
+
+  The delimiter collision causes the output variable to contain only the content
+  up to (but not including) the first occurrence of the delimiter string, with
+  no indication that truncation occurred.
+fix: |
+  Use a randomly-generated or sufficiently unique delimiter that will not
+  appear in the content. Common approaches:
+
+  1. Generate a UUID or random hex string at runtime and use it as the delimiter.
+  2. Use a very long, unusual string that is unlikely to appear in content.
+
+  The GitHub documentation explicitly recommends a random delimiter to avoid
+  this collision:
+    https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#multiline-strings
+fix_code:
+  - language: yaml
+    label: 'Unsafe — static delimiter may collide with content'
+    code: |
+      - name: Set multiline output (unsafe)
+        run: |
+          echo "BODY<<EOF" >> $GITHUB_OUTPUT
+          echo "${{ steps.notes.outputs.content }}" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+  - language: yaml
+    label: 'Safe — random delimiter prevents collision'
+    code: |
+      - name: Set multiline output (safe random delimiter)
+        run: |
+          DELIM="ghadelim_$(head -c 16 /dev/urandom | base64 | tr -dc 'a-zA-Z0-9' | head -c 16)"
+          echo "BODY<<${DELIM}" >> $GITHUB_OUTPUT
+          echo "${{ steps.notes.outputs.content }}" >> $GITHUB_OUTPUT
+          echo "${DELIM}" >> $GITHUB_OUTPUT
+  - language: yaml
+    label: 'Windows — PowerShell random delimiter'
+    code: |
+      - name: Set multiline output (PowerShell)
+        shell: pwsh
+        run: |
+          $delim = "ghadelim_$([System.Guid]::NewGuid().ToString('N').Substring(0, 16))"
+          "BODY<<$delim" | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding utf8
+          $releaseNotes | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding utf8
+          $delim | Out-File -FilePath $env:GITHUB_OUTPUT -Append -Encoding utf8
+prevention:
+  - 'Never use a simple static delimiter like EOF, END, or DONE for multiline GITHUB_OUTPUT values'
+  - 'Always use a random or UUID-based delimiter when the content could be dynamic or user-provided'
+  - 'Test multiline output steps with content that deliberately contains common delimiter strings'
+  - 'GitHub docs recommend randomly generated delimiters for all multiline environment file writes'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#multiline-strings'
+    label: 'GitHub Docs — Workflow commands: multiline strings'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables'
+    label: 'GitHub Docs — Store information in variables'

package/errors/triggers/workflow-run-name-mismatch-silent-never-triggers.yml

@@ -0,0 +1,96 @@
+id: triggers-032
+title: 'on.workflow_run.workflows matches name: field not filename — mismatch silently never triggers'
+category: triggers
+severity: warning
+tags:
+  - workflow_run
+  - trigger
+  - name-mismatch
+  - silent
+  - filename
+patterns:
+  - regex: 'workflow_run'
+    flags: ''
+error_messages: []
+root_cause: |
+  The on.workflow_run.workflows: array matches against the target workflow's
+  top-level name: field — NOT the workflow's filename.
+
+  If the target workflow contains:
+    name: CI Pipeline
+
+  then the triggering workflow must specify:
+    on:
+      workflow_run:
+        workflows: ["CI Pipeline"]
+
+  Using the filename ("build.yml", "ci.yml", or ".github/workflows/ci.yml")
+  never matches when a name: field is present. The comparison is case-sensitive:
+  "CI" != "ci" != "Ci".
+
+  Secondary rule: if the target workflow has no name: field, GitHub uses the
+  workflow file path relative to the repo root as the match string (e.g.,
+  ".github/workflows/build.yml").
+
+  No error or warning is produced on mismatch — the triggering workflow
+  silently never fires. This is one of the most common workflow_run
+  misconfiguration patterns on Stack Overflow.
+fix: |
+  1. Open the target workflow file.
+  2. Find the top-level name: field. If absent, note the repo-relative path.
+  3. Use that exact string (case-sensitive) in the workflows: array.
+  4. Merge/deploy the triggering workflow to the default branch — workflow_run
+     only fires when the trigger configuration itself is on the default branch.
+fix_code:
+  - language: yaml
+    label: 'Correct: match the target workflow name: field exactly'
+    code: |
+      # Target workflow file: .github/workflows/ci.yml
+      name: CI Pipeline    # <-- this is what workflow_run matches on
+
+      on: [push]
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "building"
+
+      ---
+      # Triggering workflow file: .github/workflows/deploy.yml
+      on:
+        workflow_run:
+          workflows: ["CI Pipeline"]   # Must match name: exactly (not "ci.yml")
+          types: [completed]
+      jobs:
+        deploy:
+          if: ${{ github.event.workflow_run.conclusion == 'success' }}
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "deploying"
+  - language: yaml
+    label: 'When target workflow has no name: field, use the file path'
+    code: |
+      # Target workflow has no name: field at .github/workflows/build.yml
+      on: [push]
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "building"
+
+      ---
+      # Triggering workflow must use the repo-relative path
+      on:
+        workflow_run:
+          workflows: [".github/workflows/build.yml"]
+          types: [completed]
+prevention:
+  - 'Always add a name: field to every workflow you intend to reference in workflow_run'
+  - 'Copy the name: value exactly (including capitalization and spaces) into workflows:'
+  - 'Add a comment in the triggering workflow citing which file the name came from'
+  - 'workflow_run silently never fires on name mismatches — no diagnostic is emitted'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run'
+    label: 'GitHub Docs — workflow_run trigger'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#name'
+    label: 'GitHub Docs — Workflow name: field'

package/package.json

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