@htekdev/actions-debugger 1.0.83 → 1.0.85

package/errors/caching-artifacts/docker-buildx-gha-cache-mode-min-partial-layers.yml

@@ -0,0 +1,91 @@
+id: caching-artifacts-049
+title: 'Docker buildx GHA cache mode:min only caches final layer — rebuilds remain slow'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - docker
+  - buildx
+  - gha-cache
+  - layer-cache
+  - mode-min
+  - silent-failure
+patterns:
+  - regex: 'cache-to.*type=gha'
+    flags: 'i'
+  - regex: 'importing\s+cache\s+manifest\s+from\s+ghcr\.io'
+    flags: 'i'
+  - regex: 'exporting\s+cache\s+.*\s+type=gha'
+    flags: 'i'
+error_messages:
+  - 'cache-to: type=gha'
+  - 'exporting cache to GitHub Actions Cache Service'
+  - 'CACHED [stage 2/4]'
+root_cause: |
+  docker/build-push-action uses cache-to: type=gha with mode=min by default when
+  no explicit mode is specified. In min mode, BuildKit exports ONLY the layers of
+  the final image (the last build stage), discarding all intermediate layer cache
+  data. This means:
+
+  - Multi-stage Dockerfiles get no benefit from the GHA cache for base/dependency
+    stages (the expensive ones) — only the final artifact stage is cached.
+  - Subsequent runs re-execute all intermediate stages from scratch while the
+    cache appears to "work" (export/import steps succeed in the logs).
+  - Developers see 80-90% cache miss rates and slow builds despite believing the
+    GHA cache is active.
+
+  The silent aspect: the workflow logs show cache export and import succeeding,
+  and BuildKit reports "CACHED" for layers it finds, with no warning that intermediate
+  stages were excluded from the cache.
+fix: |
+  Explicitly set mode=max on the cache-to option. This instructs BuildKit to export
+  ALL layer metadata — including every intermediate build stage — into the GHA cache.
+  Combined with cache-from: type=gha, all previously-built stages will be restored
+  on the next run.
+
+  Note: mode=max requires more GHA cache storage (subject to the 10 GB repository
+  limit). Use separate cache scopes per Dockerfile or build target to prevent
+  cross-contamination and LRU eviction pressure.
+fix_code:
+  - language: yaml
+    label: 'Set mode=max for full layer caching in multi-stage builds'
+    code: |
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ghcr.io/${{ github.repository }}:latest
+          cache-from: type=gha,scope=main
+          cache-to: type=gha,scope=main,mode=max
+  - language: yaml
+    label: 'Use separate scopes per Dockerfile to isolate caches'
+    code: |
+      - name: Build API image
+        uses: docker/build-push-action@v6
+        with:
+          context: ./api
+          push: true
+          tags: ghcr.io/${{ github.repository }}/api:latest
+          cache-from: type=gha,scope=api
+          cache-to: type=gha,scope=api,mode=max
+
+      - name: Build Frontend image
+        uses: docker/build-push-action@v6
+        with:
+          context: ./frontend
+          push: true
+          tags: ghcr.io/${{ github.repository }}/frontend:latest
+          cache-from: type=gha,scope=frontend
+          cache-to: type=gha,scope=frontend,mode=max
+prevention:
+  - 'Always explicitly set mode=max in cache-to: type=gha for multi-stage Dockerfiles'
+  - 'Use the scope= parameter to isolate caches per Dockerfile or build target'
+  - 'Monitor cache size with the GitHub Actions Cache API if approaching the 10 GB repository limit'
+  - 'Verify cache effectiveness by checking that intermediate build stages show CACHED in buildx output'
+docs:
+  - url: 'https://docs.docker.com/build/cache/backends/gha/'
+    label: 'Docker BuildKit — GitHub Actions cache backend'
+  - url: 'https://github.com/docker/build-push-action#cache'
+    label: 'docker/build-push-action — Cache inputs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy'
+    label: 'GitHub Actions — Cache usage limits and eviction policy'

package/errors/concurrency-timing/event-number-empty-on-push-collapses-concurrency.yml

@@ -0,0 +1,90 @@
+id: concurrency-timing-042
+title: "github.event.number empty on push events collapses concurrency group across all branches"
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - github-event-number
+  - push-event
+  - cancel-in-progress
+  - cross-branch
+  - pull-request
+patterns:
+  - regex: 'github\.event\.number\b'
+    flags: 'i'
+error_messages:
+  - "Run was cancelled due to concurrency group collision between push events on different branches"
+  - "Unexpected cancellation of push workflow by unrelated branch push"
+root_cause: |
+  `github.event.number` contains the pull request or issue number for events that have one
+  (e.g., `pull_request`, `pull_request_review`, `issue_comment`). On `push` events,
+  `github.event.number` is undefined and evaluates to an empty string in expressions.
+
+  When a workflow is triggered by both `push` and `pull_request` events, and the
+  concurrency group key uses `github.event.number`, all push-triggered runs share a
+  single concurrency group key (the suffix becomes empty):
+
+    group: "${{ github.workflow }}-${{ github.event.number }}"
+    # PR run:   "CI-123"   (unique per PR number)
+    # Push run: "CI-"      (ALL branch pushes share this single group!)
+
+  With `cancel-in-progress: true`, pushing to any branch cancels all other in-progress
+  push runs — even if they are on completely different branches. Developers intend to
+  serialize CI per PR but instead unintentionally cancel unrelated branch pushes.
+fix: |
+  Use the `||` operator to fall back to `github.ref` when `github.event.number` is empty.
+  `github.ref` is always populated (e.g., `refs/heads/main`, `refs/pull/123/merge`) and
+  produces a unique key per branch or PR.
+
+  Alternatively, use `github.event.number || github.sha` if you want push runs to each
+  be independent (no cancellation between pushes) while still serializing per PR.
+fix_code:
+  - language: yaml
+    label: "Wrong — all push runs share the same concurrency group key"
+    code: |
+      on:
+        push:
+          branches: [main, 'feature/**']
+        pull_request:
+
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.event.number }}
+        # On push: group = "CI-"  (empty number → all pushes share one group)
+        # On PR:   group = "CI-123" (unique per PR)
+        cancel-in-progress: true
+  - language: yaml
+    label: "Correct — fall back to github.ref so push runs are keyed per branch"
+    code: |
+      on:
+        push:
+          branches: [main, 'feature/**']
+        pull_request:
+
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.event.number || github.ref }}
+        # On push: group = "CI-refs/heads/main" (unique per branch)
+        # On PR:   group = "CI-123" (unique per PR number)
+        cancel-in-progress: true
+  - language: yaml
+    label: "Alternative — use github.ref for both triggers (no per-PR serialization)"
+    code: |
+      on:
+        push:
+          branches: [main, 'feature/**']
+        pull_request:
+
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        # On push: group = "CI-refs/heads/main"
+        # On PR:   group = "CI-refs/pull/123/merge"
+        cancel-in-progress: true
+prevention:
+  - "Always test concurrency group keys against all event types in the on: block"
+  - "Use github.event.number || github.ref as a safe pattern for mixed push/PR workflows"
+  - "Check that github.event.number is not undefined by printing it in a debug step when first setting up concurrency"
+  - "Prefer github.ref or github.ref_name as the base concurrency discriminator for branch-level serialization"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idconcurrency"
+    label: "Workflow syntax: concurrency"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context"
+    label: "GitHub context — github.event.number availability by event type"

package/errors/concurrency-timing/schedule-cron-no-concurrency-run-overlap.yml

@@ -0,0 +1,87 @@
+id: concurrency-timing-043
+title: 'Scheduled cron jobs overlap when no concurrency group is configured'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - schedule
+  - cron
+  - overlap
+  - race-condition
+  - concurrency
+  - data-corruption
+patterns:
+  - regex: 'on:\s*schedule'
+    flags: 'i'
+  - regex: 'triggered by:\s*schedule'
+    flags: 'i'
+error_messages:
+  - 'Multiple workflow runs triggered by schedule are running concurrently'
+  - 'triggered by: schedule'
+root_cause: |
+  When a scheduled workflow has no concurrency group configured, GitHub Actions
+  starts a new run at each scheduled time regardless of whether a previous run is
+  still in progress. Two conditions make this especially common:
+
+  1. The job takes longer than the cron interval (e.g., a 10-minute job on a
+     every-5-minute schedule).
+  2. GitHub's scheduler fires queued runs in rapid succession after a platform
+     outage or maintenance window, catching up on missed intervals.
+
+  Both scenarios result in multiple simultaneous runs sharing external resources—
+  databases, S3 buckets, deployment targets, or branch state—causing race
+  conditions, duplicate data writes, and data corruption. No error is surfaced
+  in the workflow logs; the runs both appear green while the downstream system
+  silently degrades.
+fix: |
+  Add a concurrency group to the scheduled workflow. The correct cancel-in-progress
+  value depends on whether the job is idempotent:
+
+  - Non-idempotent jobs (database migrations, state mutations): set
+    cancel-in-progress: false to queue runs sequentially.
+  - Idempotent jobs (report generation, cache refreshes): set
+    cancel-in-progress: true to drop stale queued runs and keep only the latest.
+fix_code:
+  - language: yaml
+    label: 'Queue scheduled runs for non-idempotent jobs (e.g., database migrations)'
+    code: |
+      on:
+        schedule:
+          - cron: '*/5 * * * *'
+
+      concurrency:
+        group: ${{ github.workflow }}-scheduled
+        cancel-in-progress: false
+
+      jobs:
+        migrate:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./scripts/db-migrate.sh
+  - language: yaml
+    label: 'Cancel stale runs for idempotent jobs (e.g., report generation)'
+    code: |
+      on:
+        schedule:
+          - cron: '*/5 * * * *'
+
+      concurrency:
+        group: ${{ github.workflow }}-scheduled
+        cancel-in-progress: true
+
+      jobs:
+        report:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./scripts/generate-report.sh
+prevention:
+  - 'Add a concurrency group to every workflow with an on.schedule trigger'
+  - 'For jobs longer than the cron interval, always use cancel-in-progress: false to serialize execution'
+  - 'Monitor the Actions tab for multiple simultaneous scheduled runs as an early warning sign'
+  - 'Use actionlint to audit workflows that have on.schedule but no concurrency group'
+docs:
+  - url: 'https://docs.github.com/en/actions/using-jobs/using-concurrency'
+    label: 'GitHub Actions — Using concurrency'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule'
+    label: 'GitHub Actions — Schedule event'

package/errors/known-unsolved/workflow-dispatch-api-no-run-id-in-response.yml

@@ -0,0 +1,101 @@
+id: known-unsolved-050
+title: "workflow_dispatch REST API dispatch returns 204 No Content — triggered run_id unavailable"
+category: known-unsolved
+severity: limitation
+tags:
+  - workflow_dispatch
+  - rest-api
+  - run-id
+  - polling
+  - automation
+  - cd-pipeline
+patterns:
+  - regex: 'POST.*dispatches.*204|dispatches.*No Content'
+    flags: 'i'
+error_messages:
+  - "204 No Content"
+  - "Unable to correlate triggered workflow run"
+  - "no run_id in dispatch response"
+root_cause: |
+  The GitHub Actions REST API endpoint
+  `POST /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches`
+  always returns HTTP 204 No Content on success — there is no run_id or any identifier
+  in the response body. GitHub creates the workflow run asynchronously after the API call
+  returns, so the run may not exist in the system for several seconds. There is no built-in
+  way to correlate a `workflow_dispatch` API call to the resulting run_id.
+
+  This is a persistent limitation reported since 2020 on the GitHub feedback forum with
+  thousands of upvotes. Developers building CD pipelines that need to trigger a workflow
+  and then monitor or gate on its result are forced to use fragile polling heuristics.
+fix: |
+  No direct fix — this is a GitHub platform limitation. Use one of these workarounds:
+
+  1. **Inject a correlation ID via inputs**: Pass a unique value (e.g., UUID) as a
+     `workflow_dispatch` input. After dispatch, poll `GET /repos/.../actions/runs?event=workflow_dispatch&branch=<branch>`
+     and match runs whose `inputs` contain the correlation ID.
+
+  2. **Use workflow_run event callback**: Design the triggered workflow to complete and
+     then fire a `workflow_run` event that your orchestrating workflow listens for.
+
+  3. **Switch to repository_dispatch**: `repository_dispatch` with a unique `client_payload`
+     field lets you include a correlation ID. The triggered workflow can write it to an artifact
+     or output for later retrieval.
+
+  4. **Third-party action**: Use `peter-evans/workflow-dispatch@v3` which implements polling
+     heuristics to approximate the run_id after dispatch.
+fix_code:
+  - language: yaml
+    label: "Inject correlation ID via workflow_dispatch input — then poll to find run"
+    code: |
+      # Triggering workflow or script passes a unique correlation ID:
+      # POST /repos/{owner}/{repo}/actions/workflows/deploy.yml/dispatches
+      # { "ref": "main", "inputs": { "correlation_id": "abc-123-uuid" } }
+
+      # Triggered workflow (deploy.yml) writes ID to output artifact:
+      on:
+        workflow_dispatch:
+          inputs:
+            correlation_id:
+              description: 'Unique ID for run correlation'
+              required: false
+              default: ''
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "run_id=${{ github.run_id }}" >> correlation.txt
+            - uses: actions/upload-artifact@v4
+              with:
+                name: correlation-${{ inputs.correlation_id }}
+                path: correlation.txt
+  - language: yaml
+    label: "Use repository_dispatch with client_payload for reliable correlation"
+    code: |
+      # Trigger with unique client_payload via API:
+      # POST /repos/{owner}/{repo}/dispatches
+      # { "event_type": "deploy", "client_payload": { "job_id": "build-789" } }
+
+      on:
+        repository_dispatch:
+          types: [deploy]
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - run: |
+                echo "Triggered by job: ${{ github.event.client_payload.job_id }}"
+                echo "This run ID: ${{ github.run_id }}"
+prevention:
+  - "Design CD pipelines using workflow_run event callbacks instead of polling after dispatch"
+  - "Include a unique correlation_id input in all workflow_dispatch-triggered workflows"
+  - "Track the GitHub public roadmap — run_id in dispatch response is a long-requested feature"
+  - "Consider repository_dispatch for machine-to-machine triggers needing reliable correlation"
+docs:
+  - url: "https://docs.github.com/en/rest/actions/workflows?apiVersion=2022-11-28#create-a-workflow-dispatch-event"
+    label: "REST API: Create a workflow dispatch event (returns 204 No Content)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run"
+    label: "workflow_run event — callback pattern for monitoring triggered workflows"
+  - url: "https://github.com/peter-evans/workflow-dispatch"
+    label: "peter-evans/workflow-dispatch — community action with polling heuristics"

package/errors/permissions-auth/github-token-no-cross-org-private-action-access.yml

@@ -0,0 +1,95 @@
+id: permissions-auth-049
+title: 'GITHUB_TOKEN cannot resolve private actions from a different organization'
+category: permissions-auth
+severity: error
+tags:
+  - github-token
+  - cross-org
+  - private-action
+  - enterprise
+  - repository-not-found
+patterns:
+  - regex: 'Unable to resolve action .* repository not found'
+    flags: 'i'
+  - regex: 'Error: Unable to resolve action `[^`]+`'
+    flags: 'i'
+  - regex: 'remote: Repository not found'
+    flags: 'i'
+error_messages:
+  - "Error: Unable to resolve action `other-org/private-action@v1`, repository not found."
+  - "Error: remote: Repository not found."
+  - "fatal: repository 'https://github.com/other-org/private-action/' not found"
+root_cause: |
+  GITHUB_TOKEN is automatically scoped to the repository where the workflow runs.
+  It cannot authenticate against repositories in a different GitHub organization,
+  even when both organizations are in the same GitHub Enterprise instance.
+
+  When a workflow references a private action from a different org
+  (e.g., uses: other-org/my-action@v1), the Actions runner attempts to clone
+  that action repository during the job setup phase using GITHUB_TOKEN. The
+  clone fails with "repository not found" because the token has no cross-org
+  read access. This is not a permissions: block misconfiguration — no amount of
+  permissions granted in the workflow YAML will fix it, since the token is
+  fundamentally scoped to the calling org.
+
+  This also affects actions/checkout when checking out code from a private repo
+  in another org unless a suitable alternative token is provided.
+fix: |
+  Choose the appropriate strategy based on your setup:
+
+  1. Make the action repository public — simplest if the action contains no secrets.
+  2. Vendor the action into your organization — copy the action code into a repo
+     in the same org or into .github/actions/ in the calling repo and reference it
+     as a local path action.
+  3. Use a GitHub App installation token with cross-org permissions for
+     actions/checkout calls to cross-org repos (does NOT fix job-level uses: loading).
+  4. Use a Personal Access Token (PAT) with access to both orgs for checkout
+     (same limitation: cannot fix uses: loading, only checkout steps).
+
+  Note: The uses: field at the job-steps level (for external actions) is resolved
+  before the workflow starts executing, so token injection via steps is not possible
+  for the action loading stage — vendoring or making the action public is the only
+  reliable fix for job-level uses:.
+fix_code:
+  - language: yaml
+    label: 'Vendor private action as a local path action'
+    code: |
+      # Copy the action code to .github/actions/my-action/ in your repo.
+      # Then reference it as a local action — no cross-org token required:
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: ./.github/actions/my-action
+              with:
+                param: value
+  - language: yaml
+    label: 'Use GitHub App token for cross-org repository checkout (not uses: loading)'
+    code: |
+      jobs:
+        cross-org-checkout:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/create-github-app-token@v2
+              id: app-token
+              with:
+                app-id: ${{ vars.APP_ID }}
+                private-key: ${{ secrets.APP_PRIVATE_KEY }}
+                owner: other-org
+            - uses: actions/checkout@v4
+              with:
+                repository: other-org/private-repo
+                token: ${{ steps.app-token.outputs.token }}
+prevention:
+  - 'Prefer public actions for shared tooling to avoid cross-org token scope issues'
+  - 'Vendor private cross-org actions into .github/actions/ in the calling repo'
+  - 'Create an internal shared-actions org accessible to all teams where GITHUB_TOKEN works'
+  - 'Document which repos depend on cross-org private actions and track them for access reviews'
+docs:
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token'
+    label: 'GitHub Actions — Automatic token authentication permissions'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/creating-actions/sharing-actions-and-workflows-with-your-organization'
+    label: 'GitHub Actions — Sharing actions with your organization'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsuses'
+    label: 'GitHub Actions — Workflow syntax for uses'

package/errors/silent-failures/skipped-step-job-output-silently-empty.yml

@@ -0,0 +1,119 @@
+id: silent-failures-078
+title: "Skipped step leaves job-level outputs: silently empty — downstream jobs receive empty string"
+category: silent-failures
+severity: silent-failure
+tags:
+  - job-outputs
+  - skipped-step
+  - outputs
+  - if-condition
+  - conditional
+  - downstream-jobs
+patterns:
+  - regex: 'steps\.[a-z_][a-z0-9_-]*\.outputs\.[a-z_]'
+    flags: 'i'
+error_messages:
+  - "needs.<job>.outputs.<key> is empty string when producing step was skipped"
+  - "Job output silently empty — step that writes output was conditionally skipped"
+root_cause: |
+  A job's `outputs:` block maps keys to values using `${{ steps.<id>.outputs.<key> }}`
+  expressions. These expressions are evaluated at the end of the job, after all steps have
+  run. If the step referenced in the output mapping is skipped (due to an `if:` condition
+  evaluating to false), the step never runs and never writes to `$GITHUB_OUTPUT`. The
+  output expression evaluates to an empty string with no warning.
+
+  Downstream jobs that depend on this output via `needs.<job>.outputs.<key>` receive an
+  empty string and continue running without error. This silent empty propagation causes
+  incorrect behavior: deploy jobs receiving an empty version string, notification jobs
+  receiving an empty status, or matrix jobs receiving an empty configuration list.
+
+  This is distinct from the `skipped-job-outputs-empty-string` limitation (where the
+  entire job is skipped) — here the job itself runs successfully, but one or more of its
+  steps are conditionally skipped.
+fix: |
+  Ensure the step that writes the output always runs, or provide a fallback value.
+  Use `if: always()` on the step if it should run regardless of prior step results.
+  Use a separate step to set a default/fallback output for the skipped case.
+  Alternatively, restructure the workflow so that the output-producing step is never
+  guarded by a condition that might prevent it from running.
+fix_code:
+  - language: yaml
+    label: "Wrong — output step conditionally skipped, downstream sees empty string"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            version: ${{ steps.get-version.outputs.version }}
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Get version (only on tags)
+              id: get-version
+              if: startsWith(github.ref, 'refs/tags/')   # skipped on branch pushes!
+              run: echo "version=${GITHUB_REF_NAME}" >> $GITHUB_OUTPUT
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - run: |
+                echo "Deploying version: ${{ needs.build.outputs.version }}"
+                # On branch push: prints "Deploying version: " (empty — step was skipped)
+  - language: yaml
+    label: "Correct — provide a fallback step to always set the output"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            version: ${{ steps.get-version.outputs.version }}
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Get version from tag
+              id: get-version
+              run: |
+                if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+                  echo "version=${GITHUB_REF_NAME}" >> $GITHUB_OUTPUT
+                else
+                  echo "version=dev-${GITHUB_SHA::8}" >> $GITHUB_OUTPUT
+                fi
+              # Always runs — handles both tag and branch pushes
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying version ${{ needs.build.outputs.version }}"
+  - language: yaml
+    label: "Alternative — gate deploy job to only run when version is set"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            version: ${{ steps.get-version.outputs.version }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Get version (only on tags)
+              id: get-version
+              if: startsWith(github.ref, 'refs/tags/')
+              run: echo "version=${GITHUB_REF_NAME}" >> $GITHUB_OUTPUT
+
+        deploy:
+          needs: build
+          if: needs.build.outputs.version != ''   # only run when version was set
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying ${{ needs.build.outputs.version }}"
+prevention:
+  - "Audit all job outputs: blocks — for each step reference, verify it always runs"
+  - "Avoid conditional if: guards on steps that produce job-level outputs unless a fallback step provides the same output key"
+  - "Add an explicit check step at the end of each job that validates required outputs are non-empty"
+  - "Use actionlint — it warns when output-producing steps have if: conditions that may skip them"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs"
+    label: "Passing information between jobs — job outputs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows"
+    label: "Events that trigger workflows — job outputs with conditional steps"

package/errors/triggers/schedule-paths-filter-silently-ignored.yml

@@ -0,0 +1,111 @@
+id: triggers-058
+title: "on.schedule ignores paths: filter — scheduled workflows always run"
+category: triggers
+severity: silent-failure
+tags:
+  - schedule
+  - paths
+  - cron
+  - trigger
+  - filter
+  - paths-ignore
+patterns:
+  - regex: 'schedule.*paths:|paths:.*cron:'
+    flags: 'si'
+error_messages:
+  - "Scheduled workflow runs even when no matching files changed"
+  - "paths: filter has no effect on scheduled events"
+root_cause: |
+  The `paths:` and `paths-ignore:` filters are only evaluated for `push` and `pull_request`
+  events, where GitHub can compare the changed files in the triggering commit against the
+  filter patterns. `on.schedule` events are time-based and have no associated commit or
+  changeset — there are no paths to compare. GitHub silently ignores any `paths:` or
+  `paths-ignore:` configuration placed under a `schedule:` trigger.
+
+  This commonly happens when a developer copies a `push:` trigger block that includes
+  `paths:` filtering and applies it to a `schedule:` block expecting the same filtering
+  behavior. The workflow runs on every scheduled interval regardless of what files have
+  changed. The `paths:` keys are not flagged as invalid — they are simply ignored without
+  any warning in the workflow or run logs.
+fix: |
+  Remove `paths:` and `paths-ignore:` from `on.schedule:` blocks — they have no effect.
+
+  If you need the scheduled workflow to skip execution when certain conditions are not
+  met, implement gate logic inside the workflow:
+
+  - Use an early job that checks file modification times or an external flag and sets
+    an output. Downstream jobs use `if: needs.check.outputs.should_run == 'true'`.
+  - Use the `dorny/paths-filter` action to detect file changes since a known reference
+    (e.g., the last successful run's commit SHA stored in a cache or artifact).
+  - If the schedule purpose is unrelated to file changes (e.g., dependency audits,
+    health checks), no conditional gate is needed — let it run on schedule.
+fix_code:
+  - language: yaml
+    label: "Wrong — paths: under schedule: is silently ignored"
+    code: |
+      on:
+        schedule:
+          - cron: '0 2 * * *'
+        paths:               # silently ignored — schedule always runs
+          - 'src/**'
+          - 'package.json'
+        push:
+          branches: [main]
+          paths:             # this paths: applies only to the push: trigger
+            - 'src/**'
+            - 'package.json'
+  - language: yaml
+    label: "Correct — paths: filter on push only; schedule unconditional or gated in-workflow"
+    code: |
+      on:
+        schedule:
+          - cron: '0 2 * * *'    # no paths: here — schedule always runs
+        push:
+          branches: [main]
+          paths:                  # paths: filter applies to push trigger only
+            - 'src/**'
+            - 'package.json'
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm run build
+
+      # To conditionally skip a scheduled run, use an in-workflow gate:
+      # jobs:
+      #   check-changes:
+      #     runs-on: ubuntu-latest
+      #     outputs:
+      #       changed: ${{ steps.filter.outputs.src }}
+      #     steps:
+      #       - uses: actions/checkout@v4
+      #         with:
+      #           fetch-depth: 2
+      #       - uses: dorny/paths-filter@v3
+      #         id: filter
+      #         with:
+      #           filters: |
+      #             src:
+      #               - 'src/**'
+      #
+      #   build:
+      #     needs: check-changes
+      #     if: needs.check-changes.outputs.changed == 'true' || github.event_name == 'push'
+      #     runs-on: ubuntu-latest
+      #     steps:
+      #       - uses: actions/checkout@v4
+      #       - run: npm run build
+prevention:
+  - "Only use paths: and paths-ignore: under push: and pull_request: trigger blocks"
+  - "Verify which filters apply to which events using the GitHub Actions syntax reference"
+  - "actionlint reports a warning when paths: is used under schedule: — run it in CI"
+  - "For scheduled conditional logic, gate using job if: conditions on in-workflow checks"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpaths"
+    label: "Workflow syntax: paths filter (applies to push and pull_request only)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule"
+    label: "Events that trigger workflows: schedule"
+  - url: "https://github.com/dorny/paths-filter"
+    label: "dorny/paths-filter — detect file changes inside a scheduled workflow"

package/errors/yaml-syntax/step-output-boolean-string-coercion-if-condition.yml

@@ -0,0 +1,100 @@
+id: yaml-syntax-053
+title: 'Step output boolean string coercion — comparing to bare true/false silently never matches'
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - step-outputs
+  - GITHUB_OUTPUT
+  - boolean
+  - string-coercion
+  - if-condition
+  - silent-failure
+patterns:
+  - regex: 'outputs\.[a-z_][a-z0-9_]*\s*==\s*true\b'
+    flags: 'i'
+  - regex: 'outputs\.[a-z_][a-z0-9_]*\s*==\s*false\b'
+    flags: 'i'
+  - regex: 'needs\.[a-z_][a-z0-9_-]*\.outputs\.[a-z_]+ ==\s*(true|false)\b'
+    flags: 'i'
+error_messages:
+  - "if: steps.check.outputs.changed == true"
+  - "if: needs.build.outputs.has_changes == false"
+  - "if: steps.detect.outputs.skip == true"
+root_cause: |
+  All values written to GITHUB_OUTPUT (via echo "key=value" >> $GITHUB_OUTPUT) are
+  stored and transmitted as strings, regardless of the intended type. When a step
+  outputs a boolean-like value such as echo "changed=true" >> $GITHUB_OUTPUT, the
+  output steps.id.outputs.changed is the string 'true', not the boolean true.
+
+  In GitHub Actions expression syntax, type comparison is strict:
+  - 'true' == true  → false  (string 'true' does not equal boolean true)
+  - 'false' == false → false  (string 'false' does not equal boolean false)
+  - '' == false → true  (empty string does equal boolean false — a separate gotcha)
+
+  This means if: steps.check.outputs.changed == true silently evaluates to false
+  even when the output is the string "true", and the step is silently skipped with
+  no error. The workflow log shows the step as skipped with no indication that the
+  condition evaluation was the cause.
+
+  The same pattern applies to job outputs (needs.job.outputs.flag) passed between
+  jobs via the outputs: block.
+fix: |
+  Always compare step and job outputs as strings using single-quoted string literals:
+  - For true check:  == 'true'
+  - For false check: != 'true'  (preferred over == 'false' because empty string also needs handling)
+  - For numeric outputs: use fromJSON() to parse before arithmetic comparison
+
+  For boolean output authors: document that consumers must compare as strings, or
+  use '1'/'0' string conventions to make the string nature explicit.
+fix_code:
+  - language: yaml
+    label: 'Correct: compare step outputs as strings'
+    code: |
+      steps:
+        - id: check
+          run: echo "changed=true" >> $GITHUB_OUTPUT
+
+        # WRONG — silently skipped because 'true' != true (string != boolean)
+        # - if: steps.check.outputs.changed == true
+        #   run: echo "This never runs"
+
+        # CORRECT — compare output string to string literal
+        - if: steps.check.outputs.changed == 'true'
+          run: echo "Files changed, running deploy"
+
+        # CORRECT — inverse check
+        - if: steps.check.outputs.changed != 'true'
+          run: echo "No changes, skipping deploy"
+  - language: yaml
+    label: 'Job-to-job boolean output — compare as string in downstream job'
+    code: |
+      jobs:
+        detect:
+          outputs:
+            has_changes: ${{ steps.diff.outputs.has_changes }}
+          runs-on: ubuntu-latest
+          steps:
+            - id: diff
+              run: |
+                # Output is always a string
+                echo "has_changes=true" >> $GITHUB_OUTPUT
+
+        deploy:
+          needs: detect
+          # CORRECT: compare job output as string literal
+          if: needs.detect.outputs.has_changes == 'true'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying"
+prevention:
+  - "Always use single-quoted string literals in if: conditions when comparing step or job outputs: == 'true' not == true"
+  - 'Use fromJSON() to parse numeric step outputs before arithmetic or numeric comparisons'
+  - 'Audit workflows for bare == true or == false comparisons on steps.*.outputs.* and needs.*.outputs.*'
+  - 'Use actionlint — it detects type mismatches in expression comparisons involving outputs'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs'
+    label: 'GitHub Actions — Passing information between jobs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#literals'
+    label: 'GitHub Actions — Expression literals and type coercion'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/setting-an-output-parameter'
+    label: 'GitHub Actions — Setting an output parameter'

package/package.json

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