@htekdev/actions-debugger 1.0.116 → 1.0.118

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)'

package/errors/yaml-syntax/duplicate-step-id-within-job-scope-validation-error.yml

@@ -0,0 +1,130 @@
+id: yaml-syntax-071
+title: 'Duplicate `id:` values within the same job or composite action cause instant
+  workflow validation failure'
+category: yaml-syntax
+severity: error
+tags:
+  - step-id
+  - duplicate
+  - validation
+  - composite-action
+  - copy-paste
+patterns:
+  - regex: 'The identifier .* may not be used more than once within the same scope'
+    flags: 'i'
+  - regex: 'TemplateValidationException.*may not be used more than once'
+    flags: 'i'
+error_messages:
+  - "The workflow is not valid. .github/workflows/ci.yml (Line: N, Col: N): The identifier 'checkout'
+    may not be used more than once within the same scope."
+  - "The identifier 'meta' may not be used more than once within the same scope."
+  - "GitHub.DistributedTask.ObjectTemplating.TemplateValidationException: The template is not valid."
+root_cause: |
+  Step IDs (`id:`) must be unique within a single job or composite action. If two or more
+  steps within the same scope share the same `id:` value, GitHub Actions rejects the entire
+  workflow before any step runs, throwing a `TemplateValidationException`.
+
+  Step IDs form the keys of the `steps` context object. Duplicate keys would make
+  `${{ steps.checkout.outputs.ref }}` ambiguous — the platform rejects this ambiguity at
+  parse time rather than silently choosing one arbitrarily at runtime.
+
+  The most common root cause is copy-pasting steps within a job — particularly repeating
+  `actions/checkout`, `docker/metadata-action`, or `actions/setup-node` blocks — without
+  updating or removing the `id:` field on the duplicate. Composite action authors also
+  hit this when a second action step is added without checking existing IDs.
+
+  The error message reports only the SECOND occurrence's line and column, not both —
+  making it harder to locate the original conflicting step in long step lists.
+  (Tracked as actions/runner#3121 as an open bug requesting improved error reporting.)
+fix: |
+  Ensure every step that declares an `id:` uses a unique value within its job or composite
+  action scope. Steps that are not referenced by later steps can omit `id:` entirely —
+  only steps whose outputs are used in expressions (`${{ steps.X.outputs.Y }}`) need an ID.
+fix_code:
+  - language: yaml
+    label: 'WRONG — duplicate id: "meta" causes TemplateValidationException'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Extract metadata for Docker Hub
+              id: meta                          # first declaration
+              uses: docker/metadata-action@v5
+              with:
+                images: myorg/myapp
+
+            - name: Extract metadata for GHCR
+              id: meta                          # DUPLICATE — workflow rejected
+              uses: docker/metadata-action@v5
+              with:
+                images: ghcr.io/myorg/myapp
+
+            - uses: docker/build-push-action@v6
+              with:
+                tags: ${{ steps.meta.outputs.tags }}
+  - language: yaml
+    label: 'RIGHT — unique IDs for each step'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Extract metadata for Docker Hub
+              id: meta-dockerhub
+              uses: docker/metadata-action@v5
+              with:
+                images: myorg/myapp
+
+            - name: Extract metadata for GHCR
+              id: meta-ghcr
+              uses: docker/metadata-action@v5
+              with:
+                images: ghcr.io/myorg/myapp
+
+            - name: Build and push to Docker Hub
+              uses: docker/build-push-action@v6
+              with:
+                tags: ${{ steps.meta-dockerhub.outputs.tags }}
+                labels: ${{ steps.meta-dockerhub.outputs.labels }}
+
+            - name: Build and push to GHCR
+              uses: docker/build-push-action@v6
+              with:
+                tags: ${{ steps.meta-ghcr.outputs.tags }}
+                labels: ${{ steps.meta-ghcr.outputs.labels }}
+  - language: yaml
+    label: 'RIGHT — omit id: on steps whose outputs are never referenced'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              # No id: needed — outputs not referenced by other steps
+
+            - uses: actions/setup-node@v4
+              with:
+                node-version: '20'
+              # No id: needed — only referenced outputs need a step id
+
+            - id: version
+              run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
+
+            - run: echo "Building version ${{ steps.version.outputs.version }}"
+prevention:
+  - 'When copy-pasting steps within a job, immediately update or remove the `id:` field on
+    the duplicate to avoid the conflict.'
+  - 'Use actionlint or a YAML linter locally before pushing — both catch duplicate step IDs
+    and report the error with line numbers for both occurrences.'
+  - 'Only assign `id:` to steps whose outputs are referenced in expressions elsewhere in the
+    job; leave unreferenced steps without `id:`.'
+  - 'Apply the same uniqueness rule to composite actions — step IDs within a composite action
+    must also be unique within the action file.'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsid'
+    label: 'GitHub Docs: jobs.<job_id>.steps[*].id'
+  - url: 'https://github.com/actions/runner/issues/3121'
+    label: 'actions/runner#3121 — Request to improve duplicate step ID error message (Jan 2024)'
+  - url: 'https://ghlint.twisterrob.net/issues/default/DuplicateStepId/'
+    label: 'GH-Lint: DuplicateStepId rule documentation'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htekdev/actions-debugger",
-  "version": "1.0.116",
+  "version": "1.0.118",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",