@htekdev/actions-debugger 1.0.74 → 1.0.75

package/errors/known-unsolved/reusable-workflow-local-action-path-resolves-to-called-repo.yml

@@ -0,0 +1,114 @@
+id: known-unsolved-047
+title: "Reusable workflow uses: ./local-action resolves relative to the called repo, not the calling repo"
+category: known-unsolved
+severity: limitation
+tags:
+  - reusable-workflow
+  - composite-action
+  - path-resolution
+  - local-action
+  - cross-repo
+  - limitation
+patterns:
+  - regex: 'Can''t find ''action\.ya?ml'''
+    flags: 'i'
+  - regex: 'Unable to resolve action.*\.\/'
+    flags: 'i'
+  - regex: 'action\.ya?ml.*does not exist'
+    flags: 'i'
+error_messages:
+  - "Can't find 'action.yml', 'action.yaml' or 'Dockerfile' under '/home/runner/work/repo/repo/local-action'"
+  - "Unable to resolve action `./local-action`, unable to find 'action.yaml' or 'action.yml'"
+  - "Error: Can't find 'action.yml' for step uses: ./shared-actions/deploy"
+root_cause: |
+  When a reusable workflow file (stored in org/shared-workflows) contains steps that
+  reference local composite actions using relative paths (uses: ./path/to/action), the
+  path resolves relative to the CALLED (reusable) repository — not the CALLING
+  repository.
+
+  Resolution rule: In any workflow file, uses: ./path always resolves to the root of
+  the repository that CONTAINS the workflow YAML file.
+
+  So in org/shared-workflows/.github/workflows/ci.yml:
+    - uses: ./actions/lint  →  looks in org/shared-workflows/actions/lint/action.yml
+    - Does NOT look in org/app-repo/actions/lint/ (the calling repo)
+
+  This means teams cannot:
+  - Share a reusable workflow that calls composite actions defined in the CALLING repo
+  - Have callers "inject" local actions into a shared reusable workflow via relative paths
+  - Centralize reusable workflows in one repo while composite actions stay in team repos
+
+  This limitation is by design and has been acknowledged by the GitHub Actions team as
+  a fundamental architectural constraint. The calling repository's workspace may be
+  checked out during the job, but action path resolution happens at workflow evaluation
+  time using the workflow file's own repository root, not the runtime workspace.
+fix: |
+  There is no direct fix — this is a platform-level path resolution limitation.
+
+  Option 1 (recommended) — Co-locate composite actions in the same repository as the
+  reusable workflow and reference them with uses: ./path (resolves correctly).
+
+  Option 2 — Publish shared composite actions to a dedicated standalone repository
+  (e.g., org/shared-actions) and reference them with the full path:
+    uses: org/shared-actions/path/to-action@main
+
+  Option 3 — Pass all data that the local action would have computed as inputs to the
+  reusable workflow, removing the need for the caller's local action inside the callee.
+fix_code:
+  - language: yaml
+    label: "Co-locate composite action in the same repo as the reusable workflow"
+    code: |
+      # Repository: org/shared-workflows
+      # Structure:
+      #   .github/
+      #     workflows/
+      #       ci.yml              <- reusable workflow
+      #     actions/
+      #       shared-lint/
+      #         action.yml        <- composite action lives HERE (same repo)
+
+      # In org/shared-workflows/.github/workflows/ci.yml:
+      on:
+        workflow_call:
+          inputs:
+            source-directory:
+              type: string
+              required: true
+
+      jobs:
+        lint:
+          runs-on: ubuntu-latest
+          steps:
+            # Resolves to org/shared-workflows/.github/actions/shared-lint
+            - uses: ./.github/actions/shared-lint
+              with:
+                src-path: ${{ inputs.source-directory }}
+
+  - language: yaml
+    label: "Reference composite action from a standalone shared repo"
+    code: |
+      # Instead of: uses: ./local-action (broken — resolves to reusable workflow's repo)
+      # Use the full repo reference pointing to org/shared-actions:
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: org/shared-actions/deploy@v2
+              with:
+                environment: ${{ inputs.environment }}
+            - uses: org/shared-actions/notify@v2
+              with:
+                status: ${{ job.status }}
+
+prevention:
+  - "Keep reusable workflow files and their local composite action dependencies in the same repository"
+  - "Publish composite actions shared across many repositories to a dedicated org/shared-actions repo"
+  - "Test reusable workflows by calling them from a different repository early in development"
+  - "Document which composite actions a reusable workflow depends on and where they must be located"
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows"
+    label: "GitHub docs — Reusing workflows"
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/about-custom-actions#choosing-a-location-for-your-action"
+    label: "GitHub docs — Choosing a location for your action"
+  - url: "https://github.com/orgs/community/discussions/17244"
+    label: "GitHub Community discussion — local composite action reference from reusable workflow"

package/errors/runner-environment/github-script-require-module-not-found.yml

@@ -0,0 +1,98 @@
+id: runner-environment-136
+title: "actions/github-script require() of third-party npm packages fails with MODULE_NOT_FOUND"
+category: runner-environment
+severity: error
+tags:
+  - github-script
+  - nodejs
+  - require
+  - npm
+  - module-not-found
+  - third-party-package
+patterns:
+  - regex: 'Cannot find module'
+    flags: 'i'
+  - regex: 'MODULE_NOT_FOUND'
+    flags: ''
+error_messages:
+  - "Error: Cannot find module 'axios'"
+  - "Error: Cannot find module 'lodash'"
+  - "Error: Cannot find module 'js-yaml'"
+  - "Error: Cannot find module 'semver'"
+  - "Cannot find module at /home/runner/work/_actions/actions/github-script/v7/lib/async-function.js:1"
+root_cause: |
+  The actions/github-script action executes scripts in a sandboxed Node.js runtime that
+  only includes packages bundled with the action itself. Built-in parameters available
+  in the script context are:
+    - github  — authenticated Octokit client (@octokit/rest)
+    - context — workflow event context
+    - core    — @actions/core
+    - glob    — @actions/glob
+    - io      — @actions/io
+    - exec    — @actions/exec
+    - fetch   — Node.js built-in fetch (Node 18+)
+
+  Any call to require() for packages NOT in this list — such as axios, lodash, js-yaml,
+  semver, chalk, or any other npm package — will fail with MODULE_NOT_FOUND because the
+  packages are not installed in the runner environment that executes the script.
+
+  The action does NOT auto-install packages from the repo's package.json or any other
+  manifest. Node.js module resolution only searches paths within the bundled action's
+  own node_modules directory, which contains only the above built-ins.
+fix: |
+  Option 1 (install before use) — Run npm install in a prior step and reference the
+  package via full path using RUNNER_TEMP or GITHUB_WORKSPACE:
+    - name: Install npm package
+      run: npm install <package-name>
+      working-directory: ${{ runner.temp }}
+    - uses: actions/github-script@v7
+      with:
+        script: |
+          const pkg = require(process.env.RUNNER_TEMP + '/node_modules/<package-name>')
+
+  Option 2 (use built-ins) — Refactor to use only the built-in parameters. For HTTP
+  requests use fetch() instead of axios; for YAML parsing use a run: step with a script
+  file.
+
+  Option 3 (separate Node.js script) — Move complex logic into a .js file in the repo
+  and run it with node in a run: step after npm install, giving full package access.
+fix_code:
+  - language: yaml
+    label: "Install package before github-script and require via RUNNER_TEMP"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+
+        - name: Install axios for github-script
+          run: npm install axios
+          working-directory: ${{ runner.temp }}
+
+        - uses: actions/github-script@v7
+          with:
+            script: |
+              const axios = require(process.env.RUNNER_TEMP + '/node_modules/axios')
+              const { data } = await axios.get('https://api.example.com/status')
+              core.setOutput('api-status', data.status)
+
+  - language: yaml
+    label: "Replace axios with built-in fetch() (Node 18+, no require needed)"
+    code: |
+      steps:
+        - uses: actions/github-script@v7
+          with:
+            script: |
+              // fetch is built-in — no require() needed (Node 18+, github-script v7+)
+              const response = await fetch('https://api.example.com/status')
+              const data = await response.json()
+              core.setOutput('api-status', data.status)
+
+prevention:
+  - "Check the github-script README 'Built-in variables' section before adding require() calls"
+  - "Use fetch() (built-in from Node 18+ / github-script v7+) instead of axios for HTTP requests"
+  - "For complex logic needing many npm packages, use a separate script file with a run: node step"
+  - "Consider caching the npm install step if packages are large or installed frequently"
+docs:
+  - url: "https://github.com/actions/github-script?tab=readme-ov-file#built-in-variables"
+    label: "actions/github-script — Built-in variables (official README)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-github-script-in-a-workflow"
+    label: "GitHub docs — Using GitHub Script in a workflow"

package/errors/silent-failures/env-block-sibling-key-reference-empty-string.yml

@@ -0,0 +1,92 @@
+id: silent-failures-071
+title: "${{ env.VAR }} in a step's env: block evaluates to empty string when VAR is a sibling key in the same block"
+category: silent-failures
+severity: silent-failure
+tags:
+  - env-context
+  - expression
+  - env-block
+  - sibling-reference
+  - empty-string
+  - configuration
+patterns:
+  - regex: 'env\.\w+\}\}.*\{\{\s*env\.\w+'
+    flags: 'i'
+error_messages:
+  - "(no error message — step runs successfully but env var is assigned an incorrect partial value)"
+root_cause: |
+  When multiple environment variables are defined in the same step (or job) env: block
+  and one attempts to compose a value from a sibling key using ${{ env.X }}, the
+  reference silently evaluates to an EMPTY STRING.
+
+  GitHub Actions evaluates all expressions in an env: block BEFORE the step runs, using
+  the env context that exists at that point in time. That context includes:
+    - Variables defined in the workflow-level env: block
+    - Variables defined in the job-level env: block (jobs.<id>.env)
+    - Variables added by previous steps via $GITHUB_ENV
+
+  It does NOT include sibling keys defined elsewhere in the SAME env: block being
+  evaluated. The block is evaluated atomically — each value is expanded using only
+  the env context from BEFORE the block, not from within it.
+
+  Example of the mistake:
+    env:
+      BASE_URL: https://api.example.com    # this is fine
+      FULL_URL: ${{ env.BASE_URL }}/v2     # SILENTLY wrong: evaluates to "/v2"
+
+  FULL_URL becomes "/v2" (not "https://api.example.com/v2") because BASE_URL is not
+  in the env context at the time the step's env: block expressions are evaluated —
+  it is only available AFTER the step starts executing.
+
+  This is a silent failure: no warning is produced, the step succeeds, and the
+  misconfigured variable is silently assigned the wrong value.
+fix: |
+  Option 1 (recommended) — Move the "base" variable to the workflow-level or job-level
+  env: block so it is already in the env context when the step's env: block is evaluated.
+
+  Option 2 — Compose the derived value inside the run: step using shell variable
+  expansion, which operates at runtime when all variables are already set.
+
+  Option 3 — Use an expression based on inputs, vars, or secrets contexts which ARE
+  fully available during env: block evaluation.
+fix_code:
+  - language: yaml
+    label: "Hoist base variable to workflow-level env so it's in context"
+    code: |
+      # Define BASE_URL at workflow level — it will be in the env context
+      env:
+        BASE_URL: https://api.example.com
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Call API
+              run: curl "$FULL_URL"
+              env:
+                # env.BASE_URL is available here because it's defined at workflow level
+                FULL_URL: ${{ env.BASE_URL }}/v2/endpoint
+
+  - language: yaml
+    label: "Compose the value inside run: using shell variable expansion"
+    code: |
+      steps:
+        - name: Call API endpoint
+          run: |
+            # Shell variable composition works at runtime when BASE_URL is already set
+            FULL_URL="${BASE_URL}/v2/endpoint"
+            curl "$FULL_URL"
+          env:
+            BASE_URL: https://api.example.com
+            # FULL_URL built in shell — no need to compose in env: block
+
+prevention:
+  - "Define 'base' env vars at workflow or job level when they need to be referenced by step-level env: blocks"
+  - "Use shell variable composition inside run: steps rather than ${{ env.X }} in the same env: block"
+  - "Verify composed env var values by printing them with echo before use in critical steps"
+  - "Review GitHub Actions context availability documentation when authoring env: blocks"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/variables#using-the-env-context-to-access-environment-variable-values"
+    label: "GitHub docs — Using the env context to access environment variable values"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#context-availability"
+    label: "GitHub docs — Context availability table"

package/errors/triggers/create-event-fires-for-branch-and-tag.yml

@@ -0,0 +1,108 @@
+id: triggers-051
+title: "on: create event fires for both branch and tag creation — must filter with github.ref_type"
+category: triggers
+severity: silent-failure
+tags:
+  - create-event
+  - delete-event
+  - ref-type
+  - tag
+  - branch
+  - trigger-filter
+  - release
+patterns:
+  - regex: 'on:\s*[\r\n]+\s+create:'
+    flags: 'i'
+error_messages:
+  - "(no error message — workflow triggers unexpectedly on branch creation, not just tag creation)"
+root_cause: |
+  The on: create event triggers whenever ANY ref (branch OR tag) is created in the
+  repository. There is no built-in filter to restrict it to only tag creation or only
+  branch creation.
+
+  Many developers use on: create expecting to run release or version-publish workflows
+  only when a version tag is pushed, but the workflow also fires for:
+    - Feature branches created via the GitHub UI or API
+    - Dependabot version update branches (dependabot/npm_and_yarn/...)
+    - Automated branches created by bots or scripts
+    - PR branches created by tooling
+    - Any branch creation event from any actor
+
+  The github.ref_type context variable ('branch' or 'tag') is available in the run
+  context but on: create has no built-in filter for it — an explicit if: condition
+  on the job or step must be used to restrict execution.
+
+  The same behavior applies to on: delete — it fires for both branch and tag deletion.
+fix: |
+  Add an if: condition at the job level (or step level) to filter by github.ref_type:
+
+    jobs:
+      release:
+        if: github.ref_type == 'tag'   # restrict to tag creation only
+
+  Alternative: Use on: push with a tags: filter instead of on: create.
+  The push event with tags: filter is more explicit, supports glob patterns,
+  and does not fire for branch operations at all.
+fix_code:
+  - language: yaml
+    label: "Filter on: create to tags only using ref_type job condition"
+    code: |
+      on:
+        create:
+
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          # Only run for tag creation (e.g., v1.2.3), not branch creation
+          if: github.ref_type == 'tag'
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build and publish release
+              run: echo "Publishing ${{ github.ref_name }}"
+
+  - language: yaml
+    label: "Preferred: use on: push with tags filter for tag-triggered workflows"
+    code: |
+      # More explicit and common pattern for release workflows
+      on:
+        push:
+          tags:
+            - 'v*.*.*'        # triggers on v1.0.0, v2.3.1, etc.
+            # - 'v[0-9]+.*'   # alternative glob
+
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build and publish release
+              run: echo "Publishing ${{ github.ref_name }}"
+
+  - language: yaml
+    label: "Filter on: delete to branch deletion only (e.g., branch cleanup)"
+    code: |
+      on:
+        delete:
+
+      jobs:
+        cleanup:
+          runs-on: ubuntu-latest
+          # Only run for branch deletion, not tag deletion
+          if: github.ref_type == 'branch'
+          steps:
+            - name: Cleanup branch resources
+              run: echo "Cleaning up resources for ${{ github.ref_name }}"
+
+prevention:
+  - "Always add if: github.ref_type == 'tag' when using on: create for release/publish workflows"
+  - "Prefer on: push with tags: filter for tag-triggered release workflows — it's more explicit"
+  - "Add if: github.ref_type == 'branch' when using on: delete for branch cleanup automation"
+  - "Test create/delete workflows by creating a feature branch to verify it does NOT trigger unexpectedly"
+  - "Review all on: create workflows in the repository after adding Dependabot — it creates many branches"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#create"
+    label: "GitHub docs — create event"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#delete"
+    label: "GitHub docs — delete event"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#github-context"
+    label: "GitHub docs — github context (ref_type field)"

package/package.json

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