@htekdev/actions-debugger 1.0.14 → 1.0.16

package/errors/concurrency-timing/required-check-pending-path-filter-skip.yml

@@ -0,0 +1,160 @@
+id: concurrency-timing-013
+title: "Required Status Check Stuck in Pending When Workflow Skipped by Path or Branch Filter"
+category: concurrency-timing
+severity: warning
+tags:
+  - required-status-check
+  - path-filter
+  - branch-filter
+  - pending
+  - pull-request
+  - branch-protection
+  - paths
+  - blocked-pr
+patterns:
+  - regex: "Some checks haven't completed yet|Required status check.*pending"
+    flags: "i"
+  - regex: "Waiting for status:.*pending"
+    flags: "i"
+error_messages:
+  - "Some checks haven't completed yet"
+  - "Required status check is pending"
+  - "Waiting for status: CI / test (pending)"
+root_cause: |
+  GitHub Actions workflows that use `paths:`, `paths-ignore:`, `branches:`, or
+  `branches-ignore:` filters will NOT run — and will NOT report ANY status — for
+  commits that don't match the filter criteria.
+
+  When a required status check is configured in a branch protection rule and the
+  workflow providing that check is skipped by a filter:
+  - The check is NEVER created for that commit — it remains in "Pending" state indefinitely
+  - The PR is blocked from merging with "Some checks haven't completed yet"
+  - The check CANNOT be manually re-triggered without pushing a commit that matches the filter
+
+  Common scenario:
+  A repository has a `ci.yml` workflow with `paths: ['src/**', '*.ts']` and
+  `CI / test` configured as a required status check. A developer opens a PR that only
+  changes `README.md` or `.github/docs/`. The `CI / test` check never runs, shows as
+  "Pending" forever, and the PR is permanently blocked from merging without an admin
+  override or a dummy code commit to trigger the workflow.
+
+  This is explicitly documented behavior but frequently misunderstood:
+  - The workflow appears to work correctly for code-change PRs (the common case)
+  - The bug only surfaces on documentation-only, config-only, or administrative PRs
+  - Developers and reviewers see a pending check with no way to trigger it
+
+  Note: This is distinct from skipped-needs-cascade (job dependency skipping) — this
+  is specifically about the WORKFLOW TRIGGER filter preventing the run from ever starting,
+  so no job status is reported at all.
+
+  Source: GitHub Docs — Troubleshooting required status checks: "If a workflow is skipped
+  due to path filtering, branch filtering or a commit message, then checks associated
+  with that workflow will remain in a 'Pending' state. A pull request that requires those
+  checks to be successful will be blocked from merging."
+fix: |
+  Two main approaches:
+
+  1. **Always-succeeding bypass job** — remove path filters from the workflow trigger,
+     run the workflow for all PRs, use `dorny/paths-filter` or `tj-actions/changed-files`
+     to detect changes inside the workflow, and add a sentinel job that always produces a
+     status. Configure the required check to point at the sentinel job name.
+
+  2. **Split workflow** — keep the path-filtered workflow for actual CI work, and add a
+     separate always-running workflow that provides the required status check name
+     (succeeds immediately for non-code PRs, waits for CI for code PRs).
+fix_code:
+  - language: yaml
+    label: "Fix: always-running workflow with internal path detection and sentinel job"
+    code: |
+      name: CI
+      # No path filter — workflow always runs for all PRs
+      on:
+        pull_request:
+          branches: [main]
+
+      jobs:
+        changes:
+          runs-on: ubuntu-latest
+          outputs:
+            code: ${{ steps.filter.outputs.code }}
+          steps:
+            - uses: actions/checkout@v4
+            - uses: dorny/paths-filter@v3
+              id: filter
+              with:
+                filters: |
+                  code:
+                    - 'src/**'
+                    - '*.ts'
+                    - 'package*.json'
+
+        test:
+          needs: changes
+          if: needs.changes.outputs.code == 'true'
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm test
+
+        # Branch protection required check: "CI / ci-gate" (not "CI / test")
+        # Always produces a status — green for docs PRs, waits for test on code PRs
+        ci-gate:
+          needs: [changes, test]
+          if: always()
+          runs-on: ubuntu-latest
+          steps:
+            - name: Confirm CI passed or code was not changed
+              run: |
+                CODE_CHANGED="${{ needs.changes.outputs.code }}"
+                TEST_RESULT="${{ needs.test.result }}"
+                if [[ "$CODE_CHANGED" == "false" ]]; then
+                  echo "✅ No code changes — CI gate passes automatically"
+                elif [[ "$TEST_RESULT" == "success" ]]; then
+                  echo "✅ Tests passed"
+                else
+                  echo "❌ Tests $TEST_RESULT"
+                  exit 1
+                fi
+
+  - language: yaml
+    label: "Alternative: run all steps always but skip expensive ones via filter"
+    code: |
+      name: CI
+      on:
+        pull_request:
+          branches: [main]
+      # No workflow-level path filter — status always reported
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - uses: dorny/paths-filter@v3
+              id: filter
+              with:
+                filters: |
+                  code: ['src/**', '*.ts', 'package*.json']
+
+            - name: Install dependencies
+              if: steps.filter.outputs.code == 'true'
+              run: npm ci
+
+            - name: Run tests
+              if: steps.filter.outputs.code == 'true'
+              run: npm test
+            # Job always completes with success — check is always reported
+prevention:
+  - "Never use workflow-level `paths:` or `branches:` filters as the sole trigger for a required status check."
+  - "Use `dorny/paths-filter` or `tj-actions/changed-files` INSIDE an always-running workflow instead of workflow-level path filters."
+  - "Name required status checks after jobs that always produce a status, even on non-code PRs."
+  - "Test branch protection rules by opening a documentation-only PR to verify all required checks complete."
+  - "Consider admin overrides as a last resort, not a workflow fix — the root cause will keep happening."
+docs:
+  - url: "https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks"
+    label: "Troubleshooting required status checks (path filter skip documented)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore"
+    label: "Workflow syntax: paths and paths-ignore filters"
+  - url: "https://github.com/dorny/paths-filter"
+    label: "dorny/paths-filter — detect changed files inside workflow"

package/errors/concurrency-timing/wait-timer-cancel-in-progress-starvation.yml

@@ -0,0 +1,125 @@
+id: concurrency-timing-012
+title: "Deployment wait-timer + cancel-in-progress: true Creates Permanent Deployment Starvation Loop"
+category: concurrency-timing
+severity: warning
+tags:
+  - wait-timer
+  - cancel-in-progress
+  - deployment
+  - environment
+  - starvation
+  - concurrency
+  - production
+patterns:
+  - regex: "Run was cancelled|Canceling since a higher priority waiting request"
+    flags: "i"
+  - regex: "wait.?timer|waiting for environment.*approval"
+    flags: "i"
+error_messages:
+  - "Run was cancelled"
+  - "Canceling since a higher priority waiting request for 'production' exists"
+root_cause: |
+  When a deployment workflow combines `concurrency.cancel-in-progress: true` with a
+  deployment environment that has a `wait-timer` configured (a mandatory delay before
+  deployment proceeds), every new commit to the branch creates a starvation loop where
+  no deployment ever reaches the execution phase:
+
+  1. Run A starts → deployment job begins waiting out the environment wait-timer (e.g., 5 min)
+  2. A new commit is pushed → Run B starts in the same concurrency group
+  3. `cancel-in-progress: true` fires → Run A is cancelled while still in the wait-timer
+  4. Run B now begins its own wait-timer countdown
+  5. Another commit arrives → Run B is cancelled during its timer
+  6. This repeats indefinitely — no deployment ever executes
+
+  This loop is particularly insidious because:
+  - All cancellations appear expected and benign in the Actions UI (no failures shown)
+  - The repository looks healthy — CI passes, deployments start — but production is
+    silently never updated
+  - Active development repos where commits arrive faster than the wait-timer duration
+    are especially vulnerable
+
+  Note: GitHub's concurrency model allows only ONE pending run per group. With
+  `cancel-in-progress: true`, a new run cancels the RUNNING run (not just queues) —
+  so even a very short wait-timer cannot escape this if commits arrive frequently.
+fix: |
+  Do not combine `cancel-in-progress: true` with deployment environment `wait-timer`
+  on the same workflow. Use `cancel-in-progress: false` (the default) for deploy
+  workflows — this queues runs so each commit eventually deploys in order.
+
+  If you want fast feedback for CI but reliable deployments for CD, split them into
+  separate workflow files with different concurrency strategies.
+fix_code:
+  - language: yaml
+    label: "Fix: disable cancel-in-progress for deploy workflow with wait-timer"
+    code: |
+      name: Deploy to Production
+      on:
+        push:
+          branches: [main]
+
+      concurrency:
+        group: deploy-production
+        cancel-in-progress: false  # Queue — never starve a deployment with wait-timer
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          environment: production   # Has wait-timer: 5 configured
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+
+  - language: yaml
+    label: "Split pipeline: CI cancels freely; deploy queues safely after CI"
+    code: |
+      # ci.yml — fast feedback, cancel stale runs is fine
+      name: CI
+      on:
+        push:
+          branches: [main]
+      concurrency:
+        group: ci-${{ github.ref }}
+        cancel-in-progress: true   # OK: no side effects
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+
+      ---
+      # deploy.yml — triggered after CI, environment has wait-timer
+      name: Deploy
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+          branches: [main]
+
+      concurrency:
+        group: deploy-production
+        cancel-in-progress: false   # Queue; every successful CI run gets deployed
+
+      jobs:
+        deploy:
+          if: ${{ github.event.workflow_run.conclusion == 'success' }}
+          runs-on: ubuntu-latest
+          environment: production   # wait-timer is safe — no cancel-in-progress racing it
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.workflow_run.head_sha }}
+            - run: ./deploy.sh
+prevention:
+  - "Never combine `cancel-in-progress: true` with a deployment environment `wait-timer` in the same workflow."
+  - "Use `cancel-in-progress: false` for any workflow that deploys to environments with protection rules."
+  - "Decouple CI (cancel-ok, fast) from CD (queued, reliable) into separate workflow files."
+  - "Monitor the Actions tab for a pattern of all deployments showing as CANCELLED — this is a sign of starvation."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-concurrency"
+    label: "GitHub Docs: Using concurrency in GitHub Actions"
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment#wait-timer"
+    label: "GitHub Docs: Managing environments — wait timer"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run"
+    label: "workflow_run event — decouple CI and CD pipelines"

package/errors/known-unsolved/composite-action-step-timeout-minutes-ignored.yml

@@ -0,0 +1,146 @@
+id: known-unsolved-017
+title: "timeout-minutes Is Silently Ignored on Steps Inside Composite Actions"
+category: known-unsolved
+severity: limitation
+tags:
+  - timeout-minutes
+  - composite-action
+  - limitation
+  - step-timeout
+  - composite
+  - hung-step
+  - action-yml
+patterns:
+  - regex: "timeout.?minutes.*composite|using.*composite.*timeout"
+    flags: "i"
+  - regex: "Unexpected value 'timeout-minutes'"
+    flags: "i"
+error_messages:
+  - "Unexpected value 'timeout-minutes'"
+root_cause: |
+  GitHub Actions supports `timeout-minutes` at the job level and at individual step level
+  inside regular workflow files. However, `timeout-minutes` is NOT enforced on steps
+  inside composite actions (action.yml files using `runs.using: composite`).
+
+  Adding `timeout-minutes` to a step within a composite action's `steps:` block is
+  accepted by the YAML parser without error, but the timeout is silently NOT applied
+  at runtime. A hung step inside a composite action will run until the parent job's
+  overall `timeout-minutes` is exhausted — up to 6 hours on GitHub-hosted runners by
+  default.
+
+  This creates a dangerous gap:
+  - Network-dependent steps (downloads, API calls, package installs) inside a composite
+    action can hang indefinitely if the network is slow or unresponsive
+  - `actions/cache` intermittently stalls; wrapping it in a composite action with a
+    step `timeout-minutes: 5` provides NO protection
+  - Composite action authors cannot provide defensive step timeouts — users of the
+    composite action must rely entirely on the calling job's `timeout-minutes`
+  - Since the step timeout appears to be set (the YAML is valid), developers believe
+    they have a guard when they actually have none
+
+  The limitation has been tracked and discussed in the community since 2021
+  (actions/runner#1979) and remains unresolved as of 2026.
+
+  Source: actions/runner#1979 — "We would like to see timeout-minutes supported on
+  steps in composite actions. Occasionally actions like actions/cache bug out and run
+  for the default timeout time (6 hours) which causes unnecessary costs."
+fix: |
+  Since step-level timeouts cannot be enforced inside composite actions, use these
+  workarounds:
+
+  1. **Shell-level timeout**: Wrap commands in `timeout <seconds>` (bash) or `Start-Sleep`
+     + `Start-Job` with timeout (PowerShell) to kill hung processes from within the script.
+  2. **Job-level `timeout-minutes`**: Set a conservative timeout on the calling job as a
+     safety net — it limits the composite action's maximum runtime.
+  3. **Step-level timeout in the calling workflow**: When calling a composite action as
+     a step in a workflow file, `timeout-minutes` IS supported at the step level in the
+     workflow (not inside the composite itself). This provides a per-call timeout.
+  4. **Split into multiple reusable actions**: Replace a large composite action with
+     multiple smaller ones, each invoked as a separate workflow step — where step-level
+     `timeout-minutes` IS enforced.
+fix_code:
+  - language: yaml
+    label: "WRONG — timeout-minutes inside composite action step is silently ignored"
+    code: |
+      # action.yml — composite action
+      name: "Setup with Timeout"
+      runs:
+        using: composite
+        steps:
+          - name: Download dependencies
+            timeout-minutes: 5   # ← SILENTLY IGNORED — not enforced at runtime
+            shell: bash
+            run: curl -o deps.tar.gz "${{ inputs.deps-url }}"
+
+  - language: yaml
+    label: "Workaround: shell-level timeout inside composite action"
+    code: |
+      # action.yml — composite action
+      name: "Setup with Shell Timeout"
+      runs:
+        using: composite
+        steps:
+          - name: Download dependencies with shell timeout
+            shell: bash
+            run: |
+              # timeout-minutes on this step would be ignored — use shell timeout instead
+              timeout 300 curl -o deps.tar.gz "${{ inputs.deps-url }}" || {
+                echo "::error::Download timed out after 5 minutes"
+                exit 1
+              }
+
+          - name: Cache restore with timeout guard
+            shell: bash
+            run: |
+              timeout 120 ./restore-cache.sh || {
+                echo "::warning::Cache restore timed out — continuing without cache"
+              }
+
+  - language: yaml
+    label: "Workaround: step-level timeout in the calling WORKFLOW (not inside composite)"
+    code: |
+      # workflow.yml — timeout-minutes at step level in workflow DOES work
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: 30   # Job-level safety net
+          steps:
+            - uses: actions/checkout@v4
+
+            # timeout-minutes here is at the WORKFLOW step level — this IS enforced
+            - name: Run composite action
+              uses: ./.github/actions/my-composite-action
+              timeout-minutes: 10   # Works: this is a workflow step, not inside the composite
+
+            - run: npm run build
+
+  - language: yaml
+    label: "Workaround: split composite into multiple actions — each gets timeout"
+    code: |
+      # workflow.yml — multiple smaller actions instead of one large composite
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            # Each step in the workflow gets enforceable timeout-minutes
+            - uses: ./.github/actions/setup-node
+              timeout-minutes: 5    # Enforced — workflow step level
+
+            - uses: ./.github/actions/restore-cache
+              timeout-minutes: 3    # Enforced
+
+            - uses: ./.github/actions/install-deps
+              timeout-minutes: 10   # Enforced
+prevention:
+  - "Never rely on `timeout-minutes` inside composite action `steps:` — the field is accepted but silently ignored."
+  - "Use `timeout <seconds>` (bash) or PowerShell job timeouts as shell-level guards for long-running composite steps."
+  - "Apply `timeout-minutes` at the step level in the CALLING WORKFLOW (not inside the composite) for per-invocation limits."
+  - "Always set a job-level `timeout-minutes` on any job that calls composite actions, as a safety net against runaway steps."
+  - "Composite action authors should document the expected maximum runtime so callers can set appropriate job-level timeouts."
+docs:
+  - url: "https://github.com/actions/runner/issues/1979"
+    label: "actions/runner#1979 — timeout-minutes not enforced in composite action steps (open since 2021)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepstimeout-minutes"
+    label: "GitHub Docs: steps[*].timeout-minutes (workflow-level steps — works)"
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#runs-for-composite-actions"
+    label: "GitHub Docs: Metadata syntax for composite actions"

package/errors/known-unsolved/reusable-workflow-no-composite-action-call.yml

@@ -0,0 +1,116 @@
+id: known-unsolved-014
+title: "Reusable Workflows Cannot Be Called from Composite Actions"
+category: known-unsolved
+severity: limitation
+tags:
+  - composite-action
+  - reusable-workflow
+  - workflow-call
+  - limitation
+  - uses-key
+  - no-fix
+patterns:
+  - regex: "Reusable workflows cannot be referenced from composite actions"
+    flags: "i"
+  - regex: "uses:.*\\.github/workflows/.*\\.yml.*composite"
+    flags: "i"
+  - regex: "A reusable workflow cannot be used as a step in a composite action"
+    flags: "i"
+error_messages:
+  - "Error: Reusable workflows cannot be referenced from composite actions."
+  - "A reusable workflow cannot be used as a step in a composite action."
+root_cause: |
+  GitHub Actions enforces a strict separation between two different abstraction levels:
+  - **Actions** (composite, JavaScript, Docker) — called from workflow steps via `uses:`
+  - **Reusable workflows** (called via `workflow_call` trigger) — called from workflow jobs
+    via `uses:` at the JOB level, not the step level
+
+  A composite action runs within a step inside a job. A reusable workflow, however, IS a
+  job (or set of jobs). You cannot embed a job inside a step — this is a fundamental
+  architectural constraint, not a configuration error.
+
+  This fails at validation time with a clear error message. The error is triggered when:
+  - A composite action's `runs.steps` contains a `uses:` entry that points to a
+    `.github/workflows/*.yml` file (a reusable workflow)
+  - An organization tried to nest workflow-level orchestration inside a step-level action
+
+  There is no workaround that preserves both the composite action wrapping and the reusable
+  workflow invocation. GitHub has confirmed this is by design and has no plans to change it.
+  The GitHub Actions team's rationale: reusable workflows operate at the job/runner level
+  and require job-level context (needs:, outputs:, secrets: inheritance) that cannot exist
+  inside a step.
+fix: |
+  There is no fix — this is a platform limitation.
+
+  The recommended alternatives are:
+  1. **Restructure to call the reusable workflow at the job level** (not from inside a
+     composite action). Move the reusable workflow call to a dedicated job in your workflow
+     file using `jobs.my-job.uses:`.
+  2. **Convert the reusable workflow into a composite action** if the logic does not require
+     job-level features (matrix, needs: dependencies, explicit runner selection, secrets
+     inheritance via `secrets: inherit`).
+  3. **Inline the reusable workflow steps** into the composite action directly. While this
+     loses the DRY benefit of the reusable workflow, it resolves the structural constraint.
+fix_code:
+  - language: yaml
+    label: "Call reusable workflow at job level (not from composite action)"
+    code: |
+      # ❌ This FAILS — cannot call reusable workflow from composite action step
+      # In: .github/actions/my-composite/action.yml
+      # runs:
+      #   using: "composite"
+      #   steps:
+      #     - uses: ./.github/workflows/shared-build.yml   # ERROR: not allowed
+      #       with:
+      #         environment: staging
+
+      # ✅ Call reusable workflow at job level in workflow file instead
+      jobs:
+        setup:
+          runs-on: ubuntu-latest
+          steps:
+            # Composite action can still do pre/post steps
+            - uses: ./.github/actions/my-composite
+              with:
+                param: value
+
+        shared-build:
+          needs: setup
+          uses: ./.github/workflows/shared-build.yml
+          with:
+            environment: staging
+          secrets: inherit
+  - language: yaml
+    label: "Convert reusable workflow to composite action (when job-level features not needed)"
+    code: |
+      # .github/actions/shared-build/action.yml
+      name: "Shared Build"
+      description: "Composite action equivalent of the shared-build reusable workflow"
+      inputs:
+        environment:
+          required: true
+          description: "Target environment"
+      runs:
+        using: "composite"
+        steps:
+          - name: Setup Node
+            uses: actions/setup-node@v4
+            with:
+              node-version: '20'
+          - name: Build
+            shell: bash
+            run: npm run build:${{ inputs.environment }}
+prevention:
+  - "Understand the GitHub Actions hierarchy: Docker/JS/composite actions run WITHIN steps; reusable workflows run AS jobs."
+  - "Use composite actions when you want to share steps across workflows within a single job."
+  - "Use reusable workflows (workflow_call) when you want to share an entire job or multi-job sequence."
+  - "If you need both abstraction levels, combine them: a job calls a reusable workflow, and within that workflow's jobs, steps call composite actions."
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows#limitations"
+    label: "GitHub docs — Reusing workflows: limitations (composite action restriction)"
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action"
+    label: "GitHub docs — Creating a composite action"
+  - url: "https://github.com/orgs/community/discussions/11834"
+    label: "Community discussion #11834 — reusable workflow called from composite action error"
+  - url: "https://stackoverflow.com/questions/70421268/how-to-reference-a-reusable-workflow-from-a-composite-action"
+    label: "Stack Overflow — reference reusable workflow from composite action"

package/errors/known-unsolved/schedule-trigger-default-branch-only.yml

@@ -0,0 +1,113 @@
+id: known-unsolved-015
+title: "Scheduled Workflows Only Run on the Default Branch — Cannot Target Arbitrary Branches"
+category: known-unsolved
+severity: limitation
+tags:
+  - schedule
+  - cron
+  - default-branch
+  - trigger
+  - branches-filter
+  - platform-limitation
+patterns:
+  - regex: "schedule.*branches|branches.*schedule"
+    flags: "i"
+  - regex: "cron.*not.*branch|branch.*cron.*ignored"
+    flags: "i"
+  - regex: "Unexpected value 'branches'"
+    flags: "i"
+error_messages:
+  - "You have an error in your yaml syntax on line X"
+  - "Unexpected value 'branches'"
+  - "The 'branches' filter is not supported under 'schedule'"
+root_cause: |
+  GitHub Actions schedule (cron) triggers **always run the workflow file from the
+  repository's default branch** (typically `main`). This is an intentional platform
+  security constraint.
+
+  There is no supported way to target a non-default branch with a `schedule:` trigger:
+  - Adding `branches:` under `schedule:` causes a YAML syntax error ("Unexpected value
+    'branches'") — it is not a valid key in that position.
+  - Placing the schedule workflow on a non-default branch does not cause it to run.
+  - The `github.ref` and `github.head_ref` values will always reflect the default branch
+    when triggered by a schedule event.
+
+  **Why GitHub enforces this:**
+  If scheduled workflows could target arbitrary branches, an attacker who pushes
+  malicious code to a feature branch could have it execute on a cron schedule with the
+  repository's full secrets — a significant supply-chain risk. By restricting cron runs
+  to the default branch, GitHub ensures only reviewed/merged code runs on schedule.
+
+  **Platform impact:**
+  - Cannot create separate nightly build schedules for multiple branches from one repo.
+  - Cannot run a scheduled integration test on a long-lived release branch without
+    special workarounds.
+  - Community has requested this capability since 2021 (community discussion #16107).
+
+  Sources: Stack Overflow Q/A, GitHub Community #16107, GitHub Docs
+fix: |
+  There is no direct fix — this is a platform constraint. Use these workarounds:
+
+  **Workaround 1 (Recommended): Check out the target branch in the scheduled workflow**
+  Keep the scheduled workflow on the default branch but have the job check out the
+  desired branch in its `actions/checkout` step:
+
+  **Workaround 2: Trigger via `workflow_dispatch` from an external scheduler**
+  Use the GitHub REST API or `gh workflow run` from a controlled external system
+  (another scheduled job, GitHub App, etc.) to trigger a `workflow_dispatch` event
+  targeting a specific `ref` (branch or tag).
+
+  **Workaround 3: `workflow_run` chaining**
+  Not a direct substitute, but a workflow triggered by `workflow_run` on a push to
+  the target branch can perform scheduled-like follow-up logic.
+
+  **For release branches:** Merge a scheduled workflow file into each release branch
+  as part of the branch maintenance process — each branch can independently schedule
+  its own cron.
+fix_code:
+  - language: yaml
+    label: "Broken — branches filter not valid under schedule, causes YAML error"
+    code: |
+      # ❌ BROKEN: 'branches' is not a valid key under schedule — YAML syntax error
+      on:
+        schedule:
+          - cron: '0 1 * * *'
+            branches:          # ← invalid key, causes: Unexpected value 'branches'
+              - release/v2
+  - language: yaml
+    label: "Workaround — check out target branch in the scheduled workflow step"
+    code: |
+      # ✅ WORKAROUND: workflow lives on default branch, checks out the desired ref
+      on:
+        schedule:
+          - cron: '0 1 * * *'   # runs from default branch (main)
+
+      jobs:
+        nightly-test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: 'release/v2'    # explicitly check out the target branch
+            # All subsequent steps operate on release/v2 code
+            - run: ./run-tests.sh
+  - language: yaml
+    label: "Workaround — trigger workflow_dispatch against a specific branch via gh CLI"
+    code: |
+      # ✅ WORKAROUND: External script that fires workflow_dispatch targeting a branch
+      # Run this from another scheduled job (e.g., a GitHub App or a cron runner)
+      gh workflow run nightly.yml \
+        --repo owner/repo \
+        --ref release/v2        # workflow_dispatch supports specifying a branch ref
+prevention:
+  - "Do not add `branches:` under `schedule:` — it is not a valid key and will cause YAML syntax errors."
+  - "Design scheduled workflows to check out the target branch explicitly via `actions/checkout` with the `ref:` input."
+  - "For complex multi-branch scheduling needs, consider using a GitHub App or external scheduler that fires `workflow_dispatch` events targeting specific refs."
+  - "Document this platform limitation in team wikis to prevent repeated attempts at adding `branches:` to schedule triggers."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule"
+    label: "GitHub Docs: Events that trigger workflows — schedule"
+  - url: "https://github.com/orgs/community/discussions/16107"
+    label: "GitHub Community #16107 — Schedule trigger target branch request"
+  - url: "https://stackoverflow.com/questions/63612155/how-do-i-trigger-a-scheduled-action-on-a-specific-branch"
+    label: "Stack Overflow: How to trigger a scheduled action on a specific branch"