@htekdev/actions-debugger 1.0.111 → 1.0.113

package/errors/caching-artifacts/buildkit-gha-cache-legacy-api-v1-self-hosted.yml

@@ -0,0 +1,123 @@
+id: 'caching-artifacts-065'
+title: 'Docker BuildKit type=gha cache fails on self-hosted runners with BuildKit < 0.21.0 after legacy cache service v1 shutdown'
+category: 'caching-artifacts'
+severity: 'error'
+tags:
+  - docker
+  - buildkit
+  - buildx
+  - gha-cache
+  - self-hosted
+  - cache-api-v2
+  - legacy-service
+patterns:
+  - regex: 'This legacy service is shutting down'
+    flags: 'i'
+  - regex: 'failed to solve.*legacy.*service'
+    flags: 'i'
+  - regex: 'gha-cache-sunset'
+    flags: 'i'
+  - regex: 'cache.*type=gha.*legacy'
+    flags: 'i'
+error_messages:
+  - "ERROR: failed to solve: This legacy service is shutting down, effective April 15, 2025. Migrate to the new service ASAP. For more information: https://gh.io/gha-cache-sunset"
+  - "This legacy service is shutting down, effective April 15, 2025."
+  - "importing cache manifest from gha"
+  - "exporting to GitHub Actions Cache"
+root_cause: |
+  GitHub decommissioned the legacy GitHub Actions Cache service v1 API on
+  April 15, 2025. All cache operations now require the new v2 API.
+
+  Docker BuildKit uses a separate Go-based GitHub Actions cache client
+  (`tonistiigi/go-actions-cache`) — distinct from the `@actions/cache` npm
+  package used by `actions/cache`. The `go-actions-cache` library added support
+  for cache API v2 in BuildKit 0.20.0 and Buildx 0.21.0.
+
+  Self-hosted runners that have not been updated since before the migration
+  still ship Docker Engine with an older BuildKit version (< 0.20.0) or an
+  older Docker Buildx binary (< 0.21.0). When these workflows use
+  `cache-from: type=gha` or `cache-to: type=gha`, the old BuildKit communicates
+  with the now-decommissioned v1 API endpoint and receives the shutdown error:
+
+    ERROR: failed to solve: This legacy service is shutting down, effective
+    April 15, 2025. Migrate to the new service ASAP.
+
+  GitHub-hosted runners (ubuntu-latest, etc.) are automatically up to date and
+  are not affected. Only self-hosted runners or custom BuildKit setups that
+  pin an old Buildx/BuildKit version are impacted.
+
+  Note: this is distinct from `actions/cache` action failing due to stale
+  ACTIONS_CACHE_URL overrides (caching-artifacts-031), which is a different
+  failure mode involving the npm-based cache client.
+fix: |
+  Option 1 (recommended): Pin docker/setup-buildx-action to install the latest
+  Buildx on the self-hosted runner before each build. This ensures Buildx >=
+  0.21.0 is always used regardless of the runner's system Buildx version.
+
+  Option 2: Update the self-hosted runner's Docker Engine to >= 28.0.0 and
+  Buildx to >= 0.21.0 at the system level.
+
+  Option 3: Switch to registry-based cache (type=registry) if upgrading Buildx
+  is not feasible. GHCR registry cache is not subject to the API version
+  requirement and is free for public repositories.
+
+  Minimum versions required for cache API v2:
+  - Docker Buildx >= 0.21.0
+  - BuildKit >= 0.20.0
+  - Docker Compose >= 2.33.1
+  - Docker Engine >= 28.0.0 (when using containerd image store)
+fix_code:
+  - language: yaml
+    label: 'Pin setup-buildx-action to install latest Buildx on self-hosted runner'
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, linux, x64]
+          steps:
+            - uses: actions/checkout@v4
+
+            # Always install the latest Buildx — ensures >= 0.21.0 for cache API v2
+            - name: Set up Docker Buildx
+              uses: docker/setup-buildx-action@v3
+              with:
+                version: latest   # Overrides the runner's system Buildx version
+
+            - name: Build and push
+              uses: docker/build-push-action@v7
+              with:
+                push: ${{ github.ref == 'refs/heads/main' }}
+                tags: ghcr.io/${{ github.repository }}:latest
+                cache-from: type=gha
+                cache-to: type=gha,mode=max
+  - language: yaml
+    label: 'Fallback: use GHCR registry cache instead of type=gha'
+    code: |
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and push (registry cache — no API version dependency)
+        uses: docker/build-push-action@v7
+        with:
+          push: ${{ github.ref == 'refs/heads/main' }}
+          tags: ghcr.io/${{ github.repository }}:latest
+          cache-from: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache
+          cache-to: type=registry,ref=ghcr.io/${{ github.repository }}:buildcache,mode=max
+prevention:
+  - "Always add docker/setup-buildx-action with 'version: latest' before any Docker build step on self-hosted runners."
+  - "Periodically update self-hosted runner Docker Engine and Buildx to latest stable versions."
+  - "Subscribe to the GitHub Changelog (github.blog/changelog) for advance notice of cache service API changes."
+  - "Verify Buildx version in CI: add 'docker buildx version' as a diagnostic step to catch version drift early."
+  - "Consider using registry cache (type=registry) as a more portable alternative to type=gha on self-hosted runners."
+docs:
+  - url: 'https://github.com/docker/build-push-action/issues/1345'
+    label: 'docker/build-push-action#1345 — type=gha cache failure after legacy service shutdown (Apr 2025)'
+  - url: 'https://docs.docker.com/build/ci/github-actions/cache/#github-cache'
+    label: 'Docker Docs — GitHub Actions cache backend (note: legacy v1 API shut down April 15, 2025)'
+  - url: 'https://github.com/docker/setup-buildx-action'
+    label: 'docker/setup-buildx-action — Install latest Buildx on any runner'
+  - url: 'https://gh.io/gha-cache-sunset'
+    label: 'GitHub — GHA cache service v1 sunset announcement'

package/errors/concurrency-timing/merge-group-pr-number-concurrency-null-collapse.yml

@@ -0,0 +1,85 @@
+id: concurrency-timing-051
+title: 'merge_group event has no pull_request.number — PR-number-keyed concurrency group collapses all merge queue runs to the same slot'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - merge-queue
+  - merge_group
+  - pull_request
+  - cancel-in-progress
+  - null-key
+patterns:
+  - regex: 'merge_group'
+    flags: 'i'
+  - regex: 'pull_request\.number'
+    flags: 'i'
+  - regex: 'Canceling since a higher priority waiting run was found'
+    flags: 'i'
+error_messages:
+  - 'This run was automatically cancelled'
+  - 'Canceling since a higher priority waiting run was found'
+  - 'Required status checks did not pass'
+root_cause: |
+  The merge_group event payload does not include a pull_request object. When a workflow
+  uses ${{ github.event.pull_request.number }} in a concurrency group key — a common
+  pattern to scope CI runs per open PR — the expression evaluates to an empty string
+  for all merge_group-triggered runs.
+
+  All merge queue validation runs therefore share an identical concurrency group key
+  (e.g., ci- instead of ci-42). With cancel-in-progress: true, each new merge queue
+  batch immediately cancels the currently running validation for all other batches in
+  the queue. With cancel-in-progress: false, only the most-recently-queued batch runs;
+  earlier batches are ejected from the merge queue with 'Required status checks did
+  not pass'.
+
+  This silently serializes or destroys merge queue throughput and commonly occurs when
+  developers add merge_group to an existing pull_request workflow that already uses
+  PR-number-based concurrency without updating the group expression.
+fix: |
+  Use a conditional expression that resolves to a unique key for both event types.
+  For merge_group events, github.event.merge_group.head_sha provides a value that is
+  unique per merge queue batch:
+
+    group: ci-${{ github.event.pull_request.number || github.event.merge_group.head_sha }}
+fix_code:
+  - language: yaml
+    label: 'Broken: merge_group runs collapse to ci- (empty PR number)'
+    code: |
+      on:
+        pull_request:
+        merge_group:
+
+      concurrency:
+        group: ci-${{ github.event.pull_request.number }}
+        cancel-in-progress: true
+  - language: yaml
+    label: 'Fixed: fallback to merge_group.head_sha for merge queue runs'
+    code: |
+      on:
+        pull_request:
+        merge_group:
+
+      concurrency:
+        # pull_request: keyed by PR number (e.g., ci-42)
+        # merge_group:  keyed by batch SHA (unique per merge queue batch)
+        group: ci-${{ github.event.pull_request.number || github.event.merge_group.head_sha }}
+        cancel-in-progress: true
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: make test
+prevention:
+  - 'When adding merge_group to an existing pull_request workflow, audit every concurrency group expression for github.event.pull_request.* references — all are null on merge_group events'
+  - 'Use github.event.merge_group.head_sha as the fallback identifier for merge queue runs; it is unique per batch'
+  - 'Verify the resolved concurrency key by adding a debug step that prints the evaluated expression for each event type'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#merge_group'
+    label: 'GitHub Docs: merge_group event'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency'
+  - url: 'https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue'
+    label: 'GitHub Docs: Managing a merge queue'

package/errors/concurrency-timing/push-schedule-shared-concurrency-silent-cancel.yml

@@ -0,0 +1,84 @@
+id: concurrency-timing-050
+title: 'push and schedule sharing a concurrency group silently cancel each other on the default branch'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - push
+  - schedule
+  - cancel-in-progress
+  - nightly-build
+  - silent-failure
+patterns:
+  - regex: 'Canceling since a higher priority waiting run was found'
+    flags: 'i'
+  - regex: 'This run was automatically cancelled'
+    flags: 'i'
+error_messages:
+  - 'This run was automatically cancelled'
+  - 'Canceling since a higher priority waiting run was found'
+root_cause: |
+  When a workflow responds to both on.push and on.schedule, and uses a concurrency
+  group key that does not include github.event_name, all push and schedule runs share
+  the same concurrency slot.
+
+  Both a push to the default branch and a scheduled run targeting the default branch
+  evaluate github.ref to refs/heads/main (or the configured default branch name).
+  A concurrency group of ${{ github.workflow }}-${{ github.ref }} therefore produces
+  an identical key for both event types.
+
+  With cancel-in-progress: true, any push commit that lands while a scheduled run
+  (nightly build, report, data sync) is executing immediately cancels that run with
+  no error notification. With cancel-in-progress: false, the one pending-run slot is
+  taken by the push run, silently displacing any queued scheduled run.
+
+  This is distinct from the workflow_dispatch + schedule pattern (concurrency-timing-047)
+  because push events are emitted automatically on every commit and are far more
+  frequent than manual dispatches, making accidental cancellation of scheduled runs a
+  routine occurrence rather than an occasional manual event.
+fix: |
+  Include github.event_name in the concurrency group key so that push runs and
+  schedule runs each occupy a separate, independent slot:
+
+    group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
+fix_code:
+  - language: yaml
+    label: 'Broken: push and schedule share one slot'
+    code: |
+      on:
+        push:
+          branches: [main]
+        schedule:
+          - cron: '0 2 * * *'
+
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+  - language: yaml
+    label: 'Fixed: include github.event_name to isolate push and schedule concurrency slots'
+    code: |
+      on:
+        push:
+          branches: [main]
+        schedule:
+          - cron: '0 2 * * *'
+
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: make test
+prevention:
+  - 'Always include ${{ github.event_name }} in the concurrency group key for workflows triggered by both automated (push/pull_request) and scheduled events'
+  - 'After adding on.schedule to an existing push-triggered workflow, audit the concurrency group key to confirm scheduled runs receive their own independent slot'
+  - 'Monitor the Actions tab for unexpected gaps in scheduled run history — silent cancellations leave no failed run, only a missing run for that time slot'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule'
+    label: 'GitHub Docs: schedule event'

package/errors/known-unsolved/vars-context-reusable-workflow-reflects-caller-repo.yml

@@ -0,0 +1,91 @@
+id: known-unsolved-059
+title: 'vars context in reusable workflows reflects the CALLER repository variables — the called workflow repository-level vars are inaccessible'
+category: known-unsolved
+severity: limitation
+tags:
+  - vars
+  - reusable-workflow
+  - workflow_call
+  - variables
+  - configuration
+  - known-limitation
+patterns:
+  - regex: 'vars\.[A-Z_]+'
+    flags: 'i'
+  - regex: 'workflow_call'
+    flags: 'i'
+error_messages:
+  - '(no runtime error — vars context silently returns caller repository values instead of called workflow repository values)'
+root_cause: |
+  GitHub Actions populates the vars context in a reusable workflow called via
+  workflow_call using the CALLER repository organization, repository, and environment
+  variables — not those defined in the repository that hosts the reusable workflow.
+
+  This means repository-level variables set in the reusable workflow repository are
+  not accessible when the workflow executes in another repository context. The vars
+  context in the called workflow reflects only:
+    - Organization-level variables visible to the caller
+    - The CALLER repository-level variables
+    - Environment-scoped variables from environments the caller deploys to
+
+  Unlike secrets (which has secrets: inherit), there is no vars: inherit mechanism.
+  A shared reusable workflow library that stores its own configuration in
+  repository-level variables cannot access those values at runtime when called
+  from another repository.
+
+  The workflow runs without error but references wrong or empty variable values
+  silently, producing incorrect behavior that is difficult to diagnose because
+  the runner logs show no permission error.
+fix: |
+  There is no built-in mechanism to make the called workflow repository-level
+  variables available at runtime.
+
+  Available workarounds:
+  1. Promote shared configuration to organization-level variables — visible to
+     all member repositories and available in both caller and called contexts.
+  2. Pass required values as explicit workflow_call inputs from the caller:
+       with:
+         registry_url: ${{ vars.REGISTRY_URL }}
+  3. Store shared configuration in a committed file in the called workflow
+     repository and read it via a step after checkout.
+fix_code:
+  - language: yaml
+    label: 'Workaround: pass configuration values as explicit workflow_call inputs'
+    code: |
+      # Caller repository workflow
+      jobs:
+        deploy:
+          uses: org/shared-workflows/.github/workflows/deploy.yml@main
+          with:
+            deploy_env: ${{ vars.DEPLOY_ENV }}
+            registry_url: ${{ vars.REGISTRY_URL }}
+          secrets: inherit
+
+      ---
+      # Called reusable workflow (in org/shared-workflows repo)
+      on:
+        workflow_call:
+          inputs:
+            deploy_env:
+              type: string
+              required: true
+            registry_url:
+              type: string
+              required: true
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying to ${{ inputs.deploy_env }}"
+prevention:
+  - 'Do not rely on repository-level vars in a shared reusable workflow library repo — they will not be available when the workflow runs in another repository context'
+  - 'Use organization-level variables for shared configuration that must be accessible from reusable workflows across all member repositories'
+  - 'Document all required configuration values as explicit workflow_call inputs with type and description so callers know exactly what to pass'
+  - 'Audit shared workflow libraries for vars. references that assume the called repo context — they will silently read caller repo values or return empty strings'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#vars-context'
+    label: 'GitHub Docs: vars context'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#passing-inputs-and-secrets-to-a-reusable-workflow'
+    label: 'GitHub Docs: Passing inputs and secrets to a reusable workflow'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables'
+    label: 'GitHub Docs: Store information in variables'

package/errors/permissions-auth/security-events-write-required-for-sarif-upload.yml

@@ -0,0 +1,104 @@
+id: permissions-auth-063
+title: 'security-events: write required for SARIF upload — missing permission causes Resource not accessible by integration'
+category: permissions-auth
+severity: error
+tags:
+  - security-events
+  - sarif
+  - code-scanning
+  - permissions
+  - upload-sarif
+  - github-token
+patterns:
+  - regex: 'Resource not accessible by integration'
+    flags: 'i'
+  - regex: 'HttpError: Resource not accessible by integration'
+    flags: 'i'
+  - regex: 'Code scanning is not enabled for this repository'
+    flags: 'i'
+  - regex: 'Advanced Security must be enabled for this repository to use code scanning'
+    flags: 'i'
+error_messages:
+  - 'Resource not accessible by integration'
+  - 'HttpError: Resource not accessible by integration'
+  - 'Code scanning is not enabled for this repository'
+  - 'Advanced Security must be enabled for this repository to use code scanning'
+root_cause: |
+  The github/codeql-action/upload-sarif action and third-party security scanning
+  actions (Trivy, Snyk, Semgrep, osv-scanner, etc.) submit SARIF results to the
+  GitHub code scanning API endpoint POST /repos/{owner}/{repo}/code-scanning/sarifs.
+  This endpoint requires the security-events: write permission on the GITHUB_TOKEN.
+
+  Since February 2023, newly created repositories default GITHUB_TOKEN to read-only
+  permissions. A workflow that calls upload-sarif without an explicit
+  security-events: write permission block will receive 403 Resource not accessible by
+  integration from the API and the scan results will not appear in the Security tab.
+
+  This error is commonly overlooked because:
+  1. The scanning step (CodeQL analyze, Trivy scan, Semgrep scan) often completes
+     successfully — the red X appears only on the upload step.
+  2. Example workflows published before the read-only-default policy may omit the
+     security-events: write permission line.
+  3. For fork pull requests, the pull_request trigger cannot write security-events
+     even with the permission declared — a workflow_run split pattern is required.
+fix: |
+  Add security-events: write to the job permissions block. Include contents: read
+  for checkout and actions: read if the workflow uses CodeQL (which needs to read
+  workflow definitions).
+fix_code:
+  - language: yaml
+    label: 'Add security-events: write for SARIF upload'
+    code: |
+      jobs:
+        scan:
+          runs-on: ubuntu-latest
+          permissions:
+            security-events: write   # required for upload-sarif
+            contents: read           # required for checkout
+            actions: read            # required by CodeQL to read workflow info
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run Trivy vulnerability scanner
+              uses: aquasecurity/trivy-action@master
+              with:
+                scan-type: 'fs'
+                format: 'sarif'
+                output: 'trivy-results.sarif'
+            - name: Upload Trivy results to GitHub Security tab
+              uses: github/codeql-action/upload-sarif@v3
+              with:
+                sarif_file: 'trivy-results.sarif'
+  - language: yaml
+    label: 'Fork PRs: upload SARIF in a workflow_run triggered workflow (has write access)'
+    code: |
+      # Scanning step runs in pull_request context (no write access from fork)
+      # Upload step runs in workflow_run context (has security-events: write)
+      on:
+        workflow_run:
+          workflows: ['Security Scan']
+          types: [completed]
+      jobs:
+        upload-results:
+          runs-on: ubuntu-latest
+          permissions:
+            security-events: write
+          steps:
+            - name: Download SARIF artifact
+              uses: actions/download-artifact@v4
+              with:
+                run-id: ${{ github.event.workflow_run.id }}
+                name: sarif-results
+            - uses: github/codeql-action/upload-sarif@v3
+              with:
+                sarif_file: results.sarif
+prevention:
+  - 'Add security-events: write to every job that calls github/codeql-action/upload-sarif or any third-party SARIF upload action'
+  - 'For fork pull request scanning, use the workflow_run + artifact pattern — the pull_request trigger cannot write security-events from fork contexts'
+  - 'Check the Security tab after a scan workflow succeeds — absence of scan results despite a green workflow is the primary indicator of missing security-events permission'
+docs:
+  - url: 'https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github'
+    label: 'GitHub Docs: Uploading a SARIF file to GitHub'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/assigning-permissions-to-jobs'
+    label: 'GitHub Docs: Assigning permissions to jobs'
+  - url: 'https://docs.github.com/en/code-security/code-scanning/troubleshooting-code-scanning/results-are-different-than-expected'
+    label: 'GitHub Docs: Code scanning troubleshooting — results are different than expected'

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

@@ -0,0 +1,132 @@
+id: runner-environment-180
+title: 'ubuntu-24.04 removes Mono/MSBuild/NuGet — .NET Framework net48/net40 builds fail with "command not found"'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24
+  - ubuntu-latest
+  - mono
+  - msbuild
+  - nuget
+  - dotnet-framework
+  - migration
+  - tool-removed
+patterns:
+  - regex: 'mono: command not found'
+    flags: 'i'
+  - regex: 'msbuild: command not found'
+    flags: 'i'
+  - regex: '/usr/bin/msbuild.*No such file or directory'
+    flags: 'i'
+  - regex: 'nuget: command not found'
+    flags: 'i'
+  - regex: 'Could not find file.*msbuild\.exe'
+    flags: 'i'
+error_messages:
+  - "mono: command not found"
+  - "msbuild: command not found"
+  - "nuget: command not found"
+  - "/usr/bin/msbuild: No such file or directory"
+  - "bash: line 1: mono: command not found"
+root_cause: |
+  When GitHub Actions migrated `ubuntu-latest` to Ubuntu 24.04 (rollout Dec 2024 –
+  Jan 2025, runner-images#10636), the Mono framework, mono-based MSBuild, and mono-based
+  NuGet were intentionally removed from the Ubuntu 24.04 runner image. These packages
+  are not available in Ubuntu 24.04 (Noble Numbat) apt repositories because Mono is not
+  maintained for Noble.
+
+  Affected workflows:
+  - .NET Framework projects targeting net40, net45, net46, net47, net48 built on Linux
+    using Mono (common for Unity CI, Windows-targeted libraries, legacy C# projects)
+  - Any workflow running `mono`, `msbuild`, or `nuget` shell commands on ubuntu-latest
+  - Third-party actions that internally call mono (e.g., Unity build actions, some .NET
+    test runners)
+
+  The failure is immediate and obvious ("command not found") but the root cause is often
+  unclear because the workflow worked fine on ubuntu-22.04. The ubuntu-latest label
+  silently changed the underlying image, not the workflow YAML.
+
+  Source: actions/runner-images#10636 (384 reactions, closed Jan 2025),
+  actions/runner-images#11675 (mono specifically, closed "not planned" — Mono will NOT
+  be added back to ubuntu-24.04).
+fix: |
+  Option 1 (recommended for most cases): Switch to windows-latest
+  .NET Framework targets are first-class on Windows runners which still include MSBuild,
+  NuGet, and full .NET Framework support. Most .csproj net48 builds run correctly on
+  windows-latest.
+
+  Option 2: Install Mono at runtime on Ubuntu 22.04 (not 24.04)
+  Pin to ubuntu-22.04 (supported until April 2027) and install Mono via apt at runtime:
+    sudo apt-get install -y mono-complete msbuild
+
+  Option 3: Migrate to .NET Core / .NET 6+ with multi-targeting
+  Add a `net8.0` target to your csproj alongside `net48` for CI builds on Linux, and
+  build the Linux target on ubuntu-latest. The Windows-only target can be built on
+  windows-latest in a separate matrix job.
+
+  Option 4: Use a Docker container with Mono
+  Run the build step in a `mono:latest` container:
+    container: mono:latest
+fix_code:
+  - language: yaml
+    label: 'Switch net48 / Mono builds to windows-latest'
+    code: |
+      jobs:
+        build:
+          runs-on: windows-latest   # .NET Framework is fully supported on Windows runners
+          steps:
+            - uses: actions/checkout@v4
+            - name: Setup MSBuild
+              uses: microsoft/setup-msbuild@v2
+            - name: Restore NuGet packages
+              run: nuget restore MySolution.sln
+            - name: Build
+              run: msbuild MySolution.sln /p:Configuration=Release
+  - language: yaml
+    label: 'Pin to ubuntu-22.04 and install Mono at runtime'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-22.04   # ubuntu-24.04 has no Mono; 22.04 supported until April 2027
+          steps:
+            - uses: actions/checkout@v4
+            - name: Install Mono
+              run: |
+                sudo apt-get update -q
+                sudo apt-get install -y mono-complete msbuild
+            - name: Build
+              run: msbuild MySolution.sln /p:Configuration=Release
+  - language: yaml
+    label: 'Matrix build separating Linux .NET Core from Windows .NET Framework'
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              include:
+                - os: ubuntu-latest
+                  target: net8.0
+                - os: windows-latest
+                  target: net48
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - uses: microsoft/setup-msbuild@v2
+              if: runner.os == 'Windows'
+            - name: Build
+              run: dotnet build -f ${{ matrix.target }} -c Release
+prevention:
+  - 'Pin `runs-on: ubuntu-22.04` for any workflow requiring Mono, msbuild, or nuget CLI on Linux'
+  - 'Use `windows-latest` for all .NET Framework (net40/45/46/47/48) builds — MSBuild is native there'
+  - 'Audit workflows for bare `mono`, `msbuild`, or `nuget` commands before migrating ubuntu-latest'
+  - 'Consider migrating legacy .NET Framework projects to .NET 8+ for platform-agnostic CI'
+  - 'Check runner software lists at https://github.com/actions/runner-images for tool availability per OS'
+docs:
+  - url: 'https://github.com/actions/runner-images/issues/10636'
+    label: 'actions/runner-images#10636: Ubuntu-latest migrates to Ubuntu-24.04 (384 reactions, Jan 2025)'
+  - url: 'https://github.com/actions/runner-images/issues/11675'
+    label: 'actions/runner-images#11675: Mono missing on Ubuntu 24.04 (closed not_planned — will not be added back)'
+  - url: 'https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md'
+    label: 'Ubuntu 24.04 runner image software list'
+  - url: 'https://github.com/microsoft/setup-msbuild'
+    label: 'microsoft/setup-msbuild action for Windows runners'