@htekdev/actions-debugger 1.0.124 → 1.0.125

package/errors/runner-environment/runner-environment-233.yml

@@ -0,0 +1,90 @@
+id: runner-environment-233
+title: 'actions/checkout < v6.0.3 fails on SHA-256 repositories — fatal: mismatched algorithms: client sha1; server sha256'
+category: runner-environment
+severity: error
+tags:
+  - checkout
+  - sha256
+  - git
+  - object-format
+  - hash-algorithm
+  - repository
+  - v6
+patterns:
+  - regex: 'fatal: mismatched algorithms: client sha1; server sha256'
+    flags: 'i'
+  - regex: 'fatal: mismatched algorithms: client sha256; server sha1'
+    flags: 'i'
+  - regex: 'mismatched algorithms.*sha1.*sha256'
+    flags: 'i'
+error_messages:
+  - 'fatal: mismatched algorithms: client sha1; server sha256'
+  - "The process '/usr/bin/git' failed with exit code 128"
+root_cause: |
+  GitHub is progressively rolling out support for SHA-256 object-format repositories
+  (also called NewHash or sha256-mode repos). When a repository is SHA-256-mode,
+  every git object reference is a 64-character hex SHA-256 hash instead of the
+  traditional 40-character SHA-1 hash.
+
+  Before actions/checkout v6.0.3, the checkout action always initialised the local
+  working-tree repository with a plain `git init`, which defaults to SHA-1 object
+  format. When the action then attempts to `git fetch` from a SHA-256 remote, git
+  detects that the local and remote repositories use different hash algorithms and
+  immediately aborts:
+
+    fatal: mismatched algorithms: client sha1; server sha256
+
+  The mismatch is unrecoverable — the local repository must be created with
+  `git init --object-format=sha256` BEFORE the first fetch. There is no in-place
+  conversion.
+
+  This only affects workflows where the target GitHub repository has been migrated
+  to or created as SHA-256 mode. GitHub began rolling out SHA-256 repository creation
+  in late 2025; adoption will grow over time. Previously-created SHA-1 repositories
+  are unaffected until they are explicitly migrated.
+
+  The fix shipped in actions/checkout v6.0.3 (June 2, 2026, commit 1cce339).
+  It calls the GitHub REST endpoint `GET /repos/{owner}/{repo}/hash-algorithm`
+  before `git init` and passes `--object-format=sha256` when the repository is
+  SHA-256 mode.
+
+  Source: actions/checkout#2160, PR#2439.
+fix: |
+  Upgrade to actions/checkout@v6.0.3 or later. Version v6.0.3 detects the
+  repository's object format via the GitHub API before initialising the local
+  git repository and passes the correct `--object-format` flag to `git init`.
+
+  If you cannot upgrade immediately, set the GIT_DEFAULT_HASH environment variable
+  to sha256 before running checkout, then reinitialise manually — but upgrading
+  the action is strongly preferred.
+
+  Note: v6.0.3 introduced a new REST API call (`GET /repos/.../hash-algorithm`) on
+  every checkout, which can cause secondary rate-limit issues for organisations with
+  very high parallel job counts. See runner-environment-206 for that separate issue.
+fix_code:
+  - language: yaml
+    label: 'Upgrade to actions/checkout v6.0.3+ to fix SHA-256 repository support'
+    code: |
+      - uses: actions/checkout@v6.0.3
+        with:
+          fetch-depth: 1
+  - language: yaml
+    label: 'Pin to v6.0.3+ by SHA for reproducibility (recommended for security-sensitive workflows)'
+    code: |
+      # Pin to the exact commit SHA of v6.0.3 to lock the version
+      - uses: actions/checkout@1cce3390c2bfda521930d01229c073c7ff920824  # v6.0.3
+        with:
+          fetch-depth: 1
+prevention:
+  - 'Always pin to a specific patch version of actions/checkout (e.g., @v6.0.3) rather than a floating major tag (@v6), so breaking changes from new GitHub repository features land on your own schedule'
+  - 'If your organisation creates new repositories, check whether SHA-256 mode is the default; SHA-256 repos will silently break all workflows using checkout < v6.0.3'
+  - 'Monitor the actions/checkout changelog when upgrading; v6.0.3 also introduced a new API call that can affect rate limits in high-parallelism environments (see runner-environment-206)'
+docs:
+  - url: 'https://github.com/actions/checkout/issues/2160'
+    label: 'actions/checkout#2160 — hashing mismatch error on SHA-256 repository'
+  - url: 'https://github.com/actions/checkout/pull/2439'
+    label: 'actions/checkout PR#2439 — Fix checkout init for SHA-256 repositories (merged June 2026)'
+  - url: 'https://github.com/actions/checkout/releases/tag/v6.0.3'
+    label: 'actions/checkout v6.0.3 release — SHA-256 repository support'
+  - url: 'https://git-scm.com/docs/hash-function-transition'
+    label: 'Git documentation — SHA-256 hash function transition'

package/errors/runner-environment/runner-environment-234.yml

@@ -0,0 +1,114 @@
+id: runner-environment-234
+title: "actions/checkout v6 credential helper overrides embedded PAT in cross-repo git push — 403 Permission denied to github-actions[bot]"
+category: runner-environment
+severity: error
+tags:
+  - checkout
+  - v6
+  - credential-helper
+  - cross-repo
+  - PAT
+  - git-push
+  - extraheader
+  - 403
+  - permission-denied
+patterns:
+  - regex: 'remote: Permission to .+\.git denied to github-actions\[bot\]'
+    flags: 'i'
+  - regex: 'fatal: unable to access .+github\.com.+: The requested URL returned error: 403'
+    flags: 'i'
+  - regex: 'Permission denied to github-actions\[bot\]\.'
+    flags: 'i'
+error_messages:
+  - 'remote: Permission to owner/nightly-releases.git denied to github-actions[bot].'
+  - 'fatal: unable to access ''https://github.com/owner/repo/'': The requested URL returned error: 403'
+root_cause: |
+  When a workflow uses actions/checkout v6 and then manually adds a second git remote
+  whose URL embeds a Personal Access Token (PAT), the cross-repo git push fails with
+  a 403 even though the PAT is valid and has the required scope.
+
+  actions/checkout injects a GitHub token (GITHUB_TOKEN by default) into the local
+  git configuration as an HTTP Authorization header for `https://github.com/` URLs
+  via `http.https://github.com/.extraheader`. A common pattern to push to a separate
+  repository using a PAT is to:
+    1. Add a remote with the PAT embedded in the URL:
+         git remote add nightly_repo https://TOKEN@github.com/owner/repo.git
+    2. Remove the checkout-injected extraheader to prevent it from conflicting:
+         git config --unset-all http.https://github.com/.extraheader
+    3. Push via the PAT URL remote.
+
+  This pattern worked correctly with actions/checkout v4 and v5. In v6, the sequence
+  fails because the action now also registers a git credential helper
+  (`credential.https://github.com.helper`) alongside the extraheader. When the
+  extraheader is manually unset in step 2, the credential helper remains configured.
+  Git consults the credential helper for all `https://github.com/` requests —
+  including the push to the PAT URL remote — and the helper returns GITHUB_TOKEN
+  (authenticated as `github-actions[bot]`). This token overrides the PAT embedded
+  in the remote URL, and since `github-actions[bot]` does not have write access to
+  the target repository, the push fails with HTTP 403.
+
+  The root distinction from earlier versions: unsetting `http.extraheader` alone is
+  no longer sufficient to fully remove checkout's credential injection in v6.
+
+  Source: actions/checkout#2424 (April 2026, open).
+fix: |
+  **Option 1 (recommended): Use `persist-credentials: false` in checkout.**
+  This prevents checkout from configuring any git credentials at all. The subsequent
+  git push uses the PAT embedded in the remote URL without interference.
+
+  **Option 2: Explicitly clear the credential helper after checkout.**
+  After the checkout step, unset both the extraheader AND the credential helper:
+    git config --unset-all http.https://github.com/.extraheader || true
+    git config --global --unset credential.https://github.com.helper || true
+    git config --global --unset credential.helper || true
+
+  Note: the exact helper key may vary; inspect `git config --list` to see all keys
+  set by checkout before unsetting.
+
+  **Option 3: Provide the PAT via the checkout `token:` input instead.**
+  If the PAT has access to both the primary repo and the target cross-repo, pass it
+  as the `token:` input so checkout configures it as the credential for all
+  github.com pushes. This avoids the need to inject a second credential entirely.
+fix_code:
+  - language: yaml
+    label: 'Recommended: use persist-credentials: false and embed PAT in remote URL'
+    code: |
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false   # prevents checkout from injecting any git credentials
+
+      - name: Push tags to nightly releases repository
+        env:
+          NIGHTLY_PAT: ${{ secrets.NIGHTLY_PAT }}
+        run: |
+          git remote add nightly_repo \
+            "https://${NIGHTLY_PAT}@github.com/owner/nightly-releases.git"
+          git tag -f nightly
+          git push -f nightly_repo nightly
+  - language: yaml
+    label: 'Alternative: pass PAT to checkout token: input (when PAT has access to primary repo)'
+    code: |
+      - uses: actions/checkout@v6
+        with:
+          # If CROSS_REPO_PAT has access to the checked-out repo as well,
+          # checkout will configure it for all github.com credential requests.
+          token: ${{ secrets.CROSS_REPO_PAT }}
+
+      - name: Push tags to nightly releases repository
+        run: |
+          git remote add nightly_repo \
+            "https://${{ secrets.CROSS_REPO_PAT }}@github.com/owner/nightly-releases.git"
+          git tag -f nightly
+          git push -f nightly_repo nightly
+prevention:
+  - 'Use `persist-credentials: false` in any checkout step that is followed by a cross-repo git push using a PAT, to avoid checkout credential helpers interfering with the push'
+  - 'When debugging 403 errors on git push, check `git config --list` to see all credential-related configuration; look for any helper or extraheader keys referencing github.com'
+  - 'Avoid relying on unsetting only `http.https://github.com/.extraheader` to remove checkout credentials in v6+; the set of keys checkout writes has changed across versions'
+  - 'When migrating from actions/checkout v4/v5 to v6, test all workflows that manually manipulate git credentials or push to cross-repo remotes'
+docs:
+  - url: 'https://github.com/actions/checkout/issues/2424'
+    label: 'actions/checkout#2424 — Unable to create tags in another repo with v6 (403 Permission denied)'
+  - url: 'https://github.com/actions/checkout#usage'
+    label: 'actions/checkout README — persist-credentials input'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication'
+    label: 'GitHub Docs — GITHUB_TOKEN automatic token authentication'

package/errors/runner-environment/runner-environment-235.yml

@@ -0,0 +1,151 @@
+id: runner-environment-235
+title: 'Action download fails with HTTP 429 Too Many Requests during action resolution — "Failed to download action ... Response status code does not indicate success: 429"'
+category: runner-environment
+severity: error
+tags:
+  - action-download
+  - rate-limit
+  - 429
+  - action-resolution
+  - tarball
+  - github-api
+  - outage
+  - retry
+patterns:
+  - regex: 'Failed to download action.*429|Response status code does not indicate success: 429 \(Too Many Requests\)'
+    flags: 'i'
+  - regex: 'Error: Response status code does not indicate success: 429'
+    flags: 'i'
+  - regex: 'Warning: Failed to download action.*tarball'
+    flags: 'i'
+error_messages:
+  - "Warning: Failed to download action 'https://api.github.com/repos/actions/checkout/tarball/11bd71901bbe5b1630ceea73d27597364c9af683'. Error: Response status code does not indicate success: 429 (Too Many Requests)."
+  - "Error: Response status code does not indicate success: 429 (Too Many Requests)."
+  - "Download action repository 'actions/checkout@v4'"
+root_cause: |
+  When a GitHub Actions job starts, the runner downloads each action referenced in the
+  workflow by fetching the action's source tarball from the GitHub API endpoint:
+    GET https://api.github.com/repos/{owner}/{repo}/tarball/{sha}
+
+  This endpoint is subject to GitHub's API rate limits. When many runners start
+  simultaneously — during periods of high load, GitHub infrastructure incidents, or
+  large-scale rollouts — the tarball download requests can be rate-limited, returning
+  HTTP 429 Too Many Requests.
+
+  The runner logs a warning and retries with exponential backoff:
+    "Warning: Failed to download action '...'. Error: Response status code does not
+     indicate success: 429 (Too Many Requests). <correlationId>"
+
+  If the rate limit persists through all retry attempts, the job setup fails and the
+  entire job is marked as failed with "##[error]" on the "Set up job" step. The failure
+  is NOT a problem with the workflow configuration itself — it is a transient GitHub
+  infrastructure issue.
+
+  Contributing factors:
+  1. **GitHub outages or degraded performance** — action downloads share API quota with
+     all other GitHub API traffic from the runner's IP range.
+  2. **High parallel job counts** — organizations running hundreds of parallel jobs on
+     GitHub-hosted runners can exhaust rate limit buckets across a runner fleet.
+  3. **Composite actions with many nested uses** — deeply nested composite actions make
+     many download calls per job, multiplying the per-job API request count. PR #4296
+     in actions/runner (merged 2026-03) adds batching to reduce this.
+  4. **Self-hosted runners without caching** — runners that are freshly provisioned per
+     job always re-download all actions; runners with persistent `_work/_tool` directories
+     can cache downloads across jobs.
+
+  Note: this is distinct from runner-environment-202 (repeated downloads caused by
+  case-sensitivity mismatch in v2.334.0), which causes multiple SUCCESSFUL downloads
+  rather than 429 failures.
+
+  Source: actions/runner#4232 (Feb 2026, open), actions/checkout#2230.
+fix: |
+  **Immediate:** Retry the failed workflow run. 429 errors during action downloads
+  are almost always transient — a re-run a few minutes later usually succeeds.
+
+  **Short-term: Reduce per-job download requests.**
+  Pin actions to a specific commit SHA rather than a mutable tag. Runners maintain an
+  action download cache keyed by commit SHA; pinned SHAs hit the cache more reliably
+  than mutable tags which may require a fresh lookup each run.
+
+  **For self-hosted runners: persist the action cache directory.**
+  The runner caches downloaded actions in `<runner-root>/_work/_tool`. If your runner
+  instances are ephemeral (e.g., provisioned fresh per job on EC2/GKE), mount a shared
+  volume or EFS/EBS on this path to share the cache across instances, reducing
+  download traffic dramatically.
+
+  **For high-parallelism organizations: stagger workflow start times.**
+  Spread out scheduled workflows or push triggers to avoid thousands of jobs starting
+  simultaneously. Use concurrency groups or scheduled-at offsets to distribute load.
+
+  **Self-hosted runners on GHES / GHAE:** Use GHES's internal action caching to serve
+  action downloads locally instead of hitting GitHub.com — this avoids rate limiting
+  entirely.
+
+  **Monitor GitHub status:** Check https://www.githubstatus.com/ when 429 errors appear
+  — they often correlate with incidents listed on the status page.
+fix_code:
+  - language: yaml
+    label: 'Pin actions to commit SHA to maximize cache hits and reduce download requests'
+    code: |
+      # Instead of mutable tags (re-downloaded each time if tag moves):
+      # - uses: actions/checkout@v4
+      # - uses: actions/setup-node@v4
+
+      # Pin to immutable commit SHAs for reliable caching:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
+      - uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af  # v4.1.0
+  - language: yaml
+    label: 'Self-hosted runner: configure RUNNER_TOOL_CACHE to a persistent shared path'
+    code: |
+      # In the runner environment, set the tool cache path before starting the runner:
+      # export RUNNER_TOOL_CACHE=/mnt/shared/runner-tool-cache
+      # ./run.sh
+
+      # Or in the runner .env file (config/.env relative to the runner root):
+      # RUNNER_TOOL_CACHE=/mnt/shared/runner-tool-cache
+
+      # Docker-based self-hosted runner: mount the cache directory:
+      # docker run -v /mnt/shared/runner-tool-cache:/opt/hostedtoolcache ...
+  - language: yaml
+    label: 'Workflow-level retry: re-run the job automatically on setup failure'
+    code: |
+      # Actions does not have a built-in retry for setup failures.
+      # A common workaround: use a retry action in the first step that validates setup.
+      # Alternatively, set up a workflow_run trigger to retry on failure:
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+
+      jobs:
+        retry-on-429:
+          if: github.event.workflow_run.conclusion == 'failure'
+          runs-on: ubuntu-latest
+          steps:
+            - name: Re-trigger the failed workflow
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  await github.rest.actions.createWorkflowDispatch({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    workflow_id: 'ci.yml',
+                    ref: '${{ github.event.workflow_run.head_branch }}'
+                  });
+prevention:
+  - 'Pin all `uses:` references to immutable commit SHAs — this maximises the chance that the runner serves the action from its local download cache rather than calling the GitHub API'
+  - 'For self-hosted runners provisioned per job (ephemeral), mount a persistent shared volume at the runner tool cache path so action downloads are reused across job invocations'
+  - 'Upgrade to actions/runner v2.335.0+ which includes PR#4296 action resolution batching — this reduces the number of download requests per job for workflows using composite actions'
+  - 'When you see 429 errors, check https://www.githubstatus.com/ — they often coincide with GitHub API rate limit incidents affecting the entire platform'
+  - 'Spread scheduled workflows across different minutes using cron expressions like `17 4 * * *` rather than `0 4 * * *` to avoid the stampede effect when many organizations schedule jobs at round-number times'
+docs:
+  - url: 'https://github.com/actions/runner/issues/4232'
+    label: 'actions/runner#4232: Warning: Failed to download action ... 429 Too Many Requests'
+  - url: 'https://github.com/actions/checkout/issues/2230'
+    label: 'actions/checkout#2230: checkout fails with 429 Too Many Requests'
+  - url: 'https://github.com/actions/runner/pull/4296'
+    label: 'actions/runner PR#4296: Batch and deduplicate action resolution across composite depths (reduces 429 risk)'
+  - url: 'https://docs.github.com/en/rest/overview/rate-limits-for-the-rest-api'
+    label: 'GitHub Docs: REST API rate limits'
+  - url: 'https://www.githubstatus.com/'
+    label: 'GitHub Status page — check for active incidents when 429 errors appear'

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

@@ -0,0 +1,97 @@
+id: silent-failures-112
+title: 'Non-ephemeral self-hosted runner REST API busy flag desync causes auto-scaler to kill active job'
+category: silent-failures
+severity: silent-failure
+tags:
+  - self-hosted
+  - non-ephemeral
+  - rest-api
+  - autoscaling
+  - broker
+  - busy-flag
+  - desync
+  - aws
+patterns:
+  - regex: 'The runner has received a shutdown signal'
+    flags: 'i'
+  - regex: '"busy":\s*false'
+    flags: 'i'
+  - regex: 'broker\.actions\.githubusercontent\.com.*busy.*JobState'
+    flags: 'i'
+error_messages:
+  - '##[error]The runner has received a shutdown signal.'
+  - '"busy": false  ← REST API shows idle while broker actively renewing job lease'
+  - 'Successfully renew job, valid till ...'
+root_cause: |
+  On non-ephemeral self-hosted runners (runners that execute multiple sequential jobs on the same
+  instance), there is a state desynchronization between the broker layer
+  (broker.actions.githubusercontent.com) and the REST API endpoint
+  GET /repos/{owner}/{repo}/actions/runners/{runner_id}.
+
+  The failure sequence:
+  1. Runner completes Job A and briefly enters the Online/idle state.
+  2. Runner picks up Job B, transitions to Busy, and reports JobState: Busy to the broker.
+  3. The broker acknowledges the job and successfully renews the lease every 60 seconds
+     (logged as "Successfully renew job, valid till ...").
+  4. Despite (3), the REST API returns "busy": false — sometimes immediately when Job B starts,
+     sometimes after tracking correctly for several minutes before spontaneously flipping.
+  5. Auto-scaling infrastructure (AWS Lambda scaler, GKE controllers, terraform-aws-github-runner,
+     or custom polling services) queries the REST API, sees the runner as idle, and terminates the
+     EC2/VM instance mid-job.
+  6. Job B fails with "The runner has received a shutdown signal." No error is surfaced by GitHub's
+     UI indicating the runner was inappropriately killed.
+
+  The desync appears to occur at the Busy→Online transition boundary between jobs. The broker and
+  the REST API maintain separate state stores; in certain timing windows the REST API does not pick
+  up the Job B start event, leaving its state stale from the inter-job idle period.
+fix: |
+  Option 1 — Use ephemeral runners (recommended). Each runner instance handles exactly one job
+  and then terminates. There is no second job pick-up, so the busy-flag desync window never exists.
+
+  Option 2 — Do not rely solely on "busy": false from the REST API as the termination signal.
+  Cross-reference with a job-completion event (CloudWatch, Pub/Sub, broker callback) or add a
+  grace period of 60-120 seconds after the REST API first reports idle before terminating.
+
+  Option 3 — Use the Webhook-based ARC (Actions Runner Controller) instead of REST-poll-based
+  autoscaling. ARC receives direct runner lifecycle events and does not depend on the REST API
+  busy state for scale-down decisions.
+fix_code:
+  - language: hcl
+    label: 'Enable ephemeral runners in terraform-aws-github-runner to prevent multi-job desync'
+    code: |
+      module "runners" {
+        source  = "philips-labs/github-runner/aws"
+        version = "~> 6.6.0"
+
+        # Each instance executes exactly one job then terminates.
+        # Eliminates the busy-flag desync window between sequential jobs.
+        enable_ephemeral_runners = true
+
+        # ... other config
+      }
+
+  - language: yaml
+    label: 'Declare ephemeral runner label in the workflow'
+    code: |
+      jobs:
+        build:
+          # Request a fresh ephemeral runner — one job per instance.
+          # Requires your runner pool to be configured for ephemeral mode.
+          runs-on: [self-hosted, ephemeral, linux, x64]
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./build.sh
+prevention:
+  - 'Prefer ephemeral runners over reuse runners in autoscaling environments — one job per instance eliminates the busy-flag desync window entirely.'
+  - 'Never use "busy": false from the REST API as the sole signal for terminating a non-ephemeral runner instance.'
+  - 'Add a minimum 90-second grace period after the REST API first reports busy=false before terminating any non-ephemeral runner.'
+  - 'Monitor broker lease-renewal logs ("Successfully renew job") to track active job state independently of the REST API.'
+docs:
+  - url: 'https://github.com/actions/runner/issues/4422'
+    label: 'actions/runner#4422 — /runners REST API reports busy: false while broker says busy (open)'
+  - url: 'https://github.com/github-aws-runners/terraform-aws-github-runner'
+    label: 'terraform-aws-github-runner — ephemeral runner module'
+  - url: 'https://docs.github.com/en/rest/actions/self-hosted-runners#list-self-hosted-runners-for-a-repository'
+    label: 'GitHub Docs — REST API for self-hosted runners'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners'
+    label: 'GitHub Docs — About self-hosted runners'

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

@@ -0,0 +1,110 @@
+id: silent-failures-113
+title: 'Org-level self-hosted runner with correct group access never dispatched — job stays Queued indefinitely with no error'
+category: silent-failures
+severity: silent-failure
+tags:
+  - self-hosted
+  - runner-group
+  - org-runner
+  - dispatch
+  - queued
+  - v2-broker
+  - silent
+patterns:
+  - regex: 'runner_group_id.*null'
+    flags: 'i'
+  - regex: 'Waiting for a runner to pick up this job'
+    flags: 'i'
+error_messages:
+  - 'Waiting for a runner to pick up this job'
+  - '(job stays in Queued state indefinitely — no error message is displayed)'
+root_cause: |
+  When a self-hosted runner is registered at the **organization level** (not the
+  repository level) and added to a runner group with explicit per-repository access,
+  a bug in the V2 broker flow (`useV2Flow: true`,
+  `serverUrl: broker.actions.githubusercontent.com`) can cause the dispatcher to fail
+  to resolve the runner group membership against the target repository.
+
+  The result: the queued job never receives a `runner_group_id` assignment
+  (confirmed via `GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs` API, which
+  returns `runnerId: null`, `runnerName: null`, `runnerGroupId: null` throughout the
+  entire queue duration). The runner is online and idle throughout — it simply is
+  never offered the job.
+
+  From the UI perspective, the job shows the standard "Waiting for a runner to pick
+  up this job" message with no indication that the runner group resolution failed.
+  No error annotation is ever produced — the workflow just hangs until cancelled.
+
+  This failure mode has been observed under these conditions:
+  - Runner registered at organization scope
+  - Runner group has explicit per-repository access (not "All repositories")
+  - Runner version 2.334.0, V2 broker protocol enabled
+  - GitHub Team plan
+  - GitHub Enterprise Cloud is NOT required to reproduce
+
+  Repository-level runners using identical labels and configuration dispatch
+  correctly, confirming the bug is specific to the org-level + runner-group + V2
+  broker path.
+
+  The precise broker-side failure point is unknown; the hypothesis is an inconsistency
+  in how V2 broker resolves org runner group → repository access grant at dispatch time.
+fix: |
+  Immediate workaround: re-register the runner at the repository level instead of
+  the organization level.
+
+  1. Stop and unregister the org-level runner:
+     cd <runner-dir> && ./config.sh remove --token <removal-token>
+
+  2. Re-register at repository level:
+     ./config.sh --url https://github.com/<org>/<repo> --token <repo-token>
+
+  3. Trigger the workflow again — dispatch should proceed immediately.
+
+  If you need the runner to serve multiple repositories, repeat the registration
+  for each repository, or use runner groups with "All repositories" scope as an
+  interim workaround until GitHub resolves the V2 broker dispatch bug.
+
+  Track actions/runner#4429 for an official fix.
+fix_code:
+  - language: bash
+    label: 'Re-register runner at repository level instead of org level'
+    code: |
+      cd /path/to/runner
+
+      # Remove org-level registration
+      ./config.sh remove --token <ORG_REMOVAL_TOKEN>
+
+      # Re-register at repository level
+      ./config.sh \
+        --url https://github.com/<org>/<repo> \
+        --token <REPO_RUNNER_TOKEN> \
+        --name my-runner \
+        --labels my-label \
+        --unattended
+
+      # Start the runner
+      ./run.sh
+
+  - language: yaml
+    label: 'Workflow — no workflow change needed; fix is in runner registration scope'
+    code: |
+      # No changes needed in the workflow YAML itself.
+      # The runs-on label works correctly once the runner is repo-scoped.
+      jobs:
+        build:
+          runs-on: [self-hosted, my-label]
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "Runner dispatched correctly"
+prevention:
+  - 'Prefer repository-level runner registration for single-repo pipelines; use org-level runners only when the runner must serve many repos and test dispatch before rolling out.'
+  - 'After registering an org-level runner, verify dispatch with a simple echo workflow before building production pipelines on top of it.'
+  - 'Monitor actions/runner#4429 for a fix to the V2 broker org-runner-group dispatch resolution bug.'
+  - 'When investigating stuck jobs, use the REST API (GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs) to check if runnerGroupId is null — this confirms dispatch resolution failure rather than a resource-wait.'
+docs:
+  - url: 'https://github.com/actions/runner/issues/4429'
+    label: 'actions/runner#4429 — Org-level self-hosted runner never dispatched despite correct runner group repo access'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners'
+    label: 'GitHub Docs — Adding self-hosted runners (org vs repo level)'
+  - url: 'https://docs.github.com/en/rest/actions/self-hosted-runners'
+    label: 'GitHub REST API — Self-hosted runners'