@htekdev/actions-debugger 1.0.56 → 1.0.58

package/errors/caching-artifacts/caching-artifacts-038.yml

@@ -0,0 +1,95 @@
+id: caching-artifacts-038
+title: "hashFiles() returns empty string when no matching files found — constant cache key causes cross-branch cache pollution"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - hashFiles
+  - cache-key
+  - silent-failure
+  - cross-branch
+  - lock-file
+patterns:
+  - regex: 'hashfiles\s*\(.*\)\s*==\s*''"""'
+    flags: 'i'
+  - regex: 'cache-hit.*true.*hashfiles.*empty'
+    flags: 'i'
+error_messages:
+  - "Cache restored successfully"
+  - "Cache hit: true"
+root_cause: |
+  The `hashFiles()` expression function returns an empty string when no files match the
+  provided glob pattern. It does NOT throw an error or fail the step.
+
+  A common pattern is:
+    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+  If `package-lock.json` does not exist (e.g., using yarn, pnpm, or no lock file present),
+  `hashFiles('**/package-lock.json')` returns `""` and the key becomes:
+    "Linux-node-"
+
+  This constant key means every workflow run hits the same cache entry regardless of
+  dependency changes or branch. The first job saves its node_modules under this key, and
+  every subsequent run on every branch restores those same cached modules. This silently
+  masks dependency update failures or serves stale packages from a different branch's state.
+
+  The failure is invisible: `cache-hit: true` appears in logs and the job succeeds, hiding
+  the fact that no lock file was actually hashed. Developers notice only when flaky test
+  failures or "wrong version installed" errors occur.
+fix: |
+  Use the correct lock file for your package manager, or add a fallback to prevent a
+  constant key when hashFiles returns empty.
+
+  Option 1: Use the correct lock file:
+    - npm: **/package-lock.json
+    - yarn: **/yarn.lock
+    - pnpm: **/pnpm-lock.yaml
+    - pip: **/requirements.txt or **/poetry.lock
+
+  Option 2: Add a github.run_id fallback to ensure key uniqueness when files are missing:
+    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') || github.run_id }}
+
+  Option 3: Use hashFiles with multiple patterns so at least one matches:
+    key: ${{ runner.os }}-deps-${{ hashFiles('**/package-lock.json', '**/yarn.lock', '**/pnpm-lock.yaml') }}
+
+  Option 4: Add a validation step to fail fast if no lock file is found rather than
+  silently using a constant cache key.
+fix_code:
+  - language: yaml
+    label: "run_id fallback prevents constant cache key when lock file is absent"
+    code: |
+      - name: Cache node modules
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          # hashFiles returns "" if no lock file found; run_id fallback prevents constant key
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') || github.run_id }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+  - language: yaml
+    label: "Multi-ecosystem lock file glob — matches whichever lock file is present"
+    code: |
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            ~/.yarn/cache
+            ~/.pnpm-store
+          key: ${{ runner.os }}-deps-${{ hashFiles('**/package-lock.json', '**/yarn.lock', '**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-deps-
+prevention:
+  - "Verify your lock file glob matches an actual file before relying on it for cache key uniqueness"
+  - "Add || github.run_id fallback: hashFiles('...') || github.run_id prevents silent constant-key caching"
+  - "Use restore-keys as a fallback strategy rather than depending on an exact key hit"
+  - "In setup steps, validate the expected lock file exists before caching (e.g., Test-Path package-lock.json)"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#hashfiles"
+    label: "GitHub Docs — hashFiles() expression function"
+  - url: "https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows"
+    label: "GitHub Docs — Caching dependencies to speed up workflows"
+  - url: "https://github.com/actions/cache/blob/main/tips-and-workarounds.md"
+    label: "actions/cache — Tips and workarounds"
+  - url: "https://github.com/orgs/community/discussions/25064"
+    label: "GitHub Community — hashFiles returns empty when no files match"

package/errors/caching-artifacts/caching-artifacts-039.yml

@@ -0,0 +1,110 @@
+id: caching-artifacts-039
+title: "actions/cache split save/restore: path must match exactly or restore silently reports cache miss"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - actions/cache
+  - save-restore
+  - path-mismatch
+  - cache-miss
+  - split-cache
+patterns:
+  - regex: 'Cache not found for input keys'
+    flags: 'i'
+  - regex: 'cache/restore.*path.*not.*found'
+    flags: 'i'
+error_messages:
+  - "Cache not found for input keys: <key>"
+  - "No cache found for key: <key>"
+root_cause: |
+  When using the split `actions/cache/save@v4` and `actions/cache/restore@v4` actions
+  separately (rather than the combined `actions/cache@v4`), the `path:` value in the
+  restore step must exactly match the `path:` value used in the save step — including
+  relative vs absolute paths, trailing slashes, and directory names.
+
+  If the paths differ even slightly, the cache entry is stored under a hash that
+  incorporates the path value. The restore step computes a different hash and reports
+  "Cache not found for input keys" — identical to the message shown when the cache key
+  itself is wrong. Nothing in the error output indicates that a path mismatch is the
+  actual cause, making this extremely difficult to debug.
+
+  This is an intentional implementation detail of the split actions: the combined
+  `actions/cache@v4` avoids this because the same `path:` string is used for both
+  operations automatically. Developers migrating from the combined action to split
+  save/restore for more granular control frequently encounter this.
+
+  Common path mismatch pitfalls:
+  - Save uses `./node_modules`, restore uses `node_modules` (leading `./` difference)
+  - Save uses `/home/runner/.cache/pip`, restore uses `~/.cache/pip`
+  - Save uses a trailing slash `dist/`, restore uses `dist`
+  - Save in one job uses a relative path that resolves differently in another job
+fix: |
+  Ensure the `path:` value in `actions/cache/restore@v4` is the exact same string
+  as used in the corresponding `actions/cache/save@v4` step. Copy-paste the value
+  rather than retyping it to prevent subtle differences.
+
+  When using the split actions across different jobs, prefer absolute paths or paths
+  anchored from a stable workspace directory. Alternatively, use the combined
+  `actions/cache@v4` with `save-always: true` to avoid managing save/restore separately.
+fix_code:
+  - language: yaml
+    label: "Identical path values in split save and restore steps"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Restore cached build output
+              uses: actions/cache/restore@v4
+              id: cache-restore
+              with:
+                path: .cache/build-output    # Must match save step below exactly
+                key: build-${{ github.sha }}
+                restore-keys: build-
+
+            - name: Build
+              if: steps.cache-restore.outputs.cache-hit != 'true'
+              run: npm run build
+
+            - name: Save build cache
+              if: steps.cache-restore.outputs.cache-hit != 'true'
+              uses: actions/cache/save@v4
+              with:
+                path: .cache/build-output    # Copy-pasted from restore step — no differences
+                key: build-${{ github.sha }}
+
+  - language: yaml
+    label: "Combined cache action avoids path mismatch entirely"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Cache build output
+              uses: actions/cache@v4
+              with:
+                path: .cache/build-output
+                key: build-${{ github.sha }}
+                restore-keys: build-
+                save-always: true            # Always saves even when cache-hit is true
+
+            - run: npm run build
+prevention:
+  - "Copy-paste the path value between save and restore steps — never retype it"
+  - "Use the combined actions/cache@v4 with save-always: true unless you specifically need split save/restore behavior"
+  - "Prefer absolute paths (e.g., /home/runner/.cache/pip) over relative paths when save and restore are in different jobs"
+  - "When debugging cache misses, add a run: echo '${{ toJSON(steps.cache.outputs) }}' step to inspect what the cache lookup returned"
+docs:
+  - url: "https://github.com/actions/cache/blob/main/save/README.md"
+    label: "actions/cache/save — README"
+  - url: "https://github.com/actions/cache/blob/main/restore/README.md"
+    label: "actions/cache/restore — README"
+  - url: "https://github.com/actions/cache/issues/1444"
+    label: "GitHub Issue #1444 — Path mismatch causes misleading cache miss error"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows"
+    label: "GitHub Docs — Caching dependencies to speed up workflows"

package/errors/caching-artifacts/caching-artifacts-040.yml

@@ -0,0 +1,112 @@
+id: caching-artifacts-040
+title: "actions/download-artifact@v4 cross-workflow download silently returns no artifacts without actions: read permission"
+category: caching-artifacts
+severity: error
+tags:
+  - download-artifact
+  - v4
+  - cross-workflow
+  - permissions
+  - actions-read
+  - run-id
+  - breaking-change
+patterns:
+  - regex: 'Unable to find any artifacts for the associated workflow'
+    flags: 'i'
+  - regex: 'No artifacts found for the associated workflow run'
+    flags: 'i'
+  - regex: 'run-id:.*\d+'
+    flags: 'i'
+  - regex: 'Resource not accessible by integration'
+    flags: 'i'
+error_messages:
+  - "Unable to find any artifacts for the associated workflow"
+  - "No artifacts found for the associated workflow run"
+  - "Resource not accessible by integration"
+  - "Error: Artifact download failed: 403 Forbidden"
+root_cause: |
+  actions/download-artifact@v4 introduced the ability to download artifacts produced
+  by a *different* workflow run (not just the current run) by specifying the `run-id`
+  input. This cross-workflow download requires the `actions: read` permission on the
+  GITHUB_TOKEN.
+
+  Workflows that do not explicitly declare `permissions: actions: read` will use the
+  default GITHUB_TOKEN permissions. In repositories where the default token permissions
+  are set to "read for all" at the org level, `actions` read may be granted by default
+  — but in repositories with restrictive default permissions or when only specific
+  permissions are declared in the workflow, `actions: read` is NOT automatically
+  included.
+
+  The misleading aspect is the error message: "Unable to find any artifacts for the
+  associated workflow" suggests the artifact does not exist, when in fact the issue is
+  a 403 permission denial. The action does not distinguish between "artifact not found"
+  and "access denied" in its error output.
+
+  This is a new permission requirement introduced in v4 that did not exist in v3
+  (which only supported downloading from the current workflow run and did not need
+  `actions` read access).
+
+  Common trigger scenario: a workflow that processes artifacts from a different trigger
+  (e.g., a deployment workflow that downloads build artifacts from a build workflow run)
+  is upgraded from download-artifact@v3 to @v4 and the `run-id` input is added — but
+  the required `permissions: actions: read` block is not added.
+fix: |
+  Add `actions: read` to the permissions block of the job or workflow that uses
+  `actions/download-artifact@v4` with a `run-id` input referencing a different workflow.
+
+  If the workflow or job already has a `permissions` block, add `actions: read` to it.
+  If there is no `permissions` block, add one with the minimum required permissions
+  including `actions: read` and `contents: read`.
+fix_code:
+  - language: yaml
+    label: "Add actions: read permission for cross-workflow artifact download"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          permissions:
+            actions: read    # Required for download-artifact@v4 with run-id
+            contents: read
+          steps:
+            - name: Download build artifacts from build workflow
+              uses: actions/download-artifact@v4
+              with:
+                name: build-output
+                run-id: ${{ github.event.inputs.build_run_id }}
+                github-token: ${{ secrets.GITHUB_TOKEN }}
+  - language: yaml
+    label: "Workflow-level permissions for cross-workflow download"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            build_run_id:
+              description: 'Run ID of the build workflow'
+              required: true
+              type: string
+
+      permissions:
+        actions: read
+        contents: read
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: dist
+                run-id: ${{ inputs.build_run_id }}
+                github-token: ${{ secrets.GITHUB_TOKEN }}
+prevention:
+  - "Whenever `run-id` is added to a download-artifact@v4 step, immediately add `actions: read` to the job permissions block"
+  - "Do not rely on default token permissions for cross-workflow operations — always declare explicit permission blocks"
+  - "Test cross-workflow downloads in a feature branch before merging — the permission error is deterministic, not flaky"
+  - "Add `github-token: ${{ secrets.GITHUB_TOKEN }}` explicitly to download-artifact@v4 steps that use run-id, as it clarifies the token in use"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-workflow-data-as-artifacts#downloading-artifacts-from-a-previous-workflow-run"
+    label: "GitHub Docs — Downloading artifacts from a previous workflow run"
+  - url: "https://github.com/actions/download-artifact/releases/tag/v4.0.0"
+    label: "actions/download-artifact v4.0.0 release notes — cross-workflow download"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token#defining-access-for-the-github_token-scopes"
+    label: "GitHub Docs — GITHUB_TOKEN permission scopes"

package/errors/concurrency-timing/concurrency-timing-033.yml

@@ -0,0 +1,104 @@
+id: concurrency-timing-033
+title: "Matrix jobs silently cancel each other when concurrency group key excludes matrix dimension values"
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - matrix
+  - cancel-in-progress
+  - silent-failure
+  - matrix-strategy
+patterns:
+  - regex: 'This run was cancelled\.'
+    flags: 'i'
+  - regex: 'The operation was cancelled\.'
+    flags: 'i'
+error_messages:
+  - "This run was cancelled."
+  - "The operation was cancelled."
+root_cause: |
+  When a workflow defines a `concurrency` group that does not include any matrix-specific
+  expression values, all matrix jobs resolve to the exact same concurrency group key.
+
+  With `cancel-in-progress: true`, each queued matrix job cancels the previously queued
+  or running job with the same key. Since all matrix jobs are queued nearly simultaneously,
+  they race for the single concurrency slot and only the last-scheduled job survives.
+  All others silently show "This run was cancelled." with no further explanation.
+
+  Example problematic configuration:
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+
+  All three matrix jobs resolve to the same key, e.g., "test-refs/heads/main", and
+  cancel each other until only one remains.
+
+  Without `cancel-in-progress`, matrix jobs queue serially behind the single slot instead
+  of running in parallel, also incorrect and defeating the purpose of the matrix.
+fix: |
+  Include at least one matrix dimension value in the concurrency group key so each matrix
+  job gets a unique group name and can run in parallel without cancelling each other.
+
+  Place `concurrency:` at the job level and reference the matrix variable:
+
+    jobs:
+      test:
+        concurrency:
+          group: ${{ github.workflow }}-${{ github.ref }}-${{ matrix.os }}
+          cancel-in-progress: true
+
+  If the goal is to cancel ALL previous matrix jobs when a new push arrives, apply
+  workflow-level concurrency with a key unique to the entire run (e.g., github.sha),
+  but note this serializes matrix sets rather than running jobs in parallel.
+fix_code:
+  - language: yaml
+    label: "Job-level concurrency includes matrix.os — each OS runs in its own slot"
+    code: |
+      jobs:
+        test:
+          runs-on: ${{ matrix.os }}
+          concurrency:
+            group: ${{ github.workflow }}-${{ github.ref }}-${{ matrix.os }}
+            cancel-in-progress: true
+          strategy:
+            fail-fast: false
+            matrix:
+              os: [ubuntu-latest, windows-latest, macos-latest]
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm test
+  - language: yaml
+    label: "Multi-dimension matrix — include all axis values in group key"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          concurrency:
+            group: ${{ github.workflow }}-${{ github.ref }}-${{ matrix.node }}-${{ matrix.os }}
+            cancel-in-progress: true
+          strategy:
+            fail-fast: false
+            matrix:
+              node: ['18', '20', '22']
+              os: [ubuntu-latest, windows-latest]
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: ${{ matrix.node }}
+            - run: npm test
+prevention:
+  - "Always include at least one matrix dimension variable in the concurrency group key when combining matrix strategy with concurrency"
+  - "Use job-level concurrency (under jobs.<name>:) rather than workflow-level when matrix is involved, for per-job slot control"
+  - "Review the Actions UI — if matrix jobs show 'This run was cancelled' without an explicit failure, check for concurrency group key collisions"
+  - "Run actionlint on your workflow files to catch common concurrency and expression issues"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs"
+    label: "GitHub Docs — Controlling the concurrency of workflows and jobs"
+  - url: "https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs"
+    label: "GitHub Docs — Using a matrix for your jobs"
+  - url: "https://github.com/orgs/community/discussions/24616"
+    label: "GitHub Community — Matrix jobs cancelled unexpectedly with concurrency groups"

package/errors/concurrency-timing/concurrency-timing-034.yml

@@ -0,0 +1,123 @@
+id: concurrency-timing-034
+title: "Job-level cancel-in-progress only cancels that job — sibling jobs from the same run continue executing"
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - cancel-in-progress
+  - job-level
+  - workflow-level
+  - deployment
+  - silent-failure
+patterns:
+  - regex: 'This run was cancelled\.'
+    flags: 'i'
+  - regex: 'cancel-in-progress.*true'
+    flags: 'i'
+error_messages:
+  - "This run was cancelled."
+root_cause: |
+  When `concurrency:` is placed at the job level (under `jobs.<job-id>:`) rather than at
+  the workflow level (top-level key), cancellation scope is limited to that single job only.
+  Other jobs in the same workflow run — whether still queued, in-progress, or already
+  completed — are not affected by the job-level concurrency signal.
+
+  Developers commonly place `concurrency:` under a single job (e.g., `deploy`) while
+  expecting it to cancel the entire previous workflow run. The result is a dangerous race:
+
+  Run 1:  build (succeeded) → deploy (running, concurrency group "deploy-prod")
+  Run 2:  build (starts)   → deploy (queued, same group)
+
+  Run 2's deploy job fires cancel-in-progress and cancels Run 1's deploy job — but only
+  if Run 1's deploy is still in-progress. If Run 1's build was slow and deploy hasn't
+  started yet, or if both runs' builds overlap, the serialization guarantee breaks down.
+
+  More critically: if `concurrency:` is absent from the build job, Run 1's build and
+  Run 2's build run simultaneously. Run 1's build (old code) may complete and trigger
+  Run 1's deploy AFTER Run 2's deploy has already deployed new code, producing a
+  rollback to old code with no warning.
+
+  Workflow-level concurrency cancels the ENTIRE run (all jobs). Job-level concurrency
+  cancels only THAT job. This distinction is frequently misunderstood.
+fix: |
+  Place `concurrency:` at the workflow level (top-level) to cancel the entire previous
+  workflow run — all jobs — when a new run starts. Use job-level concurrency only when
+  you deliberately want different cancellation granularity per job.
+
+  For CI/CD where the entire pipeline should be replaced by the latest push:
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true
+    jobs:
+      build: ...
+      deploy: ...
+
+  For serializing deploys while allowing parallel builds:
+    jobs:
+      build:
+        # No concurrency key — builds run in parallel
+      deploy:
+        needs: build
+        concurrency:
+          group: deploy-${{ github.ref }}
+          cancel-in-progress: false   # Queue, do not cancel in-progress deployments
+fix_code:
+  - language: yaml
+    label: "Workflow-level concurrency cancels entire run including all jobs"
+    code: |
+      name: CI/CD Pipeline
+
+      on:
+        push:
+          branches: [main]
+
+      # Top-level: cancels ALL jobs in the previous workflow run on new push
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm run build
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          environment: production
+          steps:
+            - run: ./scripts/deploy.sh
+  - language: yaml
+    label: "Job-level concurrency for deploy serialization only (intentional pattern)"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          # No concurrency key — parallel builds are fine
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm run build
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          # Job-level: serialize deploys, but never cancel an in-progress deployment
+          concurrency:
+            group: deploy-${{ github.ref }}
+            cancel-in-progress: false
+          steps:
+            - run: ./scripts/deploy.sh
+prevention:
+  - "Use workflow-level concurrency (top-level key, not under a job) when the entire pipeline should be replaced by the latest push"
+  - "Use job-level concurrency only when you intentionally want different cancellation behavior per job"
+  - "Set cancel-in-progress: false for deploy jobs — cancelling an in-progress deployment can leave infrastructure in a partially updated state"
+  - "Add concurrency to EVERY job in a pipeline if using job-level groups, not just the deploy job"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs"
+    label: "GitHub Docs — Controlling the concurrency of workflows and jobs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#concurrency"
+    label: "GitHub Actions workflow syntax — concurrency"
+  - url: "https://github.com/orgs/community/discussions/57540"
+    label: "GitHub Community — Job-level vs workflow-level concurrency scoping"

package/errors/known-unsolved/known-unsolved-038.yml

@@ -0,0 +1,124 @@
+id: known-unsolved-038
+title: "workflow_dispatch 'Run workflow' button invisible until workflow file merges to default branch"
+category: known-unsolved
+severity: limitation
+tags:
+  - workflow-dispatch
+  - ui
+  - default-branch
+  - known-limitation
+  - feature-branch
+  - testing
+patterns:
+  - regex: 'run workflow.*not.*appear'
+    flags: 'i'
+  - regex: 'workflow_dispatch.*button.*missing'
+    flags: 'i'
+  - regex: 'workflow.*not.*present.*default.*branch'
+    flags: 'i'
+error_messages:
+  - "This workflow has a workflow_dispatch event trigger, however a workflow_dispatch event workflow run cannot be created as this workflow is not present in the default branch."
+root_cause: |
+  The "Run workflow" button in the GitHub Actions UI only appears when the workflow file
+  containing `on.workflow_dispatch` exists on the repository's default branch (e.g., main).
+
+  When you add a new `on.workflow_dispatch` workflow to a feature branch:
+  - The workflow file exists in the branch and can be referenced
+  - The "Run workflow" button does NOT appear in the GitHub Actions UI for that branch
+  - The GitHub REST API returns an error if you attempt to dispatch it
+
+  The REST API error message is:
+    "This workflow has a workflow_dispatch event trigger, however a workflow_dispatch event
+    workflow run cannot be created as this workflow is not present in the default branch."
+
+  This creates a catch-22: you want to validate the workflow before merging, but the trigger
+  mechanism (UI button and REST API dispatch) only activates after merging to the default branch.
+
+  The limitation applies consistently across:
+  - GitHub web UI "Run workflow" button
+  - REST API create_workflow_dispatch endpoint
+  - GitHub CLI: gh workflow run (requires workflow on default branch)
+
+  Contrast this with `on.push` and `on.pull_request` which fire correctly from any branch
+  that contains the workflow file.
+fix: |
+  There is no way to trigger workflow_dispatch from the GitHub UI or standard API before
+  the workflow file reaches the default branch. Use these workarounds:
+
+  Option 1 (recommended): Add `on.push` temporarily during development alongside
+  `on.workflow_dispatch`. Push triggers fire from any branch. Remove push trigger before
+  merging to avoid unintended production runs.
+
+  Option 2: Use `act` (nektos/act) locally to simulate workflow_dispatch with custom inputs
+  before pushing to GitHub:
+    act workflow_dispatch -e event.json
+
+  Option 3: Merge the workflow file to a long-lived integration branch first, use it as a
+  staging default, then promote to main after validation.
+
+  Option 4: Commit the workflow directly to the default branch with a no-op body (echo "test"),
+  validate the dispatch mechanism works, then iterate in place on the default branch.
+
+  Note: Using gh api with a specific ref pointing to a branch that has the file does NOT
+  bypass the default-branch requirement for workflow_dispatch. The REST API enforces this
+  server-side regardless of ref parameter.
+fix_code:
+  - language: yaml
+    label: "Temporary on.push alongside workflow_dispatch for feature-branch testing"
+    code: |
+      on:
+        # Production trigger (only works after merge to default branch)
+        workflow_dispatch:
+          inputs:
+            environment:
+              description: 'Target environment'
+              required: true
+              type: choice
+              options: [staging, production]
+
+        # DEVELOPMENT ONLY: allows testing from feature branch via push
+        # Remove this push trigger before merging to main
+        push:
+          branches: ['feature/my-new-dispatch-workflow']
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Deploy
+              env:
+                TARGET: ${{ inputs.environment || 'staging' }}
+              run: ./scripts/deploy.sh "$TARGET"
+  - language: yaml
+    label: "Minimal no-op workflow — merge first, iterate after to unlock dispatch button"
+    code: |
+      # Step 1: Merge this minimal workflow to main first to unlock the Run Workflow button
+      # Step 2: Iterate on the job steps on main or in a branch
+      on:
+        workflow_dispatch:
+          inputs:
+            dry_run:
+              description: 'Dry run mode'
+              type: boolean
+              default: true
+
+      jobs:
+        placeholder:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Workflow dispatch confirmed working. Replace this with real steps."
+prevention:
+  - "When creating new workflow_dispatch workflows, plan to merge a minimal skeleton to main first before adding full logic"
+  - "Add on.push with a branch filter during development of any workflow_dispatch workflow — remove before merging"
+  - "Use act locally (nektos/act) to test workflow_dispatch input handling before pushing"
+  - "Document in the PR description that the Run Workflow button will appear only after merge"
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch"
+    label: "GitHub Docs — workflow_dispatch event"
+  - url: "https://docs.github.com/en/rest/actions/workflows?apiVersion=2022-11-28#create-a-workflow-dispatch-event"
+    label: "GitHub REST API — Create a workflow dispatch event"
+  - url: "https://github.com/orgs/community/discussions/24357"
+    label: "GitHub Community — workflow_dispatch button not showing in feature branch"
+  - url: "https://github.com/nektos/act"
+    label: "nektos/act — Run Actions locally including workflow_dispatch simulation"