@htekdev/actions-debugger 1.0.112 → 1.0.114

package/errors/silent-failures/checkout-v6-clean-false-deletes-workspace-on-repo-change.yml

@@ -0,0 +1,119 @@
+id: silent-failures-105
+title: 'checkout@v6 clean: false still deletes workspace when remote URL changes between checkouts'
+category: silent-failures
+severity: silent-failure
+tags:
+  - checkout
+  - clean
+  - workspace
+  - multi-checkout
+  - v6
+  - remote-url
+patterns:
+  - regex: 'Deleting the contents of.*work.*\n.*Initializing the repository'
+    flags: 'i'
+  - regex: 'clean:\s*false[\s\S]{0,500}Deleting the contents of'
+    flags: 'i'
+  - regex: 'git config --local --get remote\.origin\.url[\s\S]{0,200}Deleting the contents'
+    flags: 'i'
+error_messages:
+  - 'Deleting the contents of ''/home/runner/work/myrepo/myrepo'''
+  - 'Deleting the contents of ''/home/runner/work/_temp/...'
+root_cause: |
+  actions/checkout's `clean: false` option prevents `git clean -ffdx` (removing untracked
+  files) but does NOT prevent the action from deleting and reinitializing the entire
+  workspace directory when it detects that the existing `remote.origin.url` does not match
+  the target repository being checked out.
+
+  When multiple checkout steps run in the same job and the second checkout targets a
+  different repository (different org, different repo name, or different URL), the action
+  reads the current `git config --local --get remote.origin.url`, compares it against the
+  target repository URL, and — on mismatch — deletes the entire workspace directory before
+  reinitializing. This deletion happens regardless of `clean: false`.
+
+  Common scenarios that trigger this:
+  1. First step checks out a support/config repo (sparse-checkout of a different repo for
+     shared config), then a second step checks out the main repo with `clean: false`.
+  2. Checking out the main repo first, then a second checkout of a different repo for
+     reading shared scripts, assuming `clean: false` preserves the main workspace.
+  3. Re-using runner workspace across jobs via `clean: false` where the prior job checked
+     out a different repository.
+
+  The log shows the silent deletion in plain text ("Deleting the contents of '...'") but
+  users commonly miss it because the step still succeeds and subsequent steps may not
+  immediately error if they only use the freshly-checked-out content.
+
+  checkout@v5 has the same behavior — this is not a v6 regression. It is documented as
+  expected behavior but is frequently unexpected by users.
+fix: |
+  Option 1 (recommended): Specify `path:` to checkout each repository into a distinct
+  subdirectory, preventing the remote URL mismatch from triggering deletion.
+
+  Option 2: Reverse the order — checkout the main repo last so the deletion (if any)
+  happens to the support repo's files rather than the main workspace.
+
+  Option 3: Accept that `clean: false` cannot preserve workspace contents across
+  checkouts of different repositories sharing the same path, and restructure the workflow
+  to avoid this pattern.
+
+  Option 4: For reading shared scripts/config from another repo, use curl/gh api to fetch
+  specific files rather than a full checkout step.
+fix_code:
+  - language: yaml
+    label: 'Use path: to isolate each checkout to its own directory'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            # Checkout support config into a subdirectory
+            - name: Checkout shared config
+              uses: actions/checkout@v6
+              with:
+                repository: myorg/shared-config
+                ref: v1
+                sparse-checkout: |
+                  nginx/nginx.conf
+                path: .shared-config   # <-- isolated path, no URL conflict
+
+            # Checkout main repo into workspace root (or another path)
+            - name: Checkout source
+              uses: actions/checkout@v6
+              with:
+                fetch-depth: 0
+                # clean: false is now safe — different paths, no URL mismatch
+
+            - name: Use shared config
+              run: cp .shared-config/nginx/nginx.conf ./nginx.conf
+
+  - language: yaml
+    label: 'Fetch individual files without a full checkout to avoid URL conflict'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v6
+              with:
+                fetch-depth: 0
+
+            # Fetch a single file from another repo without a second checkout
+            - name: Fetch shared nginx config
+              env:
+                GH_TOKEN: ${{ github.token }}
+              run: |
+                gh api repos/myorg/shared-config/contents/nginx/nginx.conf \
+                  --jq '.content' | base64 -d > ./nginx.conf
+
+prevention:
+  - 'Use path: on every checkout step when multiple repositories are checked out in the same job'
+  - 'Do not rely on clean: false to preserve workspace content across checkouts of different repositories'
+  - 'Watch for "Deleting the contents of..." lines in checkout step logs — this confirms workspace was reset even with clean: false'
+  - 'When using sparse-checkout for a support repo followed by a main repo checkout, always isolate them into separate path: directories'
+docs:
+  - url: 'https://github.com/actions/checkout/issues/2348'
+    label: 'actions/checkout#2348 — v6 clean: false still deletes workspace files from prior checkout (Feb 2026)'
+  - url: 'https://github.com/actions/checkout#usage'
+    label: 'actions/checkout — clean input documentation'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-workflow-data-as-artifacts'
+    label: 'Storing workflow data — alternative to multi-repo checkout for sharing files'

package/errors/silent-failures/queue-max-silently-ignored-with-cancel-in-progress.yml

@@ -0,0 +1,109 @@
+id: silent-failures-103
+title: "concurrency queue: max silently ignored when cancel-in-progress: true is also set"
+category: silent-failures
+severity: silent-failure
+tags:
+  - concurrency
+  - queue
+  - cancel-in-progress
+  - silent-failure
+  - deployment
+  - serialization
+patterns:
+  - regex: 'This run has been cancelled'
+    flags: 'i'
+  - regex: 'Canceling since a higher priority waiting run was found'
+    flags: 'i'
+  - regex: 'queue:\s*max'
+    flags: 'i'
+error_messages:
+  - "This run has been cancelled."
+  - "Canceling since a higher priority waiting run was found"
+root_cause: |
+  GitHub Actions introduced `queue: max` in May 2026 as a way to allow up to 100
+  pending runs to wait in a concurrency group instead of being cancelled and
+  replaced. Adding `queue: max` to an existing concurrency block without removing
+  `cancel-in-progress: true` results in the `queue: max` setting being silently
+  ignored — no validation error is raised, no warning is emitted.
+
+  The concurrency group continues to cancel pending runs exactly as it did before.
+  The developer believes their deployment queue is now buffering up to 100 runs,
+  but every third commit or concurrent PR merge still cancels the previously queued
+  run, dropping deployments silently.
+
+  The language services editor plugin (VS Code Actions extension) does report a
+  lint error for this combination, but:
+    - Not all teams have the extension installed or enabled.
+    - The Actions UI and `gh` CLI do not surface the conflict at run time.
+    - The workflow file passes schema validation and runs without a reported error.
+
+  The practical symptom is identical to having no `queue: max` at all: runs are
+  still cancelled, the queue never grows beyond one pending run, and deployments
+  are dropped during high-frequency push periods — exactly the problem `queue: max`
+  was supposed to solve.
+fix: |
+  Remove `cancel-in-progress: true` (or omit it entirely, since `false` is the
+  default) when using `queue: max`. These two options are mutually exclusive:
+
+  - `cancel-in-progress: true` — cancel the pending run when a newer run arrives.
+  - `queue: max` — hold up to 100 pending runs in order.
+
+  If you need both semantics (cancel old pending runs for feature branches but queue
+  for main), split into separate concurrency group expressions per ref:
+
+    ```yaml
+    concurrency:
+      group: deploy-${{ github.ref }}
+      cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+      # Do NOT add queue: max when cancel-in-progress may be true
+    ```
+
+  For the main branch where ordered deploys matter, use `queue: max` alone:
+
+    ```yaml
+    concurrency:
+      group: deploy-production
+      queue: max
+      # cancel-in-progress must be omitted or set to false
+    ```
+fix_code:
+  - language: yaml
+    label: "WRONG — queue: max silently ignored when cancel-in-progress: true"
+    code: |
+      concurrency:
+        group: deploy-${{ github.repository }}-${{ github.ref }}
+        cancel-in-progress: true   # ← PROBLEM: negates queue: max
+        queue: max                 # ← silently ignored, no error shown
+  - language: yaml
+    label: "CORRECT — use queue: max without cancel-in-progress"
+    code: |
+      concurrency:
+        group: deploy-${{ github.repository }}-${{ github.ref }}
+        queue: max                  # ← up to 100 pending runs queued
+        # cancel-in-progress is false by default — omit it entirely
+  - language: yaml
+    label: "ADVANCED — cancel-in-progress for branches, queue for main"
+    code: |
+      concurrency:
+        group: deploy-${{ github.repository }}-${{ github.ref }}
+        # Dynamic cancel: cancel feature branch runs (fast feedback), queue
+        # main branch deploys (preserve ordering).
+        cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+        # Note: queue: max cannot be combined with cancel-in-progress.
+        # For main branch serialization without cancel, omit cancel-in-progress
+        # and rely on queue: max in a separate workflow targeting only main.
+prevention:
+  - "When adding `queue: max` to an existing concurrency block, always audit the
+    block for a `cancel-in-progress: true` setting and remove it."
+  - "Install the GitHub Actions VS Code extension — it reports a lint error for
+    `queue: max` + `cancel-in-progress: true` combinations before you push."
+  - "After enabling `queue: max`, verify it works by triggering two rapid pushes
+    and confirming both runs appear in the Actions UI as 'Queued' rather than one
+    being cancelled."
+docs:
+  - url: "https://github.blog/changelog/2026-05-07-github-actions-concurrency-groups-now-allow-larger-queues/"
+    label: "GitHub Changelog: GitHub Actions concurrency groups now allow larger queues (May 7, 2026)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-concurrency"
+    label: "Using concurrency — GitHub Actions documentation"
+  - url: "https://github.com/actions/languageservices/pull/355"
+    label: "actions/languageservices#355: Add queue property to concurrency, validate queue+cancel-in-progress conflict"

package/errors/silent-failures/silent-failures-102.yml

@@ -0,0 +1,141 @@
+id: silent-failures-102
+title: 'Matrix include: Property Boolean Values Coerced to Strings — Conditional Jobs Silently Misbehave'
+category: silent-failures
+severity: silent-failure
+tags:
+  - matrix
+  - include
+  - boolean
+  - string-coercion
+  - if-condition
+  - fromJSON
+patterns:
+  - regex: 'matrix\.[a-z_]+\s*==\s*(?:true|false)\b'
+    flags: 'i'
+  - regex: 'if:\s*\$\{\{\s*matrix\.[a-z_]+\s*\}\}'
+    flags: 'i'
+error_messages:
+  - "if: ${{ matrix.enabled }}"
+  - "if: ${{ matrix.enabled == false }}"
+  - "if: ${{ matrix.deploy == true }}"
+root_cause: |
+  All matrix property values — including those injected via `include:` entries — are coerced to
+  **strings** before expression evaluation at runtime. A matrix property configured as:
+
+  ```yaml
+  strategy:
+    matrix:
+      include:
+        - os: ubuntu-latest
+          enabled: false
+        - os: windows-latest
+          enabled: true
+  ```
+
+  produces `matrix.enabled` equal to the string `"false"` or `"true"`, not the boolean
+  `false` / `true`. This creates two distinct silent failure modes:
+
+  1. `if: ${{ matrix.enabled }}` — the string `"false"` is **truthy** in GitHub Actions expression
+     syntax (non-empty string = true). The job/step **always runs** even when the intent is to skip
+     entries where `enabled: false`.
+
+  2. `if: ${{ matrix.enabled == false }}` — compares a string against a boolean. In GitHub
+     Actions expression syntax, `"false" == false` evaluates to `false` (type mismatch). The
+     condition **always evaluates to false**, silently skipping every include entry regardless
+     of the configured value.
+
+  In both cases the workflow completes without errors or warnings. Only the observable runtime
+  behavior is wrong: jobs that should be skipped always run, or jobs that should run are
+  silently skipped.
+
+  This is distinct from composite action boolean input coercion (silent-failures-004), which
+  covers `inputs.*` properties. Matrix properties have no `type:` annotation — they are always
+  strings at expression evaluation time.
+fix: |
+  Use `fromJSON()` to parse the matrix property string into a native boolean before comparison:
+
+  - `if: ${{ fromJSON(matrix.enabled) }}` ✅ — `fromJSON("false")` → boolean `false` (falsy), skips correctly
+  - `if: ${{ fromJSON(matrix.enabled) == false }}` ✅ — correct boolean comparison
+  - `if: ${{ matrix.enabled }}` ❌ — string `"false"` is truthy, job always runs
+  - `if: ${{ matrix.enabled == false }}` ❌ — string vs boolean comparison, always evaluates to false
+
+  The same `fromJSON()` pattern applies to steps inside the matrix job:
+  ```yaml
+  steps:
+    - name: Deploy step
+      if: ${{ fromJSON(matrix.deploy) }}
+      run: ./deploy.sh
+  ```
+fix_code:
+  - language: yaml
+    label: 'Correct: fromJSON() converts string to native boolean'
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              include:
+                - os: ubuntu-latest
+                  enabled: true
+                  deploy: false
+                - os: windows-latest
+                  enabled: false
+                  deploy: false
+          runs-on: ${{ matrix.os }}
+          # ✅ Correct: fromJSON() parses "false" → boolean false (falsy)
+          if: ${{ fromJSON(matrix.enabled) }}
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Deploy (conditional step)
+              # ✅ Correct: fromJSON() for step-level boolean matrix property
+              if: ${{ fromJSON(matrix.deploy) }}
+              run: echo "Deploying on ${{ matrix.os }}"
+
+  - language: yaml
+    label: 'Wrong: string "false" is truthy — job always runs'
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              include:
+                - os: ubuntu-latest
+                  enabled: true
+                - os: windows-latest
+                  enabled: false
+          runs-on: ${{ matrix.os }}
+          # ❌ Wrong: matrix.enabled is the string "false", which is truthy
+          if: ${{ matrix.enabled }}
+          steps:
+            - run: echo "This always runs even when enabled: false"
+
+  - language: yaml
+    label: 'Wrong: string vs boolean comparison always false'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          strategy:
+            matrix:
+              include:
+                - name: job-a
+                  skip: false
+                - name: job-b
+                  skip: true
+          # ❌ Wrong: "false" == false is always false in Actions expressions
+          if: ${{ matrix.skip == false }}
+          steps:
+            - run: echo "This never runs for any include entry"
+prevention:
+  - 'Always wrap boolean matrix property references in fromJSON() — e.g., if: ${{ fromJSON(matrix.enabled) }}'
+  - 'Add a test matrix entry with the boolean set to false and verify the job is actually skipped before relying on the condition in production'
+  - 'Consider using string sentinel values (e.g., skip: "yes"/"no") and comparing with == to avoid the boolean coercion ambiguity entirely'
+  - 'Document in the workflow that all matrix properties are runtime strings — reviewers often assume boolean values remain boolean'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-a-matrix-for-your-jobs'
+    label: 'Using a matrix for your jobs — GitHub Actions docs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#fromjson'
+    label: 'fromJSON() expression function — GitHub Actions docs'
+  - url: 'https://stackoverflow.com/questions/77059002/how-to-use-matrix-variables-to-conditionally-run-jobs-in-a-github-actions-workfl'
+    label: 'Stack Overflow Q77059002 — matrix boolean coercion and fromJSON() fix'

package/errors/silent-failures/silent-failures-104.yml

@@ -0,0 +1,119 @@
+id: silent-failures-104
+title: '`github.event.inputs.X` Returns Empty String (Not Declared Default) for `on: schedule` and Other Non-Dispatch Triggers — Use `inputs.X` Instead'
+category: silent-failures
+severity: silent-failure
+tags:
+  - github-event-inputs
+  - inputs-context
+  - schedule
+  - workflow-dispatch
+  - multi-trigger
+  - empty-string
+  - default-value
+  - context
+  - boolean-input
+patterns:
+  - regex: 'github\.event\.inputs\.[a-zA-Z_][a-zA-Z0-9_-]*'
+    flags: 'g'
+  - regex: 'on:\s*\n(?:.*\n)*?\s+schedule:'
+    flags: 'im'
+error_messages:
+  - "Deploy target is empty — expected a non-empty value from github.event.inputs.environment"
+  - "Error: Input required and not supplied"
+  - "github.event.inputs.dry_run was '' but expected 'false'"
+root_cause: |
+  Multi-trigger workflows that combine `on: schedule` (or `on: push`, `on: pull_request`,
+  etc.) with `on: workflow_dispatch` commonly read input values via
+  `${{ github.event.inputs.X }}`. This silently produces wrong results for all
+  non-dispatch runs because:
+
+  - **`github.event.inputs.X`** is populated ONLY when the workflow is triggered via
+    `workflow_dispatch`. For every other event type — including `schedule`, `push`,
+    and `pull_request` — `github.event.inputs` is null or an empty object. Accessing a
+    property returns `""` (empty string). The `default:` declared in the `inputs:` block
+    is NEVER applied through this context.
+
+  - **`inputs.X`** correctly returns the declared `default:` value for non-dispatch
+    triggers, and the actual provided value for dispatch-triggered runs.
+
+  **Silent failure patterns:**
+
+  1. **Boolean gate inverted on schedule** — `if: github.event.inputs.dry_run == 'false'`
+     evaluates to `false` on schedule runs (because `"" != "false"`), so deployment steps
+     that should run on the nightly schedule are silently skipped.
+
+  2. **Non-empty guard always fails** — `if: github.event.inputs.target != ''` is always
+     `false` on schedule even when the intended behavior is to run with the default target.
+
+  3. **String comparison breaks** — `${{ github.event.inputs.environment == 'staging' }}`
+     is `false` on schedule because the empty string does not match any environment name.
+
+  Unlike `inputs.X`, `github.event.inputs.X` has no concept of a fallback default — it
+  returns `""` for every non-dispatch event.
+
+  **Distinct from sf-077** (which covers `workflow_call` — where `github.event.inputs`
+  is null because reusable workflows use the `inputs` context, not `github.event.inputs`).
+  **Distinct from sf-072** (which covers the `inputs.X` context being empty on non-dispatch,
+  not the `github.event.inputs.X` context).
+fix: |
+  Replace all `github.event.inputs.X` references with `inputs.X` in any workflow that
+  uses multiple triggers. The `inputs` context is populated for `workflow_dispatch` and
+  `workflow_call` events, and returns the declared `default:` value for all other triggers.
+fix_code:
+  - language: yaml
+    label: "Broken — github.event.inputs.X ignores defaults on schedule runs"
+    code: |
+      on:
+        schedule:
+          - cron: '0 2 * * *'
+        workflow_dispatch:
+          inputs:
+            dry_run:
+              type: boolean
+              default: false
+            environment:
+              type: string
+              default: production
+
+      jobs:
+        deploy:
+          steps:
+            # ❌ On schedule: dry_run="" (not "false"), environment="" (not "production")
+            - run: echo "Env=${{ github.event.inputs.environment }}"
+            # ❌ This if-condition is always false on schedule — step silently skipped!
+            - if: github.event.inputs.dry_run == 'false'
+              run: ./deploy.sh --env ${{ github.event.inputs.environment }}
+  - language: yaml
+    label: "Fixed — use inputs.X which applies declared defaults on all non-dispatch runs"
+    code: |
+      on:
+        schedule:
+          - cron: '0 2 * * *'
+        workflow_dispatch:
+          inputs:
+            dry_run:
+              type: boolean
+              default: false
+            environment:
+              type: string
+              default: production
+
+      jobs:
+        deploy:
+          steps:
+            # ✓ On schedule: dry_run="false", environment="production" (defaults applied)
+            - run: echo "Env=${{ inputs.environment }}"
+            # ✓ Correctly runs on schedule (dry_run defaults to "false")
+            - if: inputs.dry_run == 'false'
+              run: ./deploy.sh --env ${{ inputs.environment }}
+prevention:
+  - "Always use `inputs.X` (not `github.event.inputs.X`) in any workflow with more than one trigger — `inputs.X` applies declared defaults for non-dispatch runs"
+  - "Audit all `github.event.inputs.*` references in workflows that also include `on: schedule`, `on: push`, or `on: pull_request` triggers"
+  - "Add a debug step in the workflow to log `inputs.*` values on each run — catching empty-input regressions before they cause silent deploy failures"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#inputs-context"
+    label: "GitHub Actions inputs context — recommended approach for reading workflow inputs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#context-availability"
+    label: "Context availability — github.event.inputs is only set for workflow_dispatch triggers"
+  - url: "https://github.com/orgs/community/discussions"
+    label: "GitHub Community Discussions — multi-trigger workflows with workflow_dispatch inputs"

package/errors/yaml-syntax/yaml-syntax-068.yml

@@ -0,0 +1,137 @@
+id: yaml-syntax-068
+title: 'Composite Action run: Steps Use Caller Workspace as Working Directory — github.action_path Required for Bundled Scripts'
+category: yaml-syntax
+severity: error
+tags:
+  - composite-action
+  - github-action-path
+  - working-directory
+  - relative-path
+  - script
+  - file-not-found
+patterns:
+  - regex: 'run:\s*\./[^\s]+'
+    flags: 'i'
+  - regex: 'No such file or directory.*\./'
+    flags: 'i'
+  - regex: 'bash:.*\./.*: No such file or directory'
+    flags: 'i'
+error_messages:
+  - "bash: ./scripts/build.sh: No such file or directory"
+  - "/bin/bash: ./entrypoint.sh: No such file or directory"
+  - "Error: Process completed with exit code 127."
+  - "bash: line 1: ./setup.sh: No such file or directory"
+root_cause: |
+  When a composite action (whether local `uses: ./` or published `uses: org/action@v1`) runs a
+  `run:` step, the **working directory is the caller's workspace** (`github.workspace`), not the
+  action's own directory. Any relative path like `run: ./scripts/build.sh` resolves against the
+  caller repository root — not the composite action's repository.
+
+  This affects both published composite actions (referenced as `uses: org/my-action@v1`) and
+  local composite actions stored inside the same repository. Developers commonly write:
+
+  ```yaml
+  # In action.yml of org/my-action
+  runs:
+    using: composite
+    steps:
+      - name: Run bundled script
+        run: ./scripts/build.sh    # ❌ Resolves against CALLER workspace, not action directory
+        shell: bash
+  ```
+
+  When a caller uses `uses: org/my-action@v1`, `./scripts/build.sh` resolves to the caller's
+  `$GITHUB_WORKSPACE/scripts/build.sh`, which does not exist — producing "No such file or
+  directory" or exit code 127.
+
+  **Contrast with JavaScript/Docker actions:** In those action types, the action executes in its
+  own context. Composite actions are different — their steps are injected into the caller's
+  job environment and run with the caller's working directory.
+
+  The correct way to reference files bundled inside a composite action is to use
+  `${{ github.action_path }}`, which always points to the directory containing the action's
+  `action.yml` file, regardless of where the action is called from.
+fix: |
+  Replace relative paths in composite action `run:` steps with `${{ github.action_path }}/`:
+
+  ```yaml
+  # In action.yml
+  runs:
+    using: composite
+    steps:
+      - name: Run bundled script
+        run: ${{ github.action_path }}/scripts/build.sh   # ✅ Always resolves to action directory
+        shell: bash
+  ```
+
+  If the script must be made executable, add a `chmod` step using `github.action_path`:
+
+  ```yaml
+  steps:
+    - name: Make script executable
+      run: chmod +x ${{ github.action_path }}/scripts/build.sh
+      shell: bash
+
+    - name: Run bundled script
+      run: ${{ github.action_path }}/scripts/build.sh
+      shell: bash
+  ```
+
+  `github.action_path` is always set to the directory of the currently executing action's
+  `action.yml`, even for deeply nested composite actions calling other composite actions.
+fix_code:
+  - language: yaml
+    label: 'Correct: github.action_path for bundled scripts'
+    code: |
+      # In action.yml of your composite action (org/my-action)
+      name: 'My Action'
+      description: 'Does something useful'
+      runs:
+        using: composite
+        steps:
+          - name: Make script executable
+            run: chmod +x ${{ github.action_path }}/scripts/build.sh
+            shell: bash
+
+          - name: Run bundled build script
+            # ✅ github.action_path always points to the action's directory
+            run: ${{ github.action_path }}/scripts/build.sh
+            shell: bash
+
+          - name: Run inline Python from action directory
+            run: python ${{ github.action_path }}/tools/generate.py
+            shell: bash
+
+  - language: yaml
+    label: 'Wrong: relative path resolves against caller workspace'
+    code: |
+      # In action.yml of your composite action (org/my-action)
+      name: 'My Action'
+      runs:
+        using: composite
+        steps:
+          - name: Run bundled script
+            # ❌ Wrong: ./scripts/build.sh resolves against the CALLER's $GITHUB_WORKSPACE
+            # Fails with: bash: ./scripts/build.sh: No such file or directory
+            run: ./scripts/build.sh
+            shell: bash
+
+          # ❌ Also wrong: explicitly using github.workspace points to caller repo root
+          - name: Run script using workspace
+            run: ${{ github.workspace }}/scripts/build.sh
+            shell: bash
+
+prevention:
+  - 'Never use relative paths (./path) or github.workspace in composite action run: steps to reference the action''s own bundled files — always use github.action_path'
+  - 'Test composite actions by calling them from a separate test repository, not just the same repository where they are defined — relative paths that work locally (same repo) silently break when called externally'
+  - 'Add a step to verify the script exists at the expected path as the first step of your composite action during development: run: ls ${{ github.action_path }}/scripts/'
+  - 'Composite actions that call other composite actions each get their own github.action_path — do not pass it between actions as an input'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#github-context'
+    label: 'github.action_path context — GitHub Actions docs'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action'
+    label: 'Creating a composite action — GitHub Actions docs'
+  - url: 'https://github.com/actions/runner/issues/1348'
+    label: 'actions/runner#1348 — Local composite actions always relative to top level repository'
+  - url: 'https://stackoverflow.com/questions/77033208/github-action-composite-type-not-working-in-other-repositories-due-to-missing'
+    label: 'Stack Overflow — Composite action not working in other repositories due to missing action files'