@htekdev/actions-debugger 1.0.113 → 1.0.114

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

@@ -0,0 +1,144 @@
+id: runner-environment-192
+title: 'ubuntu-24.04 Kernel 6.17.0-1015-azure Oops in ublk_drv — User Block Device Workflows Hang'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - kernel
+  - ublk
+  - io-uring
+  - runner-image
+  - regression
+patterns:
+  - regex: 'ublk_init_queues.*Oops|RIP.*ublk_init_queues'
+    flags: 'i'
+  - regex: 'ublk_ctrl_add_dev|UBLK_U_CMD_ADD_DEV.*hang|ublk_drv.*kernel.*oops'
+    flags: 'i'
+  - regex: 'note: iou-wrk-.*exited with irqs disabled'
+    flags: 'i'
+  - regex: 'modprobe ublk_drv.*ublk.*add.*dev.*timeout|ublk.*command.*never completes'
+    flags: 'i'
+error_messages:
+  - 'RIP: 0010:ublk_init_queues+0x4e/0x1e0 [ublk_drv]'
+  - 'note: iou-wrk-* exited with irqs disabled'
+  - 'ublk_ctrl_add_dev+0x31a/0x5e0 [ublk_drv]'
+  - 'Oops: general protection fault, probably for non-canonical address'
+root_cause: |
+  The ubuntu-24.04 runner image released 2026-05-26 (version 20260525.161.1) ships
+  Linux kernel 6.17.0-1015-azure (upgraded from 6.17.0-1013-azure). This kernel
+  contains an upstream bug in the `ublk_drv` module: calling `UBLK_U_CMD_ADD_DEV`
+  once via io_uring triggers a kernel Oops in `ublk_init_queues+0x4e/0x1e0`.
+
+  **Affected call chain:**
+  ```
+  ublk_init_queues
+  ublk_ctrl_add_dev
+  ublk_ctrl_uring_cmd
+  io_uring_cmd
+  io_wq_submit_work
+  io_wq_worker
+  ```
+
+  After the Oops, the ADD_DEV io_uring command never receives a completion event
+  (CQE), so the userspace program waits indefinitely. The GitHub Actions job hangs
+  until it hits the workflow timeout.
+
+  **Affected environments:**
+  - ubuntu-24.04 amd64 hosted runners with kernel 6.17.0-1015-azure
+  - Any workflow that calls `modprobe ublk_drv` and then performs `UBLK_U_CMD_ADD_DEV`
+
+  **Unaffected environments:**
+  - ubuntu-22.04 runners (kernel 6.8.0-1052-azure — not affected)
+  - ubuntu-24.04 self-hosted runners still on kernel 6.17.0-1013-azure or earlier
+
+  This is an upstream `linux-azure` kernel bug (not a runner-images regression).
+  GitHub does not pin the kernel — it is delivered from Canonical's HWE channel.
+  A kernel SRU fix from Canonical will be picked up automatically in future
+  ubuntu-24.04 runner image releases.
+fix: |
+  **Workaround: pin ublk-based jobs to ubuntu-22.04 until the kernel SRU is deployed.**
+
+  ```yaml
+  ublk-test:
+    runs-on: ubuntu-22.04   # kernel 6.8.0 — ublk_drv works correctly
+    steps:
+      - uses: actions/checkout@v6
+      - run: |
+          sudo modprobe ublk_drv || {
+            sudo apt-get install -y --no-install-recommends \
+              "linux-modules-extra-$(uname -r)"
+            sudo modprobe ublk_drv
+          }
+          # your ublk test here
+  ```
+
+  **Alternative: install `linux-modules-extra` and test kernel version at runtime:**
+
+  ```bash
+  KERNEL=$(uname -r)
+  if [[ "$KERNEL" == "6.17.0-1015-azure" ]]; then
+    echo "::warning::Kernel 6.17.0-1015-azure has a ublk_drv bug. Skipping ublk tests."
+    exit 0
+  fi
+  ```
+
+  Track the upstream kernel SRU at Canonical:
+  https://bugs.launchpad.net/ubuntu/+source/linux-azure/
+fix_code:
+  - language: yaml
+    label: 'Pin ublk-dependent jobs to ubuntu-22.04 as workaround'
+    code: |
+      jobs:
+        ublk-integration:
+          # Workaround: ubuntu-24.04 kernel 6.17.0-1015-azure has a ublk_drv bug.
+          # Pin to ubuntu-22.04 until a fixed kernel SRU lands in ubuntu-24.04.
+          runs-on: ubuntu-22.04
+          steps:
+            - uses: actions/checkout@v6
+            - name: Load ublk_drv
+              run: |
+                sudo modprobe ublk_drv || {
+                  sudo apt-get update -qq
+                  sudo apt-get install -y --no-install-recommends \
+                    "linux-modules-extra-$(uname -r)"
+                  sudo modprobe ublk_drv
+                }
+            - name: Run ublk tests
+              run: make test-ublk
+
+  - language: yaml
+    label: 'Matrix with runtime kernel guard to skip known-broken kernel'
+    code: |
+      jobs:
+        ublk-test:
+          strategy:
+            matrix:
+              runner: [ubuntu-22.04, ubuntu-24.04]
+          runs-on: ${{ matrix.runner }}
+          steps:
+            - uses: actions/checkout@v6
+            - name: Check kernel for ublk_drv bug
+              run: |
+                KERNEL=$(uname -r)
+                echo "Kernel: $KERNEL"
+                if [[ "$KERNEL" == "6.17.0-1015-azure" ]]; then
+                  echo "::warning::Skipping ublk tests on $KERNEL (known ublk_drv Oops)"
+                  echo "SKIP_UBLK=true" >> "$GITHUB_ENV"
+                fi
+            - name: Run ublk tests
+              if: env.SKIP_UBLK != 'true'
+              run: make test-ublk
+prevention:
+  - 'Monitor ubuntu-24.04 kernel version in release notes before running ublk/io_uring block device tests.'
+  - 'Add a kernel version gate in ublk-dependent CI steps to skip on known-bad kernels.'
+  - 'Subscribe to or monitor `actions/runner-images` issues for kernel regression reports on Ubuntu runners.'
+  - 'Consider pinning ublk integration tests to ubuntu-22.04 as a long-term stable baseline for kernel-intensive work.'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/14175'
+    label: 'runner-images #14175 — ubuntu-24.04 kernel 6.17.0-1015-azure Oops in ublk_drv (open)'
+  - url: 'https://github.com/e2b-dev/ublk-adddev-repro'
+    label: 'Minimal ublk UBLK_U_CMD_ADD_DEV repro repo'
+  - url: 'https://github.com/actions/runner-images/releases/tag/ubuntu24%2F20260525.161'
+    label: 'Ubuntu 24.04 runner image 20260525.161.1 — kernel 6.17.0-1015-azure'
+  - url: 'https://bugs.launchpad.net/ubuntu/+source/linux-azure/'
+    label: 'Canonical linux-azure bug tracker (for SRU status)'

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

@@ -0,0 +1,136 @@
+id: runner-environment-193
+title: 'ubuntu-24.04-arm64 GitHub-Managed Image Ships Ruby 3.2.3 vs x64 Ruby 4.0 — Matrix Builds Fail'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - arm64
+  - ruby
+  - matrix
+  - runner-image
+  - version-mismatch
+patterns:
+  - regex: 'Your Ruby version is 3\.2\.[0-9], but your Gemfile specified.*[~>].*4\.'
+    flags: 'i'
+  - regex: 'bundler.*RUBY_VERSION.*3\.2.*expected.*4\.|incompatible.*ruby.*3\.2.*4\.'
+    flags: 'i'
+  - regex: 'LoadError.*incompatible library version.*ruby.*3\.2|\.bundle.*built for Ruby 3\.2.*running.*4\.'
+    flags: 'i'
+  - regex: 'ubuntu-24\.04-arm.*ruby.*3\.2|arm64.*ruby.*version.*mismatch'
+    flags: 'i'
+error_messages:
+  - 'Your Ruby version is 3.2.3, but your Gemfile specified ~> 4.0'
+  - 'LoadError: incompatible library version - /path/to/native.bundle'
+  - "An error occurred while installing nokogiri (1.x.x), and Bundler cannot continue."
+  - 'Gem::RuntimeRequirementNotMetError: ruby 4.0 is required'
+root_cause: |
+  The first GitHub-managed Ubuntu 24.04 ARM64 runner image (ubuntu24-arm64/
+  20260531.15.1, released 2026-06-03) ships Ruby 3.2.3 as the default system Ruby.
+  In contrast, the Ubuntu 24.04 x86-64 runner image (ubuntu24/20260525.161.1) ships
+  Ruby 4.0.5. This version gap was introduced when GitHub took over ARM64 image
+  maintenance from Arm Limited in May–June 2026; the ARM64 image was rebuilt with a
+  different baseline software set.
+
+  **Affected workflows — any that run a Ruby matrix over both platforms:**
+  ```yaml
+  strategy:
+    matrix:
+      os: [ubuntu-24.04, ubuntu-24.04-arm]
+  ```
+
+  Failure modes:
+  1. **Gemfile Ruby version constraint** — if the Gemfile (or `.ruby-version`) pins
+     `ruby ~> 4.0` (or uses Ruby 4.0 syntax features), the ARM64 run fails immediately
+     with "Your Ruby version is 3.2.3, but your Gemfile specified ~> 4.0".
+
+  2. **Native extension ABI mismatch** — if the workflow restores a gem cache built
+     on the x64 runner (Ruby 4.0 ABI), native extension `.bundle` files are
+     incompatible with Ruby 3.2 on ARM64, producing a `LoadError` at test time.
+
+  3. **Ruby 4.0 language/stdlib differences** — Ruby 4.0 removed several deprecated
+     methods that exist in Ruby 3.2 (e.g., Kernel#binding). Code that uses 4.0-only
+     APIs silently succeeds on x64 but may have unexpected behaviour differences on
+     ARM64.
+
+  4. **setup-ruby without an explicit ruby-version** — if no version is pinned, the
+     action resolves "system ruby" differently per platform, producing Ruby 3.2 on
+     ARM64 and Ruby 4.0 on x64.
+
+  Ubuntu ARM64 runners maintained by Arm Limited previously matched x64 Ruby
+  versions more closely. The GitHub-managed ARM64 baseline is younger and will
+  converge with x64 over subsequent image releases.
+fix: |
+  **Explicit Ruby version with ruby/setup-ruby** on all platforms to override the
+  system Ruby and get a consistent version:
+
+  ```yaml
+  - uses: ruby/setup-ruby@v1
+    with:
+      ruby-version: '3.3'   # or whatever version your project supports on both arches
+      bundler-cache: true
+  ```
+
+  **Separate cache keys per OS/arch** to avoid cross-ABI gem cache poisoning:
+
+  ```yaml
+  - uses: actions/cache@v4
+    with:
+      path: vendor/bundle
+      key: ${{ runner.os }}-${{ runner.arch }}-ruby-${{ hashFiles('Gemfile.lock') }}
+  ```
+
+  **Guard Gemfile ruby version** to accept both 3.x and 4.x on the arm64 matrix:
+
+  ```ruby
+  # Gemfile
+  ruby '>= 3.2'   # instead of ~> 4.0, to allow both ubuntu-24.04 and ubuntu-24.04-arm
+  ```
+fix_code:
+  - language: yaml
+    label: 'Pin Ruby version with setup-ruby across all matrix platforms'
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              os: [ubuntu-24.04, ubuntu-24.04-arm]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v6
+
+            # Explicitly pin Ruby to get the same version on x64 AND ARM64.
+            # Without this, x64 gets Ruby 4.0.x and ARM64 gets Ruby 3.2.x.
+            - uses: ruby/setup-ruby@v1
+              with:
+                ruby-version: '3.3'    # consistent across both architectures
+                bundler-cache: true
+
+            - run: bundle exec rspec
+
+  - language: yaml
+    label: 'Per-arch gem cache key to prevent ABI mismatch on cache restore'
+    code: |
+      - name: Cache gems
+        uses: actions/cache@v4
+        with:
+          path: vendor/bundle
+          # Include runner.arch so ARM64 and x64 don't share native extension builds
+          key: >-
+            ${{ runner.os }}-${{ runner.arch }}-gems-
+            ${{ hashFiles('Gemfile.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-${{ runner.arch }}-gems-
+prevention:
+  - 'Always use `ruby/setup-ruby` with an explicit `ruby-version` in cross-arch matrix jobs — never rely on the system Ruby.'
+  - 'Include `runner.arch` in gem cache keys to prevent native extension ABI mismatches between x64 and ARM64 runs.'
+  - 'Set Gemfile Ruby version constraint to `>= 3.2` instead of `~> 4.0` when the matrix includes ubuntu-24.04-arm.'
+  - 'Check the ubuntu24-arm64 runner release notes for software version differences vs ubuntu-24.04 x64 before adding ARM64 to your CI matrix.'
+docs:
+  - url: 'https://github.com/actions/runner-images/releases/tag/ubuntu24-arm64%2F20260531.15'
+    label: 'ubuntu24-arm64/20260531.15 — first GitHub-managed ARM64 image (Ruby 3.2.3)'
+  - url: 'https://github.com/actions/runner-images/releases/tag/ubuntu24%2F20260525.161'
+    label: 'ubuntu24/20260525.161.1 — Ubuntu 24.04 x64 image (Ruby 4.0.5)'
+  - url: 'https://github.com/actions/runner-images/issues/14100'
+    label: 'runner-images #14100 — ARM64 runner images now maintained by GitHub'
+  - url: 'https://github.com/ruby/setup-ruby'
+    label: 'ruby/setup-ruby — install a consistent Ruby version on any runner'

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/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"