@htekdev/actions-debugger 1.0.117 → 1.0.118

package/errors/runner-environment/ubuntu-24-man-db-dpkg-trigger-apt-install-stall.yml

@@ -0,0 +1,94 @@
+id: runner-environment-207
+title: 'ubuntu-24.04 man-db dpkg trigger stalls apt-get install for minutes'
+category: runner-environment
+severity: warning
+tags:
+  - ubuntu-24.04
+  - apt-get
+  - man-db
+  - dpkg-trigger
+  - package-installation
+  - self-hosted
+patterns:
+  - regex: 'Processing triggers for man-db \('
+    flags: 'i'
+  - regex: 'man-db \(2\.1[0-9]\.[0-9]'
+    flags: 'i'
+error_messages:
+  - 'Processing triggers for man-db (2.12.0-4build2) ...'
+  - 'Processing triggers for man-db ...'
+root_cause: |
+  The `man-db` package is pre-installed on ubuntu-24.04 GitHub-hosted runner
+  images (and is commonly present on self-hosted Ubuntu 24.04 runners). When
+  any `apt-get install` step installs or upgrades a package that ships man
+  pages, the dpkg trigger for `man-db` fires automatically and rebuilds the
+  entire manual-page database.
+
+  On ubuntu-24.04 runners, this database regeneration reads and writes several
+  gigabytes of data through the runner's I/O subsystem, which is heavily
+  shared and has limited I/O resources. The trigger typically hangs the step
+  for **1–7+ minutes** even for simple package installs like `cmake` or
+  `libssl-dev`.
+
+  GitHub fixed this in hosted runner image ubuntu24/20251102.99 (November
+  2025) by removing `man-db` from the default image. However, self-hosted
+  runners on Ubuntu 24.04 that predate this fix, Docker-based container jobs
+  using ubuntu:24.04, and pinned runner image versions remain affected.
+
+  The equivalent tzdata hang (`sudo DEBIAN_FRONTEND=noninteractive apt-get ...`)
+  is a separate issue caused by interactive prompts; the man-db issue is
+  distinct — it stalls silently with no interactive prompt.
+fix: |
+  **For self-hosted runners or container jobs (manual fix):**
+
+  Add a step before package installation to remove man-db:
+
+  ```yaml
+  - name: Disable man-db trigger
+    run: sudo rm -f /var/lib/man-db/auto-update
+  ```
+
+  Or uninstall man-db entirely:
+
+  ```yaml
+  - name: Remove man-db
+    run: sudo apt-get remove -y --purge man-db 2>/dev/null || true
+  ```
+
+  **For GitHub-hosted runners:**
+  Upgrade to ubuntu-24.04 runner image version ubuntu24/20251102.99 or later.
+  The latest ubuntu-24.04 label automatically uses a fixed image.
+
+  **Minimal impact workaround (all runners):**
+  Use `DEBIAN_FRONTEND=noninteractive` — this avoids tzdata prompts but does
+  NOT prevent the man-db trigger. You must use the `rm -f /var/lib/man-db/auto-update`
+  approach to suppress the trigger.
+fix_code:
+  - language: yaml
+    label: 'Disable man-db trigger before apt-get install'
+    code: |
+      - name: Remove man-db auto-update trigger
+        run: sudo rm -f /var/lib/man-db/auto-update
+
+      - name: Install dependencies
+        run: sudo apt-get install -y cmake libssl-dev
+  - language: yaml
+    label: 'Uninstall man-db entirely (self-hosted runners)'
+    code: |
+      - name: Remove man-db (prevents dpkg trigger overhead)
+        run: sudo apt-get remove -y --purge man-db 2>/dev/null || true
+
+      - name: Install dependencies
+        run: sudo apt-get install -y cmake libssl-dev
+prevention:
+  - 'Add a man-db removal step at the top of jobs that run apt-get install on self-hosted ubuntu-24.04 runners'
+  - 'On GitHub-hosted runners, always use the current ubuntu-24.04 label (not pinned image SHAs from before November 2025)'
+  - 'For Docker container jobs, use an image that does not pre-install man-db, or add the removal step to your Dockerfile'
+  - 'Set a job-level timeout-minutes so that an unexpected man-db stall does not consume runner quota for hours'
+docs:
+  - url: 'https://github.com/actions/runner/issues/4030'
+    label: 'actions/runner#4030 — man-db trigger severely stalls apt-get on ubuntu-24.04'
+  - url: 'https://github.com/actions/runner-images/issues/10977'
+    label: 'runner-images#10977 — Disable man-db dpkg trigger (fixed in ubuntu24/20251102.99)'
+  - url: 'https://bugs.launchpad.net/ubuntu/+source/man-db/+bug/2073797'
+    label: 'Ubuntu bug #2073797 — man-db trigger performance regression'

package/errors/runner-environment/ubuntu-26-04-missing-preinstalled-tools.yml

@@ -0,0 +1,178 @@
+id: runner-environment-212
+title: 'ubuntu-26.04 Runner Image Removes Many Pre-installed Tools — grunt, gulp, tsc, webpack, lerna, fastlane, Pulumi, Julia, Miniconda Absent'
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-26.04
+  - runner-image
+  - pre-installed-tools
+  - migration
+  - breaking-change
+  - nodejs-tools
+  - toolset
+patterns:
+  - regex: 'grunt: command not found|grunt.*not found.*ubuntu'
+    flags: 'i'
+  - regex: 'gulp: command not found|gulp.*not found.*ubuntu'
+    flags: 'i'
+  - regex: '(tsc|webpack|webpack-cli|lerna|newman|parcel): command not found'
+    flags: 'i'
+  - regex: 'fastlane: command not found|fastlane.*not found.*ubuntu'
+    flags: 'i'
+  - regex: 'pulumi: command not found|julia: command not found|conda: command not found'
+    flags: 'i'
+error_messages:
+  - '/usr/bin/env: grunt: No such file or directory'
+  - 'grunt: command not found'
+  - 'webpack: command not found'
+  - 'tsc: command not found'
+  - 'gulp: command not found'
+  - 'lerna: command not found'
+  - 'newman: command not found'
+  - 'parcel: command not found'
+  - 'fastlane: command not found'
+  - 'pulumi: command not found'
+  - 'julia: command not found'
+  - 'conda: command not found'
+root_cause: |
+  The ubuntu-26.04 GitHub Actions hosted runner image deliberately removes many
+  tools that were pre-installed on ubuntu-22.04 and ubuntu-24.04. The toolset
+  was slimmed as part of the ubuntu-26.04 image build (runner-images commit
+  9e3319d, `[ubuntu-26] Adjust installed software`, May 2026).
+
+  **Removed global Node.js CLI tools** (previously installed via npm globally):
+  - `grunt` / `grunt-cli`
+  - `gulp` / `gulp-cli`
+  - `tsc` (TypeScript compiler, was pre-installed globally)
+  - `webpack` and `webpack-cli`
+  - `lerna` (monorepo manager)
+  - `newman` (Postman CLI runner)
+  - `parcel` (zero-config bundler)
+
+  **Removed Ruby gems:**
+  - `fastlane` (iOS/Android CI automation)
+
+  **Removed language runtimes / tools:**
+  - `julia` (Julia language, x86_64 only — was in ubuntu-24.04 x64)
+  - `miniconda` / `conda` (x86_64 only — was in ubuntu-24.04 x64)
+  - `pulumi` (IaC CLI, both x86_64 and ARM64)
+
+  **Removed system utilities:**
+  - `mercurial` (hg version control)
+  - `haveged` (entropy daemon)
+  - `mediainfo` (media analysis tool)
+  - `sphinxsearch` (full-text search server)
+
+  **Other significant changes on ubuntu-26.04 vs ubuntu-24.04:**
+  - **Helm**: updated from 3.x → 4.x (get-helm-4 installer)
+  - **Docker Compose**: updated from 2.40.3 → 5.1.3 (major version bump)
+  - **Java default**: changed from Java 21 → Java 25
+  - `Fastlane` removed from rubygems pre-install
+
+  Workflows that rely on these tools being pre-installed without an explicit
+  installation step will fail immediately on ubuntu-26.04 with "command not
+  found" errors.
+fix: |
+  Explicitly install any removed tools in your workflow steps before use.
+
+  For global Node.js tools, add an installation step at the start of your job:
+
+  ```yaml
+  - name: Install build tools
+    run: npm install -g grunt-cli gulp-cli typescript webpack webpack-cli lerna newman parcel
+  ```
+
+  For fastlane:
+  ```yaml
+  - name: Install fastlane
+    run: gem install fastlane
+  ```
+
+  For Pulumi:
+  ```yaml
+  - uses: pulumi/actions@v6
+  # or
+  - name: Install Pulumi CLI
+    run: curl -fsSL https://get.pulumi.com | sh
+  ```
+
+  For Julia:
+  ```yaml
+  - uses: julia-actions/setup-julia@v2
+    with:
+      version: '1'
+  ```
+
+  For Conda / Miniconda:
+  ```yaml
+  - uses: conda-incubator/setup-miniconda@v3
+    with:
+      auto-activate-base: true
+  ```
+
+  For Java 21 (if Java 25 default breaks your build):
+  ```yaml
+  - uses: actions/setup-java@v4
+    with:
+      java-version: '21'
+      distribution: 'temurin'
+  ```
+fix_code:
+  - language: yaml
+    label: 'Explicitly install removed Node.js tools and pin Java version on ubuntu-26.04'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-26.04   # or ubuntu-latest when it aliases ubuntu-26.04
+          steps:
+            - uses: actions/checkout@v6
+
+            # Install tools removed from ubuntu-26.04 pre-installed toolset
+            - name: Install missing build tools
+              run: |
+                npm install -g grunt-cli typescript webpack webpack-cli lerna
+                gem install fastlane
+
+            # Pin Java version explicitly — ubuntu-26.04 defaults to Java 25
+            - uses: actions/setup-java@v4
+              with:
+                java-version: '21'
+                distribution: 'temurin'
+
+            - name: Build
+              run: |
+                tsc --version   # now available
+                grunt build     # now available
+  - language: yaml
+    label: 'Guard workflow with image-conditional tool install'
+    code: |
+      jobs:
+        build:
+          runs-on: ${{ matrix.os }}
+          strategy:
+            matrix:
+              os: [ubuntu-24.04, ubuntu-26.04]
+          steps:
+            - uses: actions/checkout@v6
+
+            # Install tools only when running on ubuntu-26.04
+            # where they are not pre-installed
+            - name: Install tools absent on ubuntu-26.04
+              if: startsWith(matrix.os, 'ubuntu-26')
+              run: npm install -g grunt-cli gulp-cli typescript webpack webpack-cli lerna newman
+
+            - name: Build
+              run: grunt build
+prevention:
+  - 'Do not rely on pre-installed tools being available across Ubuntu runner generations — explicitly install all tools your workflow depends on.'
+  - 'Pin Java version with actions/setup-java rather than relying on the image default Java version, which changed from 21 to 25 on ubuntu-26.04.'
+  - 'Use actions/setup-node + local project devDependencies instead of globally pre-installed Node.js tools (grunt, webpack, tsc, etc.).'
+  - 'Review the ubuntu-26.04 software manifest before migrating workflows from ubuntu-24.04 or ubuntu-latest.'
+  - 'When ubuntu-latest eventually aliases ubuntu-26.04, workflows that assume pre-installed tools from ubuntu-24.04 will break silently or with "command not found" errors.'
+docs:
+  - url: 'https://github.com/actions/runner-images/commit/9e3319d6b4acc306925295853d0ff41ddd5c40f0'
+    label: 'runner-images commit 9e3319d — [ubuntu-26] Adjust installed software (May 2026)'
+  - url: 'https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2604-Readme.md'
+    label: 'ubuntu-26.04 installed software manifest'
+  - url: 'https://github.com/actions/runner-images/issues/14150'
+    label: 'runner-images #14150 — PowerShell 7.4→7.6 announcement (lists ubuntu-26.04 as supported image)'

package/errors/runner-environment/upload-artifact-v6-proxy-headers-leak-strict-proxy-fail.yml

@@ -0,0 +1,101 @@
+id: runner-environment-208
+title: 'upload-artifact@v6 fails behind strict corporate proxy — ECONNRESET or HTTP 400 on CONNECT tunnel'
+category: runner-environment
+severity: error
+tags:
+  - upload-artifact
+  - v6
+  - proxy
+  - self-hosted
+  - ECONNRESET
+  - corporate-network
+  - azure-storage
+patterns:
+  - regex: 'Proxy connection ended before receiving CONNECT response'
+    flags: 'i'
+  - regex: 'Unable to make request: ECONNRESET'
+    flags: 'i'
+  - regex: 'upload-artifact@v[6-9]'
+    flags: 'i'
+error_messages:
+  - 'Error: Proxy connection ended before receiving CONNECT response'
+  - 'Error: Unable to make request: ECONNRESET'
+  - 'HTTP 400 Bad Request from proxy'
+root_cause: |
+  `actions/upload-artifact@v6` switched its Azure Blob Storage client from
+  `@azure/storage-blob` backed by `@azure/core-http` (used in v4/v5) to
+  `@azure/storage-blob` backed by `@azure/core-rest-pipeline` and
+  `@typespec/ts-http-runtime`.
+
+  The `proxyPolicy` in `@typespec/ts-http-runtime` contains a bug: it leaks
+  destination HTTP request headers — including `content-type`, `content-length`,
+  `x-ms-version`, and `accept` — directly into the HTTP `CONNECT` tunnel
+  request sent to the corporate proxy. RFC 9110 §9.3.6 does not expect
+  `CONNECT` requests to carry a `Content-Length`, and many strict enterprise
+  forward proxies (Squid with strict policies, Zscaler, BlueCoat, some HAProxy
+  configurations) reject `CONNECT` requests with unexpected headers.
+
+  This manifests as:
+  - `Proxy connection ended before receiving CONNECT response` — proxy drops
+    the connection before sending `200 Connection established`
+  - `ECONNRESET` — proxy resets the TCP connection
+  - HTTP 400 Bad Request — proxy rejects the malformed CONNECT
+
+  The issue does NOT reproduce with permissive proxies like default Squid
+  (which is why GitHub's own CI did not catch it). Only strict corporate proxies
+  that validate CONNECT request headers are affected.
+
+  `actions/upload-artifact@v5` uses the older `@azure/core-http` stack which
+  sends proper CONNECT tunnels without leaking headers, so workflows that pin
+  to v5 are not affected.
+
+  The fix was shipped in `actions/upload-artifact@v7.0.1` (April 12, 2026),
+  which bumps `@actions/artifact` to a version that uses the fixed
+  `@typespec/ts-http-runtime` proxyPolicy.
+fix: |
+  **Preferred fix:** Upgrade to `actions/upload-artifact@v7` (v7.0.1 or later):
+
+  ```yaml
+  - uses: actions/upload-artifact@v7
+    with:
+      name: build-artifacts
+      path: dist/
+  ```
+
+  **Temporary workaround (stay on v6):** Set the `HTTPS_PROXY` environment
+  variable AND apply a one-liner patch to strip headers from the ProxyAgent
+  call inside the cached action source:
+
+  ```yaml
+  - name: Patch upload-artifact proxy headers bug
+    run: |
+      for f in $(find "${GITHUB_WORKSPACE}/../.." -name "index.js" \
+        -path "*actions/upload-artifact*dist*" 2>/dev/null); do
+        sed -i 's/ProxyAgent(proxyUrl, { headers })/ProxyAgent(proxyUrl)/g' "$f"
+      done
+  ```
+
+  **Do NOT downgrade to v5** in new workflows; v5 relies on deprecated
+  dependencies. Upgrading to v7 is the correct long-term fix.
+fix_code:
+  - language: yaml
+    label: 'Upgrade to upload-artifact@v7 (recommended)'
+    code: |
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: build-artifacts
+          path: dist/
+          retention-days: 7
+prevention:
+  - 'Always upgrade upload-artifact to @v7 or later on self-hosted runners that sit behind a corporate proxy'
+  - 'When adding new @v6 steps, test on a runner behind your actual proxy before deploying to all pipelines'
+  - 'If the proxy blocks the artifact upload step silently, enable RUNNER_DEBUG=1 to see the full CONNECT request/response cycle'
+  - 'Pin to upload-artifact@v7.0.1 or later — earlier v7 releases were not published, v7.0.1 is the first tagged release'
+docs:
+  - url: 'https://github.com/actions/upload-artifact/issues/747'
+    label: 'upload-artifact#747 — V6 upload stalled behind proxy (10 reactions)'
+  - url: 'https://github.com/actions/upload-artifact/pull/792'
+    label: 'upload-artifact#792 — Fix proxy headers leak errconnect on strict proxies'
+  - url: 'https://github.com/actions/upload-artifact/releases/tag/v7.0.1'
+    label: 'upload-artifact v7.0.1 release notes — includes proxy fix'

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

@@ -0,0 +1,108 @@
+id: silent-failures-108
+title: 'Service container entrypoint: key silently clears Dockerfile CMD — Docker Compose semantics differ from Docker CLI'
+category: silent-failures
+severity: silent-failure
+tags:
+  - service-container
+  - docker
+  - entrypoint
+  - command
+  - docker-compose
+  - breaking-change
+  - april-2026
+patterns:
+  - regex: 'service.*container.*unhealthy|health.*check.*failed.*service'
+    flags: 'i'
+  - regex: 'Connection refused.*service|service.*port.*not.*reachable'
+    flags: 'i'
+  - regex: 'exec.*not.*enough.*arguments|usage:.*\[command\].*\[args\]'
+    flags: 'i'
+error_messages:
+  - 'Error: Service container failed health check after entrypoint override'
+  - 'Connection refused: service port not accepting connections'
+  - 'exec: not enough arguments — entrypoint launched without expected CMD'
+root_cause: |
+  GitHub Actions added explicit `entrypoint` and `command` keys for service containers
+  in the Early April 2026 update. These keys use **Docker Compose semantics**, which
+  differ from Docker CLI semantics in one critical way:
+
+  **Docker CLI** (`docker run --entrypoint /wrapper.sh image`):
+  - Overrides the image ENTRYPOINT
+  - **Keeps** the image CMD from the Dockerfile
+
+  **Docker Compose** / GitHub Actions `services.<name>.entrypoint` key:
+  - Overrides the image ENTRYPOINT
+  - **Clears the image CMD** — the container starts with no CMD arguments
+
+  This means that if a developer specifies only `entrypoint:` in a service container
+  (to wrap or replace the image's startup script) and does not also specify `command:`,
+  the container runs the new entrypoint with no arguments. For images that require CMD
+  arguments to function (e.g., a PostgreSQL image running `postgres`, a Redis image
+  running `redis-server`), the container may exit immediately, enter an error loop, or
+  start in a degraded mode.
+
+  The failure is silent because:
+  - The container may still pass a health check if it starts at all
+  - The job continues even if the service is in an unexpected state
+  - No GitHub Actions error is emitted for CMD mismatch
+
+  Example: migrating from `options: --entrypoint /wrapper.sh` (which preserved CMD)
+  to `entrypoint: /wrapper.sh` (which clears CMD) silently changes the container's
+  startup behaviour.
+fix: |
+  Always specify `command:` alongside `entrypoint:` in service container configuration
+  to explicitly provide the CMD arguments that the original Dockerfile would have
+  passed. Do not assume entrypoint-only overrides will inherit the Dockerfile CMD.
+
+  To preserve the original image's CMD, look up the image's Dockerfile CMD
+  (e.g., via `docker inspect <image> --format '{{.Config.Cmd}}'`) and replicate
+  it in the `command:` key.
+fix_code:
+  - language: yaml
+    label: 'Broken — entrypoint only, silently clears CMD (Docker Compose semantics)'
+    code: |
+      services:
+        db:
+          image: postgres:16
+          # WRONG: entrypoint alone clears the Dockerfile CMD ["postgres"]
+          # The container starts /wrapper.sh with no arguments — postgres never runs
+          entrypoint: /wrapper.sh
+
+  - language: yaml
+    label: 'Fixed — specify command: to preserve the intended CMD arguments'
+    code: |
+      services:
+        db:
+          image: postgres:16
+          env:
+            POSTGRES_PASSWORD: test
+          # Wrap the entrypoint AND preserve the original CMD
+          entrypoint: /wrapper.sh
+          command: ["postgres"]  # explicit CMD to preserve what Dockerfile would pass
+
+  - language: yaml
+    label: 'Alternative — use options: --entrypoint if you want to keep Dockerfile CMD'
+    code: |
+      services:
+        db:
+          image: postgres:16
+          env:
+            POSTGRES_PASSWORD: test
+          # Legacy approach: Docker CLI semantics — preserves Dockerfile CMD automatically
+          options: >-
+            --entrypoint /wrapper.sh
+            --health-cmd "pg_isready -U postgres"
+            --health-interval 5s
+
+prevention:
+  - 'When using the new entrypoint: key on a service container, always pair it with an explicit command: key — never rely on the Dockerfile CMD being inherited.'
+  - 'If migrating from options: --entrypoint to the new entrypoint: key, remember that the options: approach preserved CMD while the new key does not.'
+  - 'Test service container health immediately after adding entrypoint: overrides — a passing health check may mask CMD loss if the entrypoint script does not require CMD arguments.'
+  - 'Run docker inspect <image> --format "{{.Config.Cmd}}" locally to discover what CMD values the Dockerfile sets before overriding entrypoint in CI.'
+docs:
+  - url: 'https://github.blog/changelog/2026-04-02-github-actions-early-april-2026-updates/#customizing-entrypoints-for-service-containers'
+    label: 'GitHub Changelog: Customizing entrypoints for service containers (April 2026)'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idservicesservice_identrypoint'
+    label: 'GitHub Docs: jobs.<id>.services.<id>.entrypoint syntax'
+  - url: 'https://docs.docker.com/compose/compose-file/05-services/#entrypoint'
+    label: 'Docker Compose docs: entrypoint key clears CMD'

package/errors/triggers/pull-request-labeled-fires-all-labels-no-name-filter.yml

@@ -0,0 +1,110 @@
+id: triggers-070
+title: '`on: pull_request: types: [labeled]` fires for every label applied to a PR —
+  no trigger-level label-name filter exists; must use `if:` condition'
+category: triggers
+severity: silent-failure
+tags:
+  - pull_request
+  - labeled
+  - label
+  - types
+  - label-name-filter
+  - deployment-gate
+patterns:
+  - regex: 'types:\s*[\[\n].*labeled'
+    flags: 'si'
+error_messages:
+  - "No error — workflow runs for every label applied to the PR, including unrelated labels"
+  - "No error — workflow run count is higher than expected; runs appear for all label events"
+root_cause: |
+  When `types: [labeled]` is added to a `pull_request` trigger, the workflow fires for
+  EVERY label applied to the pull request — not only a specific label. There is no
+  trigger-level filter for label names. GitHub Actions does not support syntax like
+  `types: [labeled: 'deploy-preview']` or `label: 'X'` at the trigger level.
+
+  Teams building label-gated workflows (deploy-preview, run-integration-tests,
+  approved-for-staging, force-rebuild) are surprised to find the workflow fires for
+  entirely unrelated labels ('bug', 'enhancement', 'wontfix', 'good first issue').
+  The result is:
+  - Excessive workflow runs that show up in the Actions tab for every label event
+  - Wasted CI minutes for runs that skip all meaningful steps
+  - Unexpected side effects if the workflow performs mutations (deploy, comment, notify)
+    that should only happen for the specific label
+
+  This is distinct from the related issue triggers-030 ("labeled NOT in default types"):
+  - triggers-030: workflow NEVER fires because labeled is missing from default types
+  - triggers-070: workflow fires TOO OFTEN because ALL label events trigger it
+
+  The behavior is documented: `types: [labeled]` is a webhook activity type filter,
+  not a payload content filter. Payload-level filtering (label name, PR author, etc.)
+  must be done via `if:` conditions on jobs or steps.
+fix: |
+  Add a job-level `if:` condition filtering on `github.event.label.name`. This is the
+  only mechanism — no trigger-level label-name filtering exists.
+
+  Key context properties for label-based filtering:
+  - `github.event.action` — 'labeled' or 'unlabeled'
+  - `github.event.label.name` — the label JUST applied (only set for labeled/unlabeled events)
+  - `github.event.pull_request.labels.*.name` — ALL current labels on the PR (useful for
+    opened/synchronize/reopened events where a label may already be present)
+fix_code:
+  - language: yaml
+    label: 'WRONG — fires for every label including unrelated ones'
+    code: |
+      on:
+        pull_request:
+          types: [labeled]
+
+      jobs:
+        deploy-preview:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying preview..."
+            # Runs for EVERY label: 'bug', 'wontfix', 'enhancement', 'deploy-preview', etc.
+  - language: yaml
+    label: 'RIGHT — filter by specific label name with job-level if:'
+    code: |
+      on:
+        pull_request:
+          types: [labeled]
+
+      jobs:
+        deploy-preview:
+          if: github.event.label.name == 'deploy-preview'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying preview for PR #${{ github.event.pull_request.number }}"
+  - language: yaml
+    label: 'RIGHT — label gate that works for both labeled events AND already-labeled PRs'
+    code: |
+      on:
+        pull_request:
+          types:
+            - opened
+            - synchronize
+            - reopened
+            - labeled       # fires when any label is applied; filter below by name
+
+      jobs:
+        deploy-preview:
+          if: |
+            (github.event.action == 'labeled' && github.event.label.name == 'deploy-preview') ||
+            (github.event.action != 'labeled' && contains(github.event.pull_request.labels.*.name, 'deploy-preview'))
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying preview..."
+prevention:
+  - "Always pair `types: [labeled]` with `if: github.event.label.name == 'your-label'` at the job
+    level to gate on the specific label."
+  - 'Document which label triggers which workflow in a comment near the trigger definition.'
+  - 'Test label-gated workflows by applying both the expected label AND an unrelated label to verify
+    the `if:` filter correctly skips unintended runs.'
+  - 'Consider using only `types: [labeled]` (not opened/sync/reopened) if the workflow should only
+    run when the label is freshly applied, not on every code push to already-labeled PRs.'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request'
+    label: 'GitHub Docs: pull_request event — labeled activity type'
+  - url: 'https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request'
+    label: 'GitHub Webhook Docs: pull_request payload (label field)'
+  - url: 'https://stackoverflow.com/questions/62325286/run-github-actions-when-pull-requests-have-a-specific-label'
+    label: 'Stack Overflow: Run GitHub Actions when pull requests have a specific label (43 votes)'