@htekdev/actions-debugger 1.0.113 → 1.0.115

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

@@ -0,0 +1,86 @@
+id: runner-environment-194
+title: 'Job Blocked at Queue: "recent account payments have failed or your spending limit needs to be increased"'
+category: runner-environment
+severity: error
+tags:
+  - billing
+  - spending-limit
+  - payments
+  - job-blocked
+  - queue
+  - account
+patterns:
+  - regex: 'recent account payments have failed'
+    flags: 'i'
+  - regex: 'spending limit needs to be increased'
+    flags: 'i'
+  - regex: 'The job was not started because recent account'
+    flags: 'i'
+error_messages:
+  - "The job was not started because recent account payments have failed or your spending limit needs to be increased."
+root_cause: |
+  GitHub Actions computes minutes and storage usage against the account or organization's
+  spending limit. When either of the following conditions is true, queued jobs are never
+  assigned a runner and remain stuck indefinitely:
+
+  1. **Billing failure** — the payment method on file was declined or has expired. GitHub
+     cannot charge for overages and blocks new job starts as a safeguard.
+
+  2. **Spending limit reached** — the account spending limit for Actions minutes (or
+     artifact/package storage) has been hit. The default spending limit for paid plans is
+     $0 of overage; once included minutes are exhausted, jobs are blocked unless the limit
+     is raised.
+
+  The error message appears in the workflow run summary and the job queue-wait log — NOT in
+  step output, because no step ever runs. Jobs remain at "Queued" and eventually time out
+  (typically 6 hours) with this message.
+
+  Common triggers:
+  - End of billing cycle — included minutes exhausted, spending limit at $0
+  - Payment method expired (credit card expiry, bank decline, insufficient funds)
+  - Free plan runner-minutes exhausted mid-month with no spending limit override
+  - Organization suspended or billing contact unreachable
+fix: |
+  **For payment failure:**
+  1. Navigate to Settings → Billing and plans → Payment information
+  2. Update or replace the payment method
+  3. Re-run failed workflow jobs after billing resolves
+
+  **For spending limit exhaustion:**
+  1. Navigate to Settings → Billing and plans → Spending limits
+  2. Set a non-zero spending limit for Actions (or increase the existing limit)
+  3. Alternatively, migrate expensive workloads to self-hosted runners to eliminate
+     billed minute consumption
+
+  **Check current usage:**
+  - Settings → Billing and plans → View usage this month → Actions
+fix_code:
+  - language: yaml
+    label: "Route expensive jobs to self-hosted runner to avoid billed minutes"
+    code: |
+      jobs:
+        build:
+          # Self-hosted runners consume $0 of GitHub-hosted Actions minutes
+          runs-on: self-hosted
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm run build
+  - language: yaml
+    label: "Reduce billed minutes with cancel-in-progress concurrency"
+    code: |
+      # Cancel stale runs on new push — saves minutes on abandoned branches
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+prevention:
+  - "Set a non-zero spending limit or configure spending alerts in Settings → Billing to receive email warnings before jobs are blocked"
+  - "Monitor Actions usage in Settings → Billing and plans → Usage this month on a regular cadence"
+  - "Use `cancel-in-progress: true` concurrency groups to cancel stale workflow runs automatically and reduce minute consumption"
+  - "For high-parallelism CI, use self-hosted runners or larger runner credits (Teams/Enterprise) to avoid mid-month exhaustion"
+docs:
+  - url: "https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-actions/about-billing-for-github-actions"
+    label: "About billing for GitHub Actions"
+  - url: "https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-actions/managing-your-spending-limit-for-github-actions"
+    label: "Managing your spending limit for GitHub Actions"
+  - url: "https://github.com/orgs/community/discussions/151956"
+    label: "GitHub Community Discussion #151956 — jobs not starting due to spending limit"

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

@@ -0,0 +1,93 @@
+id: runner-environment-199
+title: 'Windows self-hosted runner V2 broker listener stops polling after first job (2.334.0)'
+category: runner-environment
+severity: error
+tags:
+  - self-hosted
+  - windows
+  - runner-v2
+  - broker
+  - listener
+  - stuck
+  - message-queue
+  - v2-flow
+patterns:
+  - regex: 'Get messages has been cancelled using local token source\. Continue to get messages with new status'
+    flags: 'i'
+  - regex: 'BrokerMessageListener.*cancel|cancel.*BrokerMessageListener'
+    flags: 'i'
+error_messages:
+  - 'Get messages has been cancelled using local token source. Continue to get messages with new status.'
+root_cause: |
+  On Windows self-hosted runners running v2.334.0 with the V2 broker flow enabled
+  (`useV2Flow: true`, connecting to `broker.actions.githubusercontent.com`), the
+  `BrokerMessageListener` stops issuing GET /message requests after the first job
+  completes and the runner transitions from Busy→Online (idle).
+
+  The root cause is a race condition in the V2 state machine reset path: when the
+  Busy→Online transition fires, the existing `localTokenSource` for the polling loop
+  is cancelled (logging "Get messages has been cancelled using local token source.
+  Continue to get messages with new status."), but the replacement polling loop fails
+  to start due to a missing null-check or async continuation bug on Windows. OAuth
+  token refreshes continue normally (masking the hang — credentials are not the issue),
+  but no new GET /message requests are dispatched.
+
+  The runner UI shows the runner as "Idle" indefinitely. Any jobs queued after the
+  first run sit in "Queued" status and never start until the runner service is manually
+  restarted. The issue is specific to Windows (the identical code path on Linux/macOS
+  appears unaffected) and requires a service start + exactly one job completion to
+  trigger. Reproduced reliably across multiple self-hosted Windows environments.
+
+  Reported against runner v2.334.0, commit f1995ede5d885c997d13d8eca5467c4ce97fe69c.
+  No fix available as of June 2026. Open at actions/runner#4444.
+fix: |
+  Immediate workaround: restart the runner service after each job, or add an automated
+  watchdog that monitors the runner diagnostics log for the stale-listener pattern and
+  triggers a service restart.
+
+  Longer-term: downgrade to runner v2.333.x until actions/runner#4444 is resolved.
+  Check the runner release notes for a fix targeting the V2 BrokerMessageListener
+  state-reset path.
+fix_code:
+  - language: yaml
+    label: 'PowerShell watchdog snippet to restart runner service on listener hang (add to a monitoring script)'
+    code: |
+      # Watchdog: detect stale BrokerMessageListener and restart runner service
+      # Run this as a scheduled task every 5 minutes on the runner host
+
+      $diagDir = "C:\actions-runner\_diag"
+      $logFile = Get-ChildItem $diagDir -Filter "Runner_*.log" | Sort-Object LastWriteTime -Descending | Select-Object -First 1
+      $lastMsg = (Get-Content $logFile.FullName -Tail 200 | Select-String "BrokerMessageListener") | Select-Object -Last 1
+
+      # If the last BrokerMessageListener log entry is the cancellation message
+      # and it's more than 10 minutes old, restart the service
+      if ($lastMsg -match "cancelled using local token source") {
+        $entryTime = [datetime]::Parse(($lastMsg -split " ")[0])
+        if ((Get-Date) - $entryTime -gt [TimeSpan]::FromMinutes(10)) {
+          Restart-Service actions.runner.*
+        }
+      }
+  - language: yaml
+    label: 'Pin runner version to 2.333.x in ARC or self-hosted runner config'
+    code: |
+      # For ARC (Actions Runner Controller) — pin runner version in values.yaml
+      githubConfigSecret: pre-defined-secret
+      template:
+        spec:
+          containers:
+            - name: runner
+              env:
+                - name: RUNNER_VERSION
+                  value: "2.333.0"    # Pin below 2.334.0 until #4444 is fixed
+prevention:
+  - "Subscribe to the actions/runner release feed to catch regression fixes; downgrade immediately when a V2-flow listener regression is reported."
+  - "For Windows runner pools, add a service watchdog (Task Scheduler or Prometheus alert) that detects listener staleness via the _diag/Runner_*.log pattern."
+  - "Consider switching to ephemeral JIT runners on Windows — ephemeral runners cannot hit this bug because each runner handles exactly one job then exits."
+  - "Monitor runner queue depth in your autoscaler; an idle runner with > 0 queued jobs is a reliable signal the listener has stalled."
+docs:
+  - url: 'https://github.com/actions/runner/issues/4444'
+    label: 'actions/runner#4444 — Listener stops polling broker after first job (2.334.0, Windows, V2 flow)'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners'
+    label: 'About self-hosted runners'
+  - url: 'https://github.com/actions/runner/releases'
+    label: 'Actions Runner release notes'

package/errors/runner-environment/setup-python-macos-self-hosted-symlink-permission-denied.yml

@@ -0,0 +1,94 @@
+id: runner-environment-198
+title: 'setup-python fails on macOS self-hosted runner with "ln: python3XX: Permission denied" — symlink created without sudo after sudo install'
+category: runner-environment
+severity: error
+tags:
+  - setup-python
+  - self-hosted
+  - macos
+  - symlink
+  - permissions
+  - sudo
+patterns:
+  - regex: 'ln:.*python3\d+.*Permission denied'
+    flags: 'i'
+  - regex: 'Error:.*ln:.*python.*Permission denied'
+    flags: 'i'
+error_messages:
+  - 'Error: ln: python314: Permission denied'
+  - 'Error: ln: python312: Permission denied'
+  - 'Error: ln: python313: Permission denied'
+root_cause: |
+  The setup-python macOS installer script (setup.sh) uses sudo to install the Python
+  framework into /Library/Frameworks/ — a root-owned directory. However, the
+  subsequent step that creates symlinks inside that directory (e.g., linking
+  python3.14 → python3) runs WITHOUT sudo, causing a permission error when the
+  runner''s CI user is a standard (non-root) account even if sudo is available for
+  the install step.
+
+  The error appears as:
+    Error: ln: python314: Permission denied
+
+  This affects macOS self-hosted runners (EC2, bare-metal, VM) where the runner
+  service is configured as a non-admin user. GitHub-hosted macOS runners are
+  unaffected because they grant passwordless sudo to the runner user.
+
+  A fix was proposed in actions/python-versions PR #384 to use sudo for the symlink
+  creation step as well, but is not yet merged/released as of mid-2026.
+fix: |
+  Short-term workaround: Grant the runner service user passwordless sudo on the
+  macOS runner machine, or run the runner as a user with write access to
+  /Library/Frameworks/ and /usr/local/bin.
+
+  Safer workaround: Pre-install Python on the macOS runner machine using the
+  official Python.org pkg installer (which creates symlinks correctly as root), then
+  rely on setup-python''s PATH-detection to use the pre-installed version without
+  invoking the installer.
+
+  Enterprise workaround: Use a custom RUNNER_TOOL_CACHE path that is owned by the
+  runner user and set python-version to a version already cached there, bypassing
+  the framework installer entirely.
+fix_code:
+  - language: yaml
+    label: 'Workaround: use pre-installed Python to avoid the installer'
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, macos]
+          steps:
+            # If Python 3.14 is pre-installed system-wide (via pkg installer as root),
+            # setup-python finds it in PATH without invoking setup.sh
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.14'
+            - run: python3 --version
+  - language: yaml
+    label: 'Workaround: grant passwordless sudo to runner user via /etc/sudoers (NOT recommended for production)'
+    code: |
+      # Add to /etc/sudoers on the macOS runner machine (use visudo):
+      # runner-user ALL=(ALL) NOPASSWD: ALL
+      #
+      # This allows setup-python's installer to use sudo for both the framework
+      # install and symlink creation steps.
+      #
+      # In your workflow, no changes are needed — setup-python works normally once
+      # the runner user has the required sudo permissions.
+      jobs:
+        build:
+          runs-on: [self-hosted, macos]
+          steps:
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.14'
+prevention:
+  - 'Use pre-installed Python on macOS self-hosted runners to avoid the setup.sh installer and its sudo/symlink requirements'
+  - 'When provisioning macOS self-hosted runners, ensure the runner user has passwordless sudo or pre-install all required Python versions'
+  - 'Track actions/python-versions#384 for an upstream fix that adds sudo to the symlink creation step'
+  - 'Test setup-python on macOS self-hosted runners in a staging environment before deploying to production'
+docs:
+  - url: 'https://github.com/actions/setup-python/issues/1301'
+    label: 'actions/setup-python#1301: Permission denied when creating symlinks on macOS self-hosted runners (2026)'
+  - url: 'https://github.com/actions/python-versions/pull/384'
+    label: 'actions/python-versions PR #384: fix symlink creation to use sudo (pending)'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security'
+    label: 'GitHub Docs: Self-hosted runner security'

package/errors/runner-environment/setup-python-windows-self-hosted-no-admin-install-fails.yml

@@ -0,0 +1,101 @@
+id: runner-environment-197
+title: 'setup-python fails on Windows self-hosted runner without administrator permissions — InstallAllUsers=1 MSI installer requires admin'
+category: runner-environment
+severity: error
+tags:
+  - setup-python
+  - self-hosted
+  - windows
+  - admin-permissions
+  - msi-installer
+patterns:
+  - regex: 'Error happened during Python installation'
+    flags: 'i'
+  - regex: 'InstallAllUsers=1'
+    flags: 'i'
+  - regex: 'setup-python.*self.hosted.*windows.*fail'
+    flags: 'i'
+error_messages:
+  - 'Error happened during Python installation'
+root_cause: |
+  The setup-python action installs Python using the official MSI installer with the
+  flag InstallAllUsers=1. This flag installs Python into the shared runner tool cache
+  (RUNNER_TOOL_CACHE) using the DefaultAllUsersTargetDir argument, which requires
+  administrator privileges to write to the shared system-level installation path.
+
+  When the GitHub Actions runner service is running under a standard user account
+  without local administrator permissions, the Python MSI installer fails because it
+  cannot write to the required system paths, resulting in:
+
+    Error happened during Python installation
+
+  This affects Windows self-hosted runners configured as a Windows service under a
+  non-admin account. GitHub-hosted Windows runners are unaffected because they run
+  as SYSTEM (full admin). Linux and macOS self-hosted runners are unaffected.
+
+  Note: this is by design per the action maintainers — InstallAllUsers=1 is required
+  to correctly populate the shared RUNNER_TOOL_CACHE. A per-user install mode
+  (InstallAllUsers=0) is under consideration as a future enhancement.
+fix: |
+  Primary fix: Configure the Windows runner service to run as a local administrator
+  account. In Windows Services (services.msc), change the "Log On" account for the
+  GitHub Actions Runner service to an account with local admin rights, or install the
+  runner using the .\config.cmd --runasservice flow with an admin account.
+
+  Workaround 1: Pre-install the required Python version system-wide on the runner
+  machine before workflows run. setup-python will use the pre-installed version from
+  PATH without invoking the MSI installer if the version matches.
+
+  Workaround 2: Ensure the runner is run interactively (not as a service) under an
+  account with admin rights during initial Python installation, then cache the tool.
+
+  Workaround 3: Use actions/setup-python''s uses: together with a self-hosted runner
+  image that already has Python pre-installed in RUNNER_TOOL_CACHE, bypassing the
+  MSI install step entirely.
+fix_code:
+  - language: yaml
+    label: 'Workflow: no changes needed — fix is on the runner machine configuration'
+    code: |
+      # Fix requires reconfiguring the Windows runner service account:
+      # 1. Open Services (services.msc) on the runner machine
+      # 2. Find "GitHub Actions Runner (<name>)"
+      # 3. Right-click → Properties → Log On tab
+      # 4. Change to an account with local administrator privileges
+      # 5. Restart the service
+      #
+      # After reconfiguring, setup-python works normally:
+      jobs:
+        build:
+          runs-on: [self-hosted, windows]
+          steps:
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.12'
+            - run: python --version
+  - language: yaml
+    label: 'Workaround: use pre-installed Python from PATH if runner has it installed system-wide'
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, windows]
+          steps:
+            # Skip setup-python entirely if Python is pre-installed system-wide
+            - name: Verify Python available
+              run: python --version
+            # OR use setup-python only to add to PATH, not install:
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.12'
+                # If Python 3.12 is already in RUNNER_TOOL_CACHE, no install occurs
+prevention:
+  - 'Always run Windows self-hosted runner services under a local administrator account — setup-python requires admin rights to install into the shared tool cache'
+  - 'Test setup-python on self-hosted runners with the same service account before deploying to production workloads'
+  - 'Use pre-installed Python on Windows self-hosted runners to avoid the MSI installer entirely when admin rights cannot be granted'
+  - 'Document the runner service account requirements in your team''s self-hosted runner setup guide'
+docs:
+  - url: 'https://github.com/actions/setup-python/issues/1308'
+    label: 'actions/setup-python#1308: fails on self-hosted runners without admin permissions (2026)'
+  - url: 'https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md#windows'
+    label: 'setup-python docs: Windows advanced usage and self-hosted runner configuration'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/configuring-the-self-hosted-runner-application-as-a-service'
+    label: 'GitHub Docs: Configuring the self-hosted runner as a service'

package/errors/silent-failures/checkout-v6-clean-false-deletes-workspace-on-repo-change.yml

@@ -0,0 +1,119 @@
+id: silent-failures-105
+title: 'checkout@v6 clean: false still deletes workspace when remote URL changes between checkouts'
+category: silent-failures
+severity: silent-failure
+tags:
+  - checkout
+  - clean
+  - workspace
+  - multi-checkout
+  - v6
+  - remote-url
+patterns:
+  - regex: 'Deleting the contents of.*work.*\n.*Initializing the repository'
+    flags: 'i'
+  - regex: 'clean:\s*false[\s\S]{0,500}Deleting the contents of'
+    flags: 'i'
+  - regex: 'git config --local --get remote\.origin\.url[\s\S]{0,200}Deleting the contents'
+    flags: 'i'
+error_messages:
+  - 'Deleting the contents of ''/home/runner/work/myrepo/myrepo'''
+  - 'Deleting the contents of ''/home/runner/work/_temp/...'
+root_cause: |
+  actions/checkout's `clean: false` option prevents `git clean -ffdx` (removing untracked
+  files) but does NOT prevent the action from deleting and reinitializing the entire
+  workspace directory when it detects that the existing `remote.origin.url` does not match
+  the target repository being checked out.
+
+  When multiple checkout steps run in the same job and the second checkout targets a
+  different repository (different org, different repo name, or different URL), the action
+  reads the current `git config --local --get remote.origin.url`, compares it against the
+  target repository URL, and — on mismatch — deletes the entire workspace directory before
+  reinitializing. This deletion happens regardless of `clean: false`.
+
+  Common scenarios that trigger this:
+  1. First step checks out a support/config repo (sparse-checkout of a different repo for
+     shared config), then a second step checks out the main repo with `clean: false`.
+  2. Checking out the main repo first, then a second checkout of a different repo for
+     reading shared scripts, assuming `clean: false` preserves the main workspace.
+  3. Re-using runner workspace across jobs via `clean: false` where the prior job checked
+     out a different repository.
+
+  The log shows the silent deletion in plain text ("Deleting the contents of '...'") but
+  users commonly miss it because the step still succeeds and subsequent steps may not
+  immediately error if they only use the freshly-checked-out content.
+
+  checkout@v5 has the same behavior — this is not a v6 regression. It is documented as
+  expected behavior but is frequently unexpected by users.
+fix: |
+  Option 1 (recommended): Specify `path:` to checkout each repository into a distinct
+  subdirectory, preventing the remote URL mismatch from triggering deletion.
+
+  Option 2: Reverse the order — checkout the main repo last so the deletion (if any)
+  happens to the support repo's files rather than the main workspace.
+
+  Option 3: Accept that `clean: false` cannot preserve workspace contents across
+  checkouts of different repositories sharing the same path, and restructure the workflow
+  to avoid this pattern.
+
+  Option 4: For reading shared scripts/config from another repo, use curl/gh api to fetch
+  specific files rather than a full checkout step.
+fix_code:
+  - language: yaml
+    label: 'Use path: to isolate each checkout to its own directory'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            # Checkout support config into a subdirectory
+            - name: Checkout shared config
+              uses: actions/checkout@v6
+              with:
+                repository: myorg/shared-config
+                ref: v1
+                sparse-checkout: |
+                  nginx/nginx.conf
+                path: .shared-config   # <-- isolated path, no URL conflict
+
+            # Checkout main repo into workspace root (or another path)
+            - name: Checkout source
+              uses: actions/checkout@v6
+              with:
+                fetch-depth: 0
+                # clean: false is now safe — different paths, no URL mismatch
+
+            - name: Use shared config
+              run: cp .shared-config/nginx/nginx.conf ./nginx.conf
+
+  - language: yaml
+    label: 'Fetch individual files without a full checkout to avoid URL conflict'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v6
+              with:
+                fetch-depth: 0
+
+            # Fetch a single file from another repo without a second checkout
+            - name: Fetch shared nginx config
+              env:
+                GH_TOKEN: ${{ github.token }}
+              run: |
+                gh api repos/myorg/shared-config/contents/nginx/nginx.conf \
+                  --jq '.content' | base64 -d > ./nginx.conf
+
+prevention:
+  - 'Use path: on every checkout step when multiple repositories are checked out in the same job'
+  - 'Do not rely on clean: false to preserve workspace content across checkouts of different repositories'
+  - 'Watch for "Deleting the contents of..." lines in checkout step logs — this confirms workspace was reset even with clean: false'
+  - 'When using sparse-checkout for a support repo followed by a main repo checkout, always isolate them into separate path: directories'
+docs:
+  - url: 'https://github.com/actions/checkout/issues/2348'
+    label: 'actions/checkout#2348 — v6 clean: false still deletes workspace files from prior checkout (Feb 2026)'
+  - url: 'https://github.com/actions/checkout#usage'
+    label: 'actions/checkout — clean input documentation'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-workflow-data-as-artifacts'
+    label: 'Storing workflow data — alternative to multi-repo checkout for sharing files'

package/errors/silent-failures/queue-max-silently-ignored-with-cancel-in-progress.yml

@@ -0,0 +1,109 @@
+id: silent-failures-103
+title: "concurrency queue: max silently ignored when cancel-in-progress: true is also set"
+category: silent-failures
+severity: silent-failure
+tags:
+  - concurrency
+  - queue
+  - cancel-in-progress
+  - silent-failure
+  - deployment
+  - serialization
+patterns:
+  - regex: 'This run has been cancelled'
+    flags: 'i'
+  - regex: 'Canceling since a higher priority waiting run was found'
+    flags: 'i'
+  - regex: 'queue:\s*max'
+    flags: 'i'
+error_messages:
+  - "This run has been cancelled."
+  - "Canceling since a higher priority waiting run was found"
+root_cause: |
+  GitHub Actions introduced `queue: max` in May 2026 as a way to allow up to 100
+  pending runs to wait in a concurrency group instead of being cancelled and
+  replaced. Adding `queue: max` to an existing concurrency block without removing
+  `cancel-in-progress: true` results in the `queue: max` setting being silently
+  ignored — no validation error is raised, no warning is emitted.
+
+  The concurrency group continues to cancel pending runs exactly as it did before.
+  The developer believes their deployment queue is now buffering up to 100 runs,
+  but every third commit or concurrent PR merge still cancels the previously queued
+  run, dropping deployments silently.
+
+  The language services editor plugin (VS Code Actions extension) does report a
+  lint error for this combination, but:
+    - Not all teams have the extension installed or enabled.
+    - The Actions UI and `gh` CLI do not surface the conflict at run time.
+    - The workflow file passes schema validation and runs without a reported error.
+
+  The practical symptom is identical to having no `queue: max` at all: runs are
+  still cancelled, the queue never grows beyond one pending run, and deployments
+  are dropped during high-frequency push periods — exactly the problem `queue: max`
+  was supposed to solve.
+fix: |
+  Remove `cancel-in-progress: true` (or omit it entirely, since `false` is the
+  default) when using `queue: max`. These two options are mutually exclusive:
+
+  - `cancel-in-progress: true` — cancel the pending run when a newer run arrives.
+  - `queue: max` — hold up to 100 pending runs in order.
+
+  If you need both semantics (cancel old pending runs for feature branches but queue
+  for main), split into separate concurrency group expressions per ref:
+
+    ```yaml
+    concurrency:
+      group: deploy-${{ github.ref }}
+      cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+      # Do NOT add queue: max when cancel-in-progress may be true
+    ```
+
+  For the main branch where ordered deploys matter, use `queue: max` alone:
+
+    ```yaml
+    concurrency:
+      group: deploy-production
+      queue: max
+      # cancel-in-progress must be omitted or set to false
+    ```
+fix_code:
+  - language: yaml
+    label: "WRONG — queue: max silently ignored when cancel-in-progress: true"
+    code: |
+      concurrency:
+        group: deploy-${{ github.repository }}-${{ github.ref }}
+        cancel-in-progress: true   # ← PROBLEM: negates queue: max
+        queue: max                 # ← silently ignored, no error shown
+  - language: yaml
+    label: "CORRECT — use queue: max without cancel-in-progress"
+    code: |
+      concurrency:
+        group: deploy-${{ github.repository }}-${{ github.ref }}
+        queue: max                  # ← up to 100 pending runs queued
+        # cancel-in-progress is false by default — omit it entirely
+  - language: yaml
+    label: "ADVANCED — cancel-in-progress for branches, queue for main"
+    code: |
+      concurrency:
+        group: deploy-${{ github.repository }}-${{ github.ref }}
+        # Dynamic cancel: cancel feature branch runs (fast feedback), queue
+        # main branch deploys (preserve ordering).
+        cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+        # Note: queue: max cannot be combined with cancel-in-progress.
+        # For main branch serialization without cancel, omit cancel-in-progress
+        # and rely on queue: max in a separate workflow targeting only main.
+prevention:
+  - "When adding `queue: max` to an existing concurrency block, always audit the
+    block for a `cancel-in-progress: true` setting and remove it."
+  - "Install the GitHub Actions VS Code extension — it reports a lint error for
+    `queue: max` + `cancel-in-progress: true` combinations before you push."
+  - "After enabling `queue: max`, verify it works by triggering two rapid pushes
+    and confirming both runs appear in the Actions UI as 'Queued' rather than one
+    being cancelled."
+docs:
+  - url: "https://github.blog/changelog/2026-05-07-github-actions-concurrency-groups-now-allow-larger-queues/"
+    label: "GitHub Changelog: GitHub Actions concurrency groups now allow larger queues (May 7, 2026)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-concurrency"
+    label: "Using concurrency — GitHub Actions documentation"
+  - url: "https://github.com/actions/languageservices/pull/355"
+    label: "actions/languageservices#355: Add queue property to concurrency, validate queue+cancel-in-progress conflict"