@htekdev/actions-debugger 1.0.55 → 1.0.57

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/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-037.yml

@@ -0,0 +1,124 @@
+id: known-unsolved-037
+title: "Skipped jobs show as 'skipped' — branch protection required status checks block PR merge"
+category: known-unsolved
+severity: limitation
+tags:
+  - required-status-checks
+  - branch-protection
+  - skipped
+  - conditional-job
+  - merge-blocked
+  - known-limitation
+patterns:
+  - regex: 'if:\s+github\.event_name\s+!=\s+'
+    flags: i
+  - regex: 'if:\s+\$\{\{\s*github\.event_name\s*!=\s*'
+    flags: i
+error_messages:
+  - "Required status check 'ci/test' was not successful — status: skipped"
+  - "Branch protection rule requires passing status checks before merging"
+root_cause: |
+  When a job's if: condition evaluates to false, GitHub Actions marks that job as
+  "Skipped" in the Checks API. Branch protection rules that require a specific check
+  to pass only accept a conclusion of "success" — not "skipped", "cancelled", or
+  "neutral".
+
+  This creates a practical trap: a team sets up a required check for a job like
+  ci/test, then later adds an if: condition to skip that job on certain events
+  (for example, to avoid running tests on tag pushes or documentation-only changes).
+  The conditional logic is correct for workflow execution, but the skipped conclusion
+  permanently blocks all PRs where that condition evaluates to false.
+
+  GitHub has documented this as intentional: a skipped job is not a successful job.
+  There is no configuration option to treat "skipped" as equivalent to "success" for
+  branch protection purposes as of 2026. The workaround requires a structural change
+  to the workflow.
+fix: |
+  This is a known limitation with no direct fix. The recommended workarounds are:
+
+  1. ALWAYS-PASS WRAPPER JOB: Create a wrapper job that always runs and reports
+     the real outcome. The wrapper job becomes the required status check instead of
+     the real CI job. If CI was skipped (e.g., docs-only change), the wrapper passes.
+     If CI ran and failed, the wrapper fails.
+
+  2. MOVE THE CONDITION INSIDE THE JOB: Instead of using if: at the job level, keep
+     the job always running and use if: at the step level. An empty job always
+     succeeds, so the required status check passes.
+
+  3. PATHS FILTER PATTERN (dorny/paths-filter): Use a separate filtering job and
+     pass its output as a condition parameter to downstream jobs while keeping a
+     pass-through job for status check reporting.
+
+  4. RE-EVALUATE THE REQUIRED CHECK: If the check is truly optional for some events,
+     consider removing it from required status checks and instead enforce it only at
+     the merge queue level.
+fix_code:
+  - language: yaml
+    label: "Problem: conditional job is skipped, blocking required status check"
+    code: |
+      on: [push, pull_request]
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          # This job is required in branch protection, but gets skipped on push to main
+          if: github.event_name == 'pull_request'
+          steps:
+            - run: npm test
+            # On push events, this job is SKIPPED, blocking required status check
+  - language: yaml
+    label: "Fix: always-pass wrapper job becomes the required status check"
+    code: |
+      on: [push, pull_request]
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          if: github.event_name == 'pull_request'
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+
+        # Set THIS job as the required status check in branch protection
+        ci-status:
+          runs-on: ubuntu-latest
+          needs: [test]
+          if: always()
+          steps:
+            - name: Report CI result
+              run: |
+                result="${{ needs.test.result }}"
+                if [[ "$result" == "success" || "$result" == "skipped" ]]; then
+                  echo "CI passed or was intentionally skipped — OK to merge"
+                else
+                  echo "CI failed (result: $result)"
+                  exit 1
+                fi
+  - language: yaml
+    label: "Alternative: move condition inside job so job always runs and passes when empty"
+    code: |
+      on: [push, pull_request]
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          # No if: at job level — job always runs and always produces a conclusion
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Run tests (pull_request only)
+              if: github.event_name == 'pull_request'
+              run: npm test
+              # If step is skipped, job still succeeds — required check passes
+prevention:
+  - "Never add an if: condition to a job that is a required status check — use a wrapper job instead"
+  - "Use the always-pass wrapper pattern from the start when adding new required status checks"
+  - "Test required check behavior by creating a draft PR that intentionally triggers the skip condition"
+  - "Document which jobs are required status checks in a comment at the top of the workflow file"
+docs:
+  - url: "https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/troubleshooting-required-status-checks"
+    label: "GitHub Docs: Troubleshooting required status checks"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idif"
+    label: "GitHub Docs: Job-level if conditions"
+  - url: "https://github.com/dorny/paths-filter"
+    label: "dorny/paths-filter: Conditional execution with status reporting"

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"