@htekdev/actions-debugger 1.0.117 → 1.0.119

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

@@ -0,0 +1,133 @@
+id: caching-artifacts-069
+title: 'actions/cache save@v5 "Unable to Reserve Cache" When Key Already Exists for Same Branch'
+category: caching-artifacts
+severity: warning
+tags:
+  - cache
+  - cache-save
+  - v5
+  - immutable
+  - key-exists
+  - save-only
+  - reserve-cache
+patterns:
+  - regex: 'Unable to reserve cache with key .+, another job may be creating this cache'
+    flags: 'i'
+  - regex: 'More Details: Key already reserved duplicate'
+    flags: 'i'
+  - regex: 'Failed to save: Unable to reserve cache'
+    flags: 'i'
+error_messages:
+  - 'Failed to save: Unable to reserve cache with key my-cache-key, another job may be creating this cache.'
+  - 'Warning: Cache save failed.'
+  - 'More Details: Key already reserved duplicate'
+root_cause: |
+  GitHub's cache service is write-once per key+branch combination. Once a cache entry
+  has been successfully written for a given key on a given branch/ref, that key cannot
+  be overwritten. The slot is permanently "reserved" by the first writer.
+
+  When using `actions/cache/save@v5` (the standalone save action, separate from the
+  combined restore+save `actions/cache@v5`), the action does NOT automatically skip the
+  save if an exact cache key match already exists. It attempts to write the cache, the
+  service returns "Key already reserved duplicate" (v5 API uses proper JSON errors
+  unlike v3/v4 which returned HTML DOCTYPE responses), and the action emits:
+    "Failed to save: Unable to reserve cache with key X, another job may be creating this cache."
+    "Warning: Cache save failed."
+
+  This differs from the combined `actions/cache@v5` which checks the CACHE_HIT output
+  from its restore step and automatically skips the save on an exact key match. When
+  using the split restore/save pattern (actions/cache/restore + actions/cache/save),
+  the save action has no restore step context, so it always attempts to write —
+  triggering this warning when the key already exists from a previous workflow run.
+
+  Common trigger scenarios:
+  - Using actions/cache/save@v5 in an always() post step to save a cache built during
+    the job, on the second+ run of the same workflow on the same branch
+  - Using @actions/cache npm package's saveCache() directly without first checking
+    whether the key was already restored (restoreCache returned an exact match)
+  - Parallel jobs on the same branch all attempting to save under the same static key
+fix: |
+  Option 1 (recommended): Gate the save step on cache-miss.
+  Use actions/cache/restore@v5 first and only run the save step when the primary key
+  was not an exact hit:
+
+    - name: Restore cache
+      id: restore
+      uses: actions/cache/restore@v5
+      with:
+        key: ${{ env.CACHE_KEY }}
+        path: ~/.cache/my-tool
+
+    - name: Build
+      run: make build
+
+    - name: Save cache
+      if: steps.restore.outputs.cache-hit != 'true'
+      uses: actions/cache/save@v5
+      with:
+        key: ${{ env.CACHE_KEY }}
+        path: ~/.cache/my-tool
+
+  Option 2: Use the combined actions/cache@v5 which handles this automatically.
+
+  Option 3 (programmatic): If using @actions/cache npm package, check restoreCache
+  return value before calling saveCache — skip save if the return value matches the
+  primary key (exact hit).
+fix_code:
+  - language: yaml
+    label: 'Option 1 — gate save on cache-miss from restore step'
+    code: |
+      steps:
+        - name: Restore cache
+          id: cache-restore
+          uses: actions/cache/restore@v5
+          with:
+            key: ${{ runner.os }}-build-${{ hashFiles('**/lockfiles') }}
+            restore-keys: |
+              ${{ runner.os }}-build-
+            path: |
+              ~/.cache/my-tool
+              node_modules
+
+        - name: Build
+          run: make all
+
+        # Only save when the primary key was not an exact hit
+        - name: Save cache
+          if: steps.cache-restore.outputs.cache-hit != 'true'
+          uses: actions/cache/save@v5
+          with:
+            key: ${{ runner.os }}-build-${{ hashFiles('**/lockfiles') }}
+            path: |
+              ~/.cache/my-tool
+              node_modules
+  - language: yaml
+    label: 'Option 2 — use combined cache action (auto-skips save on exact hit)'
+    code: |
+      steps:
+        - name: Cache dependencies
+          uses: actions/cache@v5
+          with:
+            key: ${{ runner.os }}-build-${{ hashFiles('**/lockfiles') }}
+            restore-keys: |
+              ${{ runner.os }}-build-
+            path: |
+              ~/.cache/my-tool
+              node_modules
+prevention:
+  - 'Prefer the combined actions/cache@v5 over split restore/save when the primary key
+    is static or content-hash-based — the combined action skips save on exact hit automatically'
+  - 'When using split restore/save, always gate the save step with
+    if: steps.<restore-id>.outputs.cache-hit != ''true'''
+  - 'Never treat "Warning: Cache save failed." as a hard error when using static cache keys
+    across repeated runs — add continue-on-error: true to the save step if the warning
+    is expected and the restored cache is already valid'
+  - 'For programmatic use via @actions/cache npm package, check the return value of
+    restoreCache() before calling saveCache() — skip save when result === primaryKey'
+docs:
+  - url: 'https://github.com/actions/cache/issues/1707'
+    label: 'actions/cache#1707 — Unable to reserve cache (actions/cache/save@v5)'
+  - url: 'https://github.com/actions/cache/tree/main/save#readme'
+    label: 'actions/cache save action README — Case 1: reuse key as-is'
+  - 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-070.yml

@@ -0,0 +1,94 @@
+id: caching-artifacts-070
+title: "setup-python Post step fails — pip cache directory doesn't exist on disk"
+category: caching-artifacts
+severity: error
+tags:
+  - setup-python
+  - pip
+  - cache
+  - post-step
+  - cache-miss
+  - no-dependencies
+  - python-version-bump
+patterns:
+  - regex: 'Cache folder path is retrieved for pip but doesn.t exist on disk'
+    flags: 'i'
+  - regex: 'likely indicates that there are no dependencies to cache'
+    flags: 'i'
+  - regex: 'Post Setup Python.*fail|Post.*setup-python.*error'
+    flags: 'i'
+error_messages:
+  - "Cache folder path is retrieved for pip but doesn't exist on disk: /home/runner/.cache/pip. This likely indicates that there are no dependencies to cache. Consider removing the cache step if it is not needed."
+root_cause: |
+  When actions/setup-python is configured with cache: 'pip', the action records the expected
+  pip cache directory path at setup time (/home/runner/.cache/pip on Linux, equivalent on
+  macOS/Windows). The Post Setup Python step runs at job end and attempts to save the cache
+  to that path. If the directory does not exist on disk at save time, the Post step fails
+  with this error.
+
+  Two common causes:
+
+  1. No pip install ran in the job: The job uses cache: 'pip' but only runs linting or other
+     pre-installed tools without installing any Python packages. Pip never creates its cache
+     directory, so there is nothing to save. The job's actual steps appear green while the
+     Post step fails and turns the overall workflow run red.
+
+  2. Python version bump causes cache key miss: When the Python patch version changes (e.g.,
+     from 3.13.5 to 3.13.6), the setup-python cache key changes and the first run after the
+     bump experiences a full cache miss. If pip install runs but writes packages to a virtual
+     environment rather than the global pip cache (/home/runner/.cache/pip), the expected
+     directory remains empty and the Post step fails. Subsequent runs after the new cache is
+     warmed succeed.
+
+  The failure is deceptive because it surfaces in the Post Setup Python cleanup step — well
+  after the test or build steps have already succeeded — making it easy to overlook the root
+  cause.
+fix: |
+  - Remove cache: 'pip' from any setup-python step in jobs that do not call pip install.
+    Linting-only jobs, type-check-only jobs, and jobs that rely entirely on pre-installed
+    system Python do not benefit from pip caching.
+  - If pip install does run, ensure it runs against the global pip (not a virtualenv that
+    bypasses /home/runner/.cache/pip) so the post step can find and save the cache.
+  - Upgrade to actions/setup-python@v5 or later: newer versions emit a warning annotation
+    instead of failing the step when the cache directory is missing.
+  - After a Python version bump, the first run is expected to cache-miss; monitor for Post
+    step failures on that first run and confirm subsequent runs succeed.
+fix_code:
+  - language: yaml
+    label: 'Fix: Remove cache when no pip install runs'
+    code: |
+      # WRONG: cache: pip set but job only lints — no pip install → Post step fails
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+          cache: 'pip'            # ← REMOVE when no pip install follows
+      - name: Lint
+        run: flake8 .             # no pip install; /home/runner/.cache/pip never created
+
+      # CORRECT: omit cache when the job does not install packages
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+          # no cache key — Post step skips cache save attempt entirely
+      - name: Lint
+        run: flake8 .
+  - language: yaml
+    label: 'Fix: Upgrade to setup-python@v5 for graceful handling'
+    code: |
+      # CORRECT: v5+ emits a warning annotation instead of failing when cache path missing
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+prevention:
+  - 'Only set cache: pip on jobs that actually run pip install — linting-only jobs should omit it.'
+  - 'Use actions/setup-python@v5 or later; it handles missing cache directories with a warning instead of a failure.'
+  - 'After bumping the Python patch version in python-version:, expect one cache-miss run and watch for Post step failures on that run only.'
+  - 'When using virtual environments (venv/pipenv/poetry), ensure pip still writes to the global cache or configure cache-dependency-path appropriately.'
+docs:
+  - url: 'https://github.com/actions/setup-python/issues/1169'
+    label: 'setup-python#1169: Cache folder path doesn''t exist on disk (Aug 2025)'
+  - url: 'https://github.com/actions/setup-python'
+    label: 'actions/setup-python: Caching packages documentation'

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

@@ -0,0 +1,127 @@
+id: concurrency-timing-056
+title: 'Workflow-level and job-level concurrency share same group key — deadlock cancellation fires immediately'
+category: concurrency-timing
+severity: error
+tags:
+  - concurrency
+  - deadlock
+  - workflow-level
+  - job-level
+  - reusable-workflow
+  - workflow-call
+  - github-workflow-context
+patterns:
+  - regex: 'Canceling since a deadlock for concurrency group .* was detected between'
+    flags: 'i'
+  - regex: 'deadlock.*concurrency group|concurrency group.*deadlock'
+    flags: 'i'
+error_messages:
+  - "Canceling since a deadlock for concurrency group 'ci-refs/heads/main' was detected between 'top level workflow' and 'deploy'"
+  - "Canceling since a deadlock for concurrency group 'release-refs/heads/main' was detected between 'top level workflow' and 'api'"
+root_cause: |
+  GitHub Actions fires a deadlock error and immediately cancels the offending job when the
+  same concurrency group name is held simultaneously by two levels within a single workflow
+  execution. Two distinct scenarios trigger this:
+
+  Scenario 1 — Same-workflow self-deadlock: A workflow file defines concurrency: at the
+  workflow level AND one of its jobs also defines jobs.<id>.concurrency: using an expression
+  that evaluates to the same string:
+
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}   # workflow-level slot
+
+    jobs:
+      deploy:
+        concurrency:
+          group: ${{ github.workflow }}-${{ github.ref }}  # same string → deadlock
+        runs-on: ubuntu-latest
+
+  Scenario 2 — Reusable callee inherits caller context: A calling workflow has workflow-level
+  concurrency using ${{ github.workflow }}-${{ github.ref }}. The called reusable workflow
+  also defines workflow-level concurrency with the same expression. Because github.workflow
+  inside a reusable workflow inherits the CALLER's workflow name (not the callee's filename),
+  both evaluate to the identical group key and GitHub detects a deadlock.
+
+  github.workflow_ref also inherits from the top-level caller and does NOT produce a unique
+  value in the callee context; it cannot be used to distinguish caller from callee.
+fix: |
+  Scenario 1 — Remove the duplicate concurrency block. Keep either the workflow-level OR
+  the job-level declaration, not both with the same key. If per-job isolation is needed,
+  append ${{ github.job }} to the job-level group name:
+
+    jobs:
+      deploy:
+        concurrency:
+          group: ${{ github.workflow }}-${{ github.ref }}-${{ github.job }}
+
+  Scenario 2 — Remove the concurrency: block entirely from the reusable workflow. The
+  caller's workflow-level concurrency already governs the entire execution. If the callee
+  needs standalone concurrency when triggered via workflow_dispatch, use a hardcoded unique
+  prefix instead of ${{ github.workflow }}:
+
+    concurrency:
+      group: deploy-${{ github.ref }}   # hardcoded prefix avoids collision with any caller
+      cancel-in-progress: true
+fix_code:
+  - language: yaml
+    label: 'Scenario 1 fix: remove duplicate job-level concurrency'
+    code: |
+      # WRONG — identical group at workflow level and job level → deadlock
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        deploy:
+          concurrency:
+            group: ${{ github.workflow }}-${{ github.ref }}  # ← DELETE THIS
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo deploying
+
+      # CORRECT — concurrency only at workflow level
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo deploying
+  - language: yaml
+    label: 'Scenario 2 fix: remove concurrency from reusable workflow'
+    code: |
+      # deploy.yml (reusable) — WRONG: workflow-level concurrency collides with caller
+      # because github.workflow returns the CALLER's name in reusable context
+      on:
+        workflow_call:
+        workflow_dispatch:
+      # concurrency:               ← DELETE this entire block from the reusable workflow
+      #   group: ${{ github.workflow }}-${{ github.ref }}
+      #   cancel-in-progress: true
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo deploying
+
+      # If standalone concurrency is needed for workflow_dispatch calls, use hardcoded prefix:
+      # concurrency:
+      #   group: deploy-${{ github.ref }}   # hardcoded "deploy-" avoids collision
+      #   cancel-in-progress: true
+prevention:
+  - 'Before adding concurrency: to a reusable workflow, check if it will be called via workflow_call — if so, remove it or use a hardcoded prefix.'
+  - 'Never use the same concurrency group expression at both the workflow level and job level in the same file.'
+  - 'Note that ${{ github.workflow }} and ${{ github.workflow_ref }} both return the top-level caller''s values inside a reusable workflow; neither provides the callee''s filename.'
+  - 'Use actionlint to statically detect identical concurrency groups — issue actionlint#538 tracks adding this check.'
+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://stackoverflow.com/questions/78101326/github-actions-concurrency-deadlock'
+    label: 'SO: GitHub Actions concurrency deadlock (Score 6, 1.7K views)'
+  - url: 'https://stackoverflow.com/questions/79511940/using-workflow-filename-in-concurrency-group-for-workflows-started-by-workflow-c'
+    label: 'SO: Using workflow filename in concurrency group for workflow_call (Score 3)'
+  - url: 'https://github.com/github/vscode-github-actions/issues/135'
+    label: 'vscode-github-actions#135: Identical concurrency groups cause silent never-run (14 reactions)'

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

@@ -0,0 +1,115 @@
+id: concurrency-timing-057
+title: "Fork PRs with Identical Branch Names Share Concurrency Group and Cancel Each Other"
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - fork
+  - pull_request
+  - head_ref
+  - cancel-in-progress
+  - silent-cancel
+patterns:
+  - regex: 'group.*github\.head_ref'
+    flags: 'i'
+  - regex: 'This run was cancelled'
+    flags: 'i'
+error_messages:
+  - "This run was cancelled."
+  - "Run was cancelled."
+root_cause: |
+  When a workflow uses 'github.head_ref' as the sole identifier in a
+  concurrency group key (a common pattern to cancel stale runs on the same
+  branch), all pull requests that share a branch name across different forks
+  map to the SAME concurrency group. With 'cancel-in-progress: true', the
+  latest queued run cancels all earlier runs in that group — including runs
+  from completely unrelated PRs in OTHER contributor forks.
+
+  Example scenario:
+  - Fork A (alice/myrepo) opens PR from branch 'fix/auth-bug'.
+  - Fork B (bob/myrepo) opens a PR from a branch also named 'fix/auth-bug'.
+  - Both PRs target the same upstream repo (org/myrepo).
+  - Concurrency group: 'ci-fix/auth-bug' (from github.head_ref).
+  - When Fork B's PR triggers a run, it cancels Fork A's in-progress run.
+
+  The cancellation appears as "This run was cancelled" with no explanation
+  that a different fork's PR caused it. Maintainers and contributors see
+  flaky-looking CI with no obvious cause.
+
+  This is especially common in:
+  - Large open-source projects where many contributors use the same
+    conventional branch names (fix/typo, docs/readme, feature/x).
+  - Dependabot/Renovate PRs across forks — all use the same structured
+    branch name pattern (dependabot/npm_and_yarn/lodash-4.0.0).
+fix: |
+  Include 'github.event.pull_request.number' in the concurrency group key.
+  PR numbers are unique per repository, so two PRs from different forks
+  always have different numbers even if their branch names collide.
+
+  Alternative: use 'github.run_id' for maximum uniqueness (no cancellation
+  across runs at all), but this defeats the purpose of cancel-in-progress
+  for the same PR.
+
+  The recommended pattern from GitHub documentation:
+  group: '${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}'
+
+  The '|| github.ref' fallback handles non-PR events (push, schedule)
+  where 'github.event.pull_request.number' is empty.
+fix_code:
+  - language: yaml
+    label: "Broken — github.head_ref alone causes cross-fork cancellation"
+    code: |
+      concurrency:
+        group: ci-${{ github.head_ref }}   # ❌ Collides across forks with same branch name
+        cancel-in-progress: true
+
+  - language: yaml
+    label: "Fixed — include PR number to ensure per-PR uniqueness"
+    code: |
+      concurrency:
+        # PR number is unique per repo — different forks never collide
+        group: '${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}'
+        cancel-in-progress: true
+
+  - language: yaml
+    label: "Alternative — include repo owner to scope per fork"
+    code: |
+      concurrency:
+        # Include head repo full_name to distinguish forks explicitly
+        group: >-
+          ${{ github.workflow }}-
+          ${{ github.event.pull_request.head.repo.full_name || github.repository }}-
+          ${{ github.event.pull_request.number || github.ref }}
+        cancel-in-progress: true
+
+  - language: yaml
+    label: "Recommended pattern from GitHub docs — workflow + PR number or ref"
+    code: |
+      name: CI
+      on:
+        pull_request:
+        push:
+          branches: [main]
+
+      concurrency:
+        group: '${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}'
+        cancel-in-progress: true
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./run-tests.sh
+
+prevention:
+  - "Never use github.head_ref alone as a concurrency group key for pull_request workflows."
+  - "Always pair github.head_ref with github.event.pull_request.number to scope to the specific PR."
+  - "Use the GitHub-recommended pattern: '${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}'."
+  - "Test concurrency behavior by opening two PRs from different forks with the same branch name before merging concurrency configuration."
+  - "On public repos with many external contributors, audit all concurrency group keys for cross-fork collision risk."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency"
+    label: "GitHub Docs — Using concurrency (recommended group key pattern)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#concurrency"
+    label: "GitHub Docs — Workflow syntax: concurrency"

package/errors/concurrency-timing/workflow-run-head-branch-null-schedule-dispatch-concurrency.yml

@@ -0,0 +1,135 @@
+id: concurrency-timing-055
+title: '`github.event.workflow_run.head_branch` is null for `schedule`- and `workflow_dispatch`-triggered
+  parent workflows — concurrency group key collapses all downstream runs into one slot'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - workflow_run
+  - concurrency
+  - head_branch
+  - schedule
+  - null-key
+  - deployment
+patterns:
+  - regex: 'on:\s+workflow_run:'
+    flags: 'si'
+  - regex: 'group:.*event\.workflow_run\.head_branch'
+    flags: 'i'
+error_messages:
+  - "Canceling since a higher priority waiting run was found for the same concurrency group"
+  - "This run has been cancelled. Concurrency group: deploy-"
+root_cause: |
+  `github.event.workflow_run.head_branch` is null/empty when the triggering (upstream)
+  workflow was itself triggered by `schedule`, `workflow_dispatch`, `repository_dispatch`,
+  or any other non-branch event. Only workflows triggered by branch-based events (push,
+  pull_request, etc.) produce a non-null head_branch value.
+
+  The standard recommendation for workflow_run-triggered workflows (see also
+  concurrency-timing-045) is to key the concurrency group on head_branch:
+
+      concurrency:
+        group: deploy-${{ github.event.workflow_run.head_branch }}
+
+  For branch-based parent triggers this works correctly. For schedule- or
+  workflow_dispatch-triggered parent workflows, head_branch is null, making the
+  concurrency group key evaluate to `deploy-` (empty suffix). Every downstream run
+  where the parent was triggered by schedule or dispatch shares the SAME concurrency
+  slot. The second scheduled downstream run cancels the first — silently, because
+  `${{ null }}` evaluates to an empty string in GitHub Actions expressions with no
+  warning or error.
+
+  This is commonly introduced when teams follow a deploy-after-CI pattern where the
+  nightly build (schedule) triggers a downstream deploy/notify workflow_run workflow
+  and copy the branch-scoped concurrency pattern from another workflow.
+fix: |
+  Add a fallback value to handle null head_branch, or use a more robust key.
+
+  Option 1 — head_branch with workflow_run.id fallback (recommended):
+    Use head_branch when available (branch-based parent) and fall back to the unique
+    workflow_run id (schedule/dispatch parent) to guarantee no cross-run collisions.
+
+  Option 2 — workflow_run.id only:
+    If the workflow_run-triggered downstream workflow is exclusively for non-branch
+    parents (schedule, dispatch), key the group on github.event.workflow_run.id.
+    Every downstream run gets its own unique slot.
+
+  Option 3 — Restrict trigger with branches: filter:
+    Limit the workflow_run trigger to branch-based parent runs using `branches:`.
+    Schedule/dispatch-triggered completions are silently ignored so there is no
+    concurrency collision to manage.
+fix_code:
+  - language: yaml
+    label: 'WRONG — head_branch is null for schedule-triggered parents; all runs share one slot'
+    code: |
+      on:
+        workflow_run:
+          workflows: ["Nightly Build"]
+          types: [completed]
+
+      concurrency:
+        group: deploy-${{ github.event.workflow_run.head_branch }}
+        cancel-in-progress: true
+
+      jobs:
+        deploy:
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying..."
+  - language: yaml
+    label: 'RIGHT — fallback to workflow_run.id prevents slot collision for schedule parents'
+    code: |
+      on:
+        workflow_run:
+          workflows: ["Nightly Build"]
+          types: [completed]
+
+      # head_branch is populated for push/pull_request-triggered parents
+      # workflow_run.id is always unique — prevents cross-run collision for schedule/dispatch parents
+      concurrency:
+        group: deploy-${{ github.event.workflow_run.head_branch || github.event.workflow_run.id }}
+        cancel-in-progress: true
+
+      jobs:
+        deploy:
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying commit ${{ github.event.workflow_run.head_sha }}"
+  - language: yaml
+    label: 'RIGHT — restrict workflow_run to branch-based parents only'
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+          branches: [main, 'release/**']
+          # schedule- and workflow_dispatch-triggered parent completions have no branch;
+          # the branches: filter excludes them, so no null head_branch issue
+
+      concurrency:
+        group: deploy-${{ github.event.workflow_run.head_branch }}
+        cancel-in-progress: true
+
+      jobs:
+        deploy:
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying branch ${{ github.event.workflow_run.head_branch }}"
+prevention:
+  - 'Always check whether parent workflows may be triggered by schedule or workflow_dispatch before
+    keying a workflow_run downstream concurrency group on head_branch.'
+  - 'Add a || fallback for any workflow_run context property that may be null — head_branch, head_sha,
+    and pull_requests are null for schedule/dispatch-triggered parents.'
+  - 'Add a debug step that echoes github.event.workflow_run.head_branch early in the workflow to verify
+    it is populated for all expected parent trigger types during initial rollout.'
+  - 'Use branches: on the workflow_run trigger to restrict to branch-based events if schedule/dispatch
+    parent completions do not need to be handled.'
+docs:
+  - url: 'https://docs.github.com/en/webhooks/webhook-events-and-payloads#workflow_run'
+    label: 'GitHub Webhook Docs: workflow_run payload — head_branch property'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run'
+    label: 'GitHub Docs: workflow_run event trigger'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency'