@htekdev/actions-debugger 1.0.59 → 1.0.60

package/errors/permissions-auth/github-token-cross-repo-dispatch-limitation.yml

@@ -0,0 +1,115 @@
+id: permissions-auth-043
+title: 'GITHUB_TOKEN cannot dispatch workflows or events in other repositories'
+category: permissions-auth
+severity: error
+tags:
+  - GITHUB_TOKEN
+  - repository_dispatch
+  - workflow_dispatch
+  - cross-repo
+  - 404
+  - permissions
+patterns:
+  - regex: 'Resource not accessible by integration'
+    flags: 'i'
+  - regex: '404.*dispatches|dispatches.*404'
+    flags: 'i'
+  - regex: 'HttpError: Not Found'
+    flags: 'i'
+error_messages:
+  - 'Resource not accessible by integration'
+  - 'HttpError: Not Found'
+  - '{"message":"Not Found","documentation_url":"https://docs.github.com/rest/repos/repos#create-a-repository-dispatch-event"}'
+  - 'RequestError [HttpError]: Not Found'
+root_cause: |
+  GITHUB_TOKEN is automatically scoped to the repository where the workflow
+  runs. It cannot authenticate to any other repository, regardless of what is
+  declared in the workflow's permissions block. The permissions block controls
+  only the scopes of the automatically-generated token for the CURRENT repo —
+  it has no effect on access to other repositories.
+
+  Attempts to call the GitHub REST API against a different repository —
+  including POST /repos/{owner}/{other-repo}/dispatches (repository_dispatch)
+  or POST /repos/{owner}/{other-repo}/actions/workflows/{id}/dispatches
+  (workflow_dispatch) — return 404 Not Found. GitHub returns 404 rather than
+  403 to avoid leaking information about whether the target repository exists
+  or is private.
+
+  This is a hard authentication boundary enforced by GitHub's token system,
+  not a configuration issue. No amount of permissions: adjustments in the
+  workflow file can grant the automatic GITHUB_TOKEN cross-repository access.
+
+  Note: this is distinct from the GITHUB_TOKEN loopback limitation (where
+  GITHUB_TOKEN cannot trigger new workflow runs in the SAME repository). This
+  error applies to any cross-repository API call.
+fix: |
+  Replace GITHUB_TOKEN with a credential that has access to the target
+  repository: a Personal Access Token (PAT) with repo scope, or a GitHub App
+  installation token scoped to both repositories. Store the credential as an
+  encrypted repository or organization secret.
+
+  GitHub Apps with installation tokens are the recommended approach for
+  production cross-repo automation — they provide fine-grained permissions,
+  do not depend on a specific user account, and tokens are automatically
+  rotated.
+fix_code:
+  - language: yaml
+    label: 'Use a PAT secret for cross-repo repository_dispatch'
+    code: |
+      jobs:
+        trigger-downstream:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Dispatch event to other repository
+              uses: actions/github-script@v7
+              with:
+                github-token: ${{ secrets.CROSS_REPO_PAT }}
+                script: |
+                  await github.rest.repos.createDispatchEvent({
+                    owner: 'my-org',
+                    repo: 'other-repo',
+                    event_type: 'build-triggered',
+                    client_payload: {
+                      ref: context.ref,
+                      sha: context.sha
+                    }
+                  });
+  - language: yaml
+    label: 'Use a GitHub App installation token for cross-repo workflow dispatch (recommended)'
+    code: |
+      jobs:
+        trigger-downstream:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Generate GitHub App installation token
+              id: app-token
+              uses: actions/create-github-app-token@v1
+              with:
+                app-id: ${{ vars.APP_ID }}
+                private-key: ${{ secrets.APP_PRIVATE_KEY }}
+                owner: my-org
+                repositories: other-repo
+
+            - name: Dispatch workflow in other repository
+              uses: actions/github-script@v7
+              with:
+                github-token: ${{ steps.app-token.outputs.token }}
+                script: |
+                  await github.rest.actions.createWorkflowDispatch({
+                    owner: 'my-org',
+                    repo: 'other-repo',
+                    workflow_id: 'deploy.yml',
+                    ref: 'main'
+                  });
+prevention:
+  - 'Never use ${{ secrets.GITHUB_TOKEN }} in API calls targeting other repositories — it will always 404'
+  - 'Prefer GitHub Apps with installation tokens over PATs for cross-repo automation — scoped, auto-rotating, and not tied to a user account'
+  - 'Store cross-repo PATs as organization secrets so they are reusable across multiple source repositories without per-repo duplication'
+  - 'When debugging 404 on dispatch endpoints, first check whether the token is GITHUB_TOKEN vs a PAT — this is the most common cause'
+docs:
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token'
+    label: 'GitHub Docs: Permissions for the GITHUB_TOKEN'
+  - url: 'https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow'
+    label: 'GitHub Docs: Authenticating with a GitHub App in GitHub Actions'
+  - url: 'https://github.com/orgs/community/discussions/26724'
+    label: 'GitHub Community: GITHUB_TOKEN cannot dispatch to another repository'

package/errors/silent-failures/reusable-workflow-outputs-undeclared-workflow-level.yml

@@ -0,0 +1,95 @@
+id: silent-failures-060
+title: 'Reusable workflow outputs not declared at on.workflow_call.outputs are silently empty in callers'
+category: silent-failures
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - workflow_call
+  - outputs
+  - empty-string
+  - silent-failure
+patterns:
+  - regex: 'needs\.[a-z][a-z0-9_-]*\.outputs\.[a-z][a-z0-9_-]*'
+    flags: 'i'
+error_messages:
+  - '(no error emitted — callers receive empty strings silently)'
+  - 'Error: Input required and not supplied'
+root_cause: |
+  Reusable workflows require a two-level output declaration. Developers
+  correctly declare job-level outputs under jobs.<job-id>.outputs, but omit
+  the second required declaration: the workflow-level outputs block under
+  on.workflow_call.outputs.
+
+  Without the workflow-level outputs declaration, any caller that references
+  ${{ needs.<call-job>.outputs.<name> }} receives an empty string. GitHub
+  Actions does not emit any error, warning, or annotation — downstream steps
+  silently receive empty values, producing wrong behavior or spurious failures
+  (e.g., artifact path is empty, deployment target is blank).
+
+  The root cause is that GitHub's reusable workflow output model requires two
+  separate declarations:
+    1. job.outputs: maps a step output to a job-scoped output
+    2. on.workflow_call.outputs: hoists a job output up to the workflow level
+       so external callers can reference it
+
+  Omitting level 2 is invisible — the job output exists internally but is
+  never exposed to the calling workflow.
+fix: |
+  Add an outputs block directly under on.workflow_call that maps each desired
+  workflow output name to ${{ jobs.<job-id>.outputs.<output-name> }}. This is
+  in addition to (not a replacement for) the job-level outputs block.
+fix_code:
+  - language: yaml
+    label: 'Reusable workflow: declare outputs at both job level and on.workflow_call level'
+    code: |
+      on:
+        workflow_call:
+          outputs:
+            build-version:
+              description: 'The semantic version produced by this workflow'
+              value: ${{ jobs.build.outputs.build-version }}
+            artifact-path:
+              description: 'Path to the uploaded artifact'
+              value: ${{ jobs.build.outputs.artifact-path }}
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            build-version: ${{ steps.version.outputs.version }}
+            artifact-path: ${{ steps.upload.outputs.artifact-path }}
+          steps:
+            - id: version
+              run: echo "version=1.2.3" >> "$GITHUB_OUTPUT"
+              shell: bash
+            - id: upload
+              uses: actions/upload-artifact@v4
+              with:
+                name: my-artifact
+                path: dist/
+  - language: yaml
+    label: 'Calling workflow: access reusable workflow outputs via needs context'
+    code: |
+      jobs:
+        call-build:
+          uses: ./.github/workflows/build.yml
+
+        deploy:
+          needs: call-build
+          runs-on: ubuntu-latest
+          steps:
+            - name: Use build outputs
+              run: |
+                echo "Version: ${{ needs.call-build.outputs.build-version }}"
+                echo "Artifact: ${{ needs.call-build.outputs.artifact-path }}"
+              shell: bash
+prevention:
+  - 'Always declare outputs under on.workflow_call.outputs in addition to any job-level outputs blocks — they are two distinct YAML nodes'
+  - 'Immediately echo needs.<call-job>.outputs.* in the caller after wiring up to verify outputs are populated during development'
+  - 'Use actionlint locally or in CI to catch missing workflow-level output declarations before they ship'
+  - 'Treat the two-level declaration as a checklist: job outputs block + workflow_call outputs block'
+docs:
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#using-outputs-from-a-reusable-workflow'
+    label: 'GitHub Docs: Using outputs from a reusable workflow'
+  - url: 'https://github.com/orgs/community/discussions/17245'
+    label: 'GitHub Community: Outputs from reusable workflow missing in caller'

package/errors/triggers/pull-request-target-checkout-base-branch.yml

@@ -0,0 +1,101 @@
+id: triggers-044
+title: 'pull_request_target checks out base branch by default — PR head requires explicit ref'
+category: triggers
+severity: silent-failure
+tags:
+  - pull_request_target
+  - checkout
+  - ref
+  - base-branch
+  - security
+  - fork
+patterns:
+  - regex: 'on:\s*\n\s*pull_request_target'
+    flags: 'im'
+  - regex: 'uses:\s*actions/checkout.*\n(?!.*ref:)'
+    flags: 'im'
+error_messages:
+  - '(no error — workflow runs against base branch code, not PR changes)'
+root_cause: |
+  pull_request_target runs in the context of the BASE repository rather than
+  the contributor's fork. This is an intentional security boundary: because
+  the workflow has access to repository secrets and typically runs with write
+  permissions, GitHub executes it against trusted code on the base branch
+  rather than potentially untrusted PR code.
+
+  As a direct consequence, actions/checkout without an explicit ref: parameter
+  checks out the TARGET BRANCH (e.g., main), not the contributor's changes.
+  The workflow appears to run successfully — tests pass, linters pass — but
+  only because they are testing the existing base branch code. The PR's actual
+  changes are completely ignored. CI gives a false green for every PR
+  regardless of what was submitted.
+
+  This is among the most common misuses of pull_request_target, appearing
+  frequently in workflows that were migrated from pull_request to gain write
+  access (e.g., to post PR comments or add labels) without understanding the
+  checkout difference.
+fix: |
+  If the goal is to build and test PR code, use on: pull_request instead of
+  pull_request_target. pull_request runs in the fork context with limited
+  permissions, which is the correct and safe choice for CI testing.
+
+  Reserve pull_request_target only for operations that specifically need write
+  permissions or secrets AND that do NOT execute untrusted PR code (e.g.,
+  adding labels based on event metadata, posting a comment using a stored
+  token). If pull_request_target must check out PR code, consult the GitHub
+  Security Lab advisory on pwn requests first — the attack surface is
+  significant.
+fix_code:
+  - language: yaml
+    label: 'Preferred: use pull_request for code testing workflows (runs against PR head safely)'
+    code: |
+      on:
+        pull_request:
+          branches: [main]
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: read
+          steps:
+            - uses: actions/checkout@v4
+              # No ref needed — pull_request automatically checks out the merge commit
+            - run: npm ci && npm test
+              shell: bash
+  - language: yaml
+    label: 'Safe pull_request_target: metadata-only operations — no checkout of PR code'
+    code: |
+      on:
+        pull_request_target:
+          types: [opened, synchronize, labeled]
+
+      jobs:
+        label:
+          runs-on: ubuntu-latest
+          permissions:
+            pull-requests: write
+          steps:
+            # Safe: uses only github.event data, does NOT check out PR code
+            - name: Add triage label
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  await github.rest.issues.addLabels({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    issue_number: context.payload.pull_request.number,
+                    labels: ['needs-review']
+                  });
+prevention:
+  - 'Default to on: pull_request for all CI testing workflows — it checks out PR code correctly and runs with limited permissions'
+  - 'Only use pull_request_target when write permissions or secrets are required AND untrusted PR code is never executed'
+  - 'If pull_request_target is in a workflow, verify there is NO actions/checkout step (or that it explicitly uses a trusted ref)'
+  - 'Review the GitHub Security Lab pwn requests advisory before combining pull_request_target with any form of code execution from the PR'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_target'
+    label: 'GitHub Docs: pull_request_target event'
+  - url: 'https://securitylab.github.com/research/github-actions-preventing-pwn-requests/'
+    label: 'GitHub Security Lab: Preventing pwn requests in GitHub Actions'
+  - url: 'https://github.com/orgs/community/discussions/15669'
+    label: 'GitHub Community: pull_request_target and checkout behavior'

package/errors/yaml-syntax/composite-action-run-step-missing-shell.yml

@@ -0,0 +1,93 @@
+id: yaml-syntax-042
+title: 'Composite action run steps require explicit shell property — no default shell is applied'
+category: yaml-syntax
+severity: error
+tags:
+  - composite-action
+  - shell
+  - run-step
+  - action-yaml
+  - validation-error
+patterns:
+  - regex: 'Required property is missing: shell'
+    flags: 'i'
+  - regex: 'The `shell` property must be set'
+    flags: 'i'
+  - regex: 'shell is required for `run` step in composite action'
+    flags: 'i'
+error_messages:
+  - 'Required property is missing: shell'
+  - 'The `shell` property must be set for step `run` in composite actions'
+  - "Error: Unexpected value ''"
+root_cause: |
+  Regular workflow jobs default to bash on Linux and macOS, and pwsh on
+  Windows, when the shell property is omitted from a run step. Composite
+  actions (using: composite) do not inherit any default shell — every run
+  step must explicitly declare a shell value such as bash, pwsh, sh, or cmd.
+
+  This inconsistency frequently catches developers who copy run steps from a
+  workflow job into a composite action's action.yml without adding shell: bash.
+  The error surfaces immediately on the first run and is caught by the runner's
+  action schema validation, but the message can be confusing because shell is
+  a property developers rarely need to specify in regular workflows.
+
+  The GitHub Actions runner enforces this requirement because composite actions
+  must be portable across multiple callers (Linux, macOS, Windows) and the
+  runner has no basis to assume which shell is appropriate without the caller
+  specifying one.
+fix: |
+  Add shell: bash (or shell: pwsh on Windows-targeted steps, shell: sh for
+  minimal Alpine images) to every run step in the composite action's
+  action.yml. If the action must support multiple operating systems, use a
+  conditional expression to select the shell based on runner.os.
+fix_code:
+  - language: yaml
+    label: 'action.yml: add explicit shell to every run step in a composite action'
+    code: |
+      name: My Composite Action
+      description: 'Example composite action with correct shell declarations'
+      runs:
+        using: composite
+        steps:
+          - name: Install dependencies
+            run: npm ci
+            shell: bash
+
+          - name: Build
+            run: npm run build
+            shell: bash
+
+          - name: Run tests
+            run: npm test
+            shell: bash
+  - language: yaml
+    label: 'Cross-platform composite action: select shell via runner.os expression'
+    code: |
+      runs:
+        using: composite
+        steps:
+          - name: Platform-aware step
+            run: echo "Running on ${{ runner.os }}"
+            shell: ${{ runner.os == 'Windows' && 'pwsh' || 'bash' }}
+
+          - name: Windows-only step
+            if: runner.os == 'Windows'
+            run: Write-Host "Windows step"
+            shell: pwsh
+
+          - name: Unix step
+            if: runner.os != 'Windows'
+            run: echo "Unix step"
+            shell: bash
+prevention:
+  - 'Add shell: bash to every run step when authoring or editing a composite action — treat it as required boilerplate'
+  - 'Use actionlint or the VS Code GitHub Actions extension to surface missing shell properties before committing'
+  - 'Keep a composite action template or snippet that includes shell: bash by default in every run step'
+  - 'When converting a workflow job to a composite action, do a search for all run: blocks and add shell: to each'
+docs:
+  - url: 'https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#runsusing-for-composite-actions'
+    label: 'GitHub Docs: Metadata syntax for composite actions'
+  - url: 'https://github.com/actions/runner/issues/835'
+    label: 'actions/runner #835: Composite actions should have a default shell'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsshell'
+    label: 'GitHub Docs: Workflow syntax — steps.shell'

package/package.json

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