@htekdev/actions-debugger 1.0.94 → 1.0.96

package/errors/caching-artifacts/caching-artifacts-052.yml

@@ -0,0 +1,107 @@
+id: caching-artifacts-052
+title: '`download-artifact@v4` `name:` Does Not Support Glob Patterns — Use `pattern:` Instead'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - download-artifact
+  - v4-breaking-change
+  - glob
+  - pattern
+  - migration
+  - artifact-download
+patterns:
+  - regex: 'download-artifact@v4|download-artifact@v3.*name.*\*'
+    flags: 'i'
+  - regex: 'name\s*:\s*[''"][^''"]*\*[^''"]*[''"]'
+    flags: 'i'
+error_messages:
+  - "No artifacts found with the provided name"
+  - "Error: Unable to find any artifacts for the associated workflow"
+  - "Unable to find artifact 'my-*-artifact'"
+root_cause: |
+  In `actions/download-artifact@v3`, the `name:` input accepted glob patterns
+  (e.g., `name: 'build-*'`) and would download all matching artifacts.
+  In `actions/download-artifact@v4` this behavior changed: `name:` now requires
+  an EXACT artifact name match. Glob characters in `name:` are treated as
+  literal characters, so `name: 'build-*'` looks for an artifact literally
+  named `build-*`, finds none, and either errors or silently downloads nothing
+  depending on the `error-no-files-found` setting.
+
+  The `pattern:` input was introduced in v4 as the replacement for glob-based
+  artifact selection. Migrating from v3 to v4 requires moving glob expressions
+  from `name:` to `pattern:`.
+
+  This silently impacts workflows that:
+  - Download multiple build artifacts from matrix jobs using a shared prefix
+  - Use wildcards to grab all artifacts from a set of parallel jobs
+  - Were migrated to v4 without reading the full migration guide
+fix: |
+  Replace glob patterns in `name:` with the `pattern:` input in
+  `actions/download-artifact@v4`. The `name:` input should only be used
+  when downloading a single artifact by its exact name.
+
+  When using `pattern:`, the action also has a `merge-multiple` option
+  that controls whether matched artifacts are merged into one directory
+  or placed in separate subdirectories.
+fix_code:
+  - language: yaml
+    label: "WRONG — glob in name: silently matches nothing in v4"
+    code: |
+      steps:
+        - uses: actions/download-artifact@v4
+          with:
+            name: 'build-*'      # ❌ globs not supported in name: for v4
+            path: ./artifacts
+  - language: yaml
+    label: "RIGHT — use pattern: for glob matching in v4"
+    code: |
+      steps:
+        - uses: actions/download-artifact@v4
+          with:
+            pattern: 'build-*'   # ✅ use pattern: for glob matching
+            path: ./artifacts
+            merge-multiple: true # flatten into single directory
+  - language: yaml
+    label: "RIGHT — download exact artifact by name in v4"
+    code: |
+      steps:
+        - uses: actions/download-artifact@v4
+          with:
+            name: build-linux-amd64   # ✅ exact name, no glob needed
+            path: ./dist/linux
+  - language: yaml
+    label: "Matrix upload + glob download pattern"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              os: [linux, windows, macos]
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/upload-artifact@v4
+              with:
+                name: build-${{ matrix.os }}   # distinct name per job
+                path: ./dist/
+
+        package:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                pattern: 'build-*'      # ✅ downloads all build-* artifacts
+                path: ./all-builds
+                merge-multiple: false   # keep per-artifact subdirectories
+prevention:
+  - "When migrating from download-artifact@v3 to @v4, audit all `name:` inputs for glob characters and move them to `pattern:`."
+  - "Use `name:` only for exact single-artifact downloads; use `pattern:` for any glob or multi-artifact download."
+  - "Set `error-no-files-found: error` to fail fast when no artifacts match, exposing glob issues early."
+  - "Review the download-artifact v4 migration guide before updating the action version."
+docs:
+  - url: "https://github.com/actions/download-artifact/blob/main/docs/MIGRATION.md"
+    label: "download-artifact v4 migration guide"
+  - url: "https://github.com/actions/download-artifact#inputs"
+    label: "download-artifact — inputs reference (pattern vs name)"
+  - url: "https://github.com/actions/toolkit/releases/tag/%40actions%2Fartifact%402.0.0"
+    label: "actions/toolkit v2 — artifact v2 API underlying v4 action"

package/errors/caching-artifacts/caching-artifacts-053.yml

@@ -0,0 +1,90 @@
+id: caching-artifacts-053
+title: "download-artifact@v4 finds no artifacts in workflow_run context without run-id"
+category: caching-artifacts
+severity: error
+tags:
+  - download-artifact
+  - workflow_run
+  - run-id
+  - cross-workflow
+  - artifact
+patterns:
+  - regex: 'No artifacts found'
+    flags: 'i'
+  - regex: 'Unable to find any artifacts for the associated workflow'
+    flags: 'i'
+error_messages:
+  - "No artifacts found for the associated workflow run"
+  - "Unable to find any artifacts for the associated workflow"
+  - "Error: Unable to find any artifacts for the associated workflow run"
+root_cause: |
+  `actions/download-artifact@v4` defaults to downloading artifacts from the
+  CURRENT workflow run (`github.run_id`). In a `workflow_run`-triggered
+  workflow, the current run is the downstream (deploy) workflow — which has
+  produced no artifacts. The upstream (build) workflow's artifacts belong to
+  the triggering run, identified by `github.event.workflow_run.id`.
+
+  Without setting `run-id: ${{ github.event.workflow_run.id }}`, the download
+  step searches the current run's artifacts, finds nothing, and either fails
+  with "No artifacts found" or silently exits (depending on `if-no-files-found`
+  setting). No artifact was ever associated with the downstream run, so the
+  error can be confusing — the artifact clearly exists in the Actions UI under
+  the upstream run.
+
+  This is a distinct issue from the cross-run permissions error (ca-040):
+  that occurs when `run-id` IS set but `actions: read` permission is missing.
+  This issue occurs when `run-id` is simply not set at all.
+fix: |
+  Set `run-id: ${{ github.event.workflow_run.id }}` on the download step to
+  target the triggering workflow's run. Also provide `github-token` (required
+  for cross-run downloads) and ensure `actions: read` permission is set.
+fix_code:
+  - language: yaml
+    label: "Correct: set run-id from triggering workflow in workflow_run context"
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+
+      permissions:
+        actions: read
+        contents: read
+
+      jobs:
+        deploy:
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - name: Download build artifacts
+              uses: actions/download-artifact@v4
+              with:
+                name: build-output
+                # Required: point to the upstream run, not the current run
+                run-id: ${{ github.event.workflow_run.id }}
+                github-token: ${{ secrets.GITHUB_TOKEN }}
+
+            - name: Deploy
+              run: echo "Deploying from artifact"
+  - language: yaml
+    label: "Incorrect: missing run-id causes 'No artifacts found'"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Download build artifacts
+              uses: actions/download-artifact@v4
+              with:
+                name: build-output
+                # Missing run-id — searches the CURRENT run, which has no artifacts
+prevention:
+  - "In any `workflow_run`-triggered workflow, always set `run-id: ${{ github.event.workflow_run.id }}`"
+  - "Pair with `github-token: ${{ secrets.GITHUB_TOKEN }}` and `permissions: actions: read`"
+  - "Verify artifacts exist under the triggering run via the Actions UI before debugging download steps"
+  - "Name artifacts consistently between upload (in CI) and download (in deploy) workflows"
+docs:
+  - url: "https://github.com/actions/download-artifact?tab=readme-ov-file#download-artifacts-from-other-workflow-runs-or-repositories"
+    label: "actions/download-artifact: Downloading from other workflow runs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run"
+    label: "GitHub Docs: workflow_run event"

package/errors/concurrency-timing/concurrency-timing-045.yml

@@ -0,0 +1,70 @@
+id: concurrency-timing-045
+title: "workflow_run-triggered workflows run concurrently — no upstream concurrency linkage"
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - workflow_run
+  - concurrency
+  - deployment
+  - build-deploy-pipeline
+  - downstream-workflow
+patterns:
+  - regex: 'on:\s+workflow_run:'
+    flags: 'si'
+error_messages:
+  - "Multiple deployments triggered simultaneously for the same branch"
+  - "Deploy workflow triggered concurrently"
+root_cause: |
+  Workflows triggered via `on: workflow_run:` do not inherit any concurrency
+  group from the triggering (upstream) workflow. If multiple upstream runs
+  complete in quick succession — for example, two commits pushed rapidly — each
+  `completed` event spawns an independent downstream run. All downstream runs
+  execute concurrently with no serialization or cancellation, even when the
+  upstream workflow had a concurrency group that serialized upstream runs.
+
+  The downstream workflow runs in the context of the default branch and receives
+  the triggering run's metadata via `github.event.workflow_run.*`, but GitHub
+  does not propagate any concurrency scope from upstream to downstream.
+
+  For build-then-deploy pipelines this creates a race condition: two deploy runs
+  may begin simultaneously, with whichever finishes last determining the final
+  deployed state regardless of commit order.
+fix: |
+  Add an explicit `concurrency:` block to the `workflow_run`-triggered workflow,
+  keyed on `github.event.workflow_run.head_branch` to scope per branch.
+
+  Use `cancel-in-progress: true` for idempotent deploys (only the latest commit
+  matters) or `cancel-in-progress: false` for non-idempotent operations that
+  must complete once queued.
+fix_code:
+  - language: yaml
+    label: "Add explicit concurrency group to workflow_run-triggered deploy workflow"
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+          branches: [main]
+
+      # Without this block, concurrent CI completions spawn concurrent deploys
+      concurrency:
+        group: deploy-${{ github.event.workflow_run.head_branch }}
+        cancel-in-progress: true
+
+      jobs:
+        deploy:
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy
+              run: echo "Deploying ${{ github.event.workflow_run.head_sha }}"
+prevention:
+  - "Always define an explicit `concurrency:` block in `workflow_run`-triggered workflows"
+  - "Key the concurrency group on `github.event.workflow_run.head_branch` to scope by branch"
+  - "For CI-to-deploy pipelines, use `cancel-in-progress: true` so only the latest commit deploys"
+  - "Consider consolidating CI and deploy into a single workflow using `needs:` if elevated permissions are not required"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run"
+    label: "GitHub Docs: workflow_run event"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/controlling-workflow-and-job-execution"
+    label: "GitHub Docs: Controlling workflow and job execution (concurrency)"

package/errors/known-unsolved/known-unsolved-053.yml

@@ -0,0 +1,114 @@
+id: known-unsolved-053
+title: '`workflow_dispatch` Has No Native Array or List Input Type — Must Serialize as JSON String'
+category: known-unsolved
+severity: limitation
+tags:
+  - workflow_dispatch
+  - inputs
+  - array
+  - list
+  - json
+  - limitation
+patterns:
+  - regex: 'workflow_dispatch.*inputs|inputs.*type\s*:\s*string.*array'
+    flags: 'im'
+  - regex: "fromJSON\\(.*inputs\\."
+    flags: 'i'
+error_messages:
+  - "Input type 'array' is not supported for workflow_dispatch"
+  - "Unexpected value 'array'"
+root_cause: |
+  GitHub Actions `workflow_dispatch` supports only five input types:
+  `string`, `boolean`, `choice`, `number`, and `environment`. There is no
+  native `array` or `list` type. Users who need to pass multiple values
+  (e.g., a list of services to deploy, a set of environments to target)
+  must serialize the array as a JSON string and parse it in the workflow.
+
+  This limitation affects:
+  - Manual dispatch with dynamic target lists
+  - CI/CD automation via the REST API (`POST /repos/.../actions/workflows/.../dispatches`)
+  - Reuse of workflow_dispatch workflows that naturally accept variable-length input
+  - Validation — no schema can prevent malformed JSON from being passed
+
+  A `type: array` schema was proposed in actions/runner#1844 (800+ reactions)
+  and remains one of the highest-voted open feature requests for GitHub Actions.
+fix: |
+  Serialize the array as a JSON string in the dispatch call and use
+  `fromJSON()` in the workflow to parse it into a matrix or loop variable.
+
+  Workarounds by use case:
+  1. **API dispatch**: Serialize to `'["a","b","c"]'` and use `fromJSON(inputs.targets)`
+  2. **UI dispatch**: Document the expected JSON format in the input description
+  3. **Choice type**: If the list is finite and known ahead of time, use
+     `type: choice` with predefined options instead
+  4. **Multiple boolean inputs**: For small fixed sets, use separate boolean
+     inputs per option (verbose but typed)
+fix_code:
+  - language: yaml
+    label: "Workaround — serialize array as JSON string, parse with fromJSON"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            services:
+              description: 'JSON array of services to deploy e.g. ["api","worker","ui"]'
+              required: true
+              type: string
+              default: '["api","worker"]'
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          strategy:
+            matrix:
+              service: ${{ fromJSON(inputs.services) }}
+          steps:
+            - run: echo "Deploying ${{ matrix.service }}"
+  - language: yaml
+    label: "Workaround — comma-separated string split in shell"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            environments:
+              description: 'Comma-separated environments e.g. staging,production'
+              required: true
+              type: string
+              default: 'staging'
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy to each environment
+              run: |
+                IFS=',' read -ra ENVS <<< "${{ inputs.environments }}"
+                for env in "${ENVS[@]}"; do
+                  echo "Deploying to: $env"
+                done
+  - language: yaml
+    label: "Alternative — use type: choice for known finite sets"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            target_env:
+              description: 'Target environment'
+              required: true
+              type: choice
+              options:
+                - staging
+                - production
+                - both
+prevention:
+  - "Document the expected JSON format in the input `description` field so UI dispatchers know the required syntax."
+  - "Add a validation step that runs `echo '${{ inputs.targets }}' | jq .` to fail fast on malformed JSON before processing."
+  - "Consider using `type: choice` with predefined options if the list is small and known at workflow-definition time."
+  - "For API-driven workflows, generate the JSON array programmatically and pass it as a string in the dispatch payload."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onworkflow_dispatchinputsinput_idtype"
+    label: "workflow_dispatch input types — supported values"
+  - url: "https://github.com/actions/runner/issues/1844"
+    label: "actions/runner #1844 — Support array inputs for workflow_dispatch (800+ reactions)"
+  - url: "https://docs.github.com/en/rest/actions/workflows#create-a-workflow-dispatch-event"
+    label: "REST API — Create a workflow dispatch event"

package/errors/permissions-auth/permissions-auth-053.yml

@@ -0,0 +1,103 @@
+id: permissions-auth-053
+title: 'GITHUB_TOKEN `packages: write` Cannot Delete Package Versions — Requires PAT with `delete:packages`'
+category: permissions-auth
+severity: error
+tags:
+  - packages
+  - github-token
+  - delete-packages
+  - container-registry
+  - package-cleanup
+  - permissions
+patterns:
+  - regex: 'Resource not accessible by integration'
+    flags: 'i'
+  - regex: 'DELETE.*packages.*versions|packages.*DELETE.*versions'
+    flags: 'i'
+  - regex: '403.*package|package.*403'
+    flags: 'i'
+error_messages:
+  - "Resource not accessible by integration"
+  - "403 Forbidden — DELETE https://api.github.com/user/packages/{type}/{name}/versions/{id}"
+  - "Error: Resource not accessible by integration (HTTP 403)"
+root_cause: |
+  The `packages: write` permission in `GITHUB_TOKEN` grants the ability to
+  publish and overwrite package versions but does NOT include the ability to
+  delete them. Package version deletion requires account-level permission
+  (`delete:packages` OAuth scope) that cannot be granted to an installation
+  token. The GitHub Packages REST API delete endpoint
+  (`DELETE /user/packages/{type}/{name}/versions/{id}` or the org equivalent)
+  validates the caller's account-level scope, which GITHUB_TOKEN—being a
+  repository-scoped installation token—can never satisfy regardless of the
+  `permissions: packages: write` declaration in the workflow.
+
+  This commonly surfaces in:
+  - Container image cleanup jobs that try to prune old tags/digests
+  - npm, Maven, or RubyGems package version retention workflows
+  - Automated housekeeping that uses `ghcr.io` image management actions
+fix: |
+  Store a fine-grained or classic PAT with `delete:packages` scope as a
+  repository secret (e.g., `PACKAGES_DELETE_TOKEN`) and use that token when
+  calling the Packages delete API or actions that delete package versions.
+
+  For GitHub Container Registry (ghcr.io) image pruning, use a PAT or a
+  GitHub App installation token with Packages write + admin scope. Pass it
+  as the `token:` input to the relevant cleanup action.
+fix_code:
+  - language: yaml
+    label: "WRONG — GITHUB_TOKEN cannot delete package versions (403)"
+    code: |
+      jobs:
+        cleanup:
+          runs-on: ubuntu-latest
+          permissions:
+            packages: write   # ❌ write permission does not grant delete
+          steps:
+            - name: Delete old package version
+              run: |
+                # This call will return 403 "Resource not accessible by integration"
+                VERSION_ID=12345
+                curl -X DELETE \
+                  -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
+                  https://api.github.com/user/packages/container/my-image/versions/$VERSION_ID
+  - language: yaml
+    label: "RIGHT — use a PAT with delete:packages scope"
+    code: |
+      jobs:
+        cleanup:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Delete old package version
+              env:
+                GH_TOKEN: ${{ secrets.PACKAGES_DELETE_TOKEN }}  # PAT with delete:packages
+              run: |
+                VERSION_ID=12345
+                curl -X DELETE \
+                  -H "Authorization: Bearer $GH_TOKEN" \
+                  https://api.github.com/user/packages/container/my-image/versions/$VERSION_ID
+  - language: yaml
+    label: "RIGHT — ghcr.io cleanup action with PAT"
+    code: |
+      jobs:
+        cleanup-images:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: snok/container-retention-policy@v3
+              with:
+                account: user
+                token: ${{ secrets.PACKAGES_DELETE_TOKEN }}  # PAT with delete:packages
+                image-names: my-image
+                cut-off: 7 days ago UTC
+                keep-n-most-recent: 5
+prevention:
+  - "Never assume `packages: write` is sufficient for full package lifecycle management — deletion is always PAT-only."
+  - "Create a dedicated PAT or GitHub App with `delete:packages` scope and store it as a secret for cleanup workflows."
+  - "Scope cleanup jobs separately from build jobs so the PAT is only used where deletion is needed."
+  - "Document in your workflow that PACKAGES_DELETE_TOKEN requires `delete:packages` scope so it is renewed with the right scopes."
+docs:
+  - url: "https://docs.github.com/en/rest/packages/packages#delete-a-package-version-for-a-user"
+    label: "REST API — Delete a package version for a user"
+  - url: "https://docs.github.com/en/packages/learn-github-packages/about-permissions-for-github-packages#about-scopes-and-permissions-for-package-registries"
+    label: "About permissions for GitHub Packages"
+  - url: "https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token"
+    label: "Creating a fine-grained PAT with delete:packages"

package/errors/permissions-auth/permissions-auth-054.yml

@@ -0,0 +1,99 @@
+id: permissions-auth-054
+title: "OIDC sub claim format changes when environment: block added — IdP trust policy breaks"
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - environment
+  - aws
+  - gcp
+  - azure
+  - sub-claim
+  - trust-policy
+  - deployment-protection
+patterns:
+  - regex: 'Not authorized to perform sts:AssumeRoleWithWebIdentity'
+    flags: 'i'
+  - regex: 'Error: Credentials could not be loaded'
+    flags: 'i'
+  - regex: 'Permission.*denied.*generateAccessToken|WorkloadIdentityPool.*rejected'
+    flags: 'i'
+error_messages:
+  - "Not authorized to perform sts:AssumeRoleWithWebIdentity"
+  - "Error: Credentials could not be loaded, please check your action inputs: Could not load credentials from any providers"
+  - "Permission 'iam.serviceAccounts.getOpenIdToken' denied on resource"
+  - "The provided token could not be validated"
+root_cause: |
+  GitHub Actions OIDC token `sub` (subject) claim format depends on whether the
+  job has an `environment:` key. Without an environment, the subject is:
+    `repo:OWNER/REPO:ref:refs/heads/BRANCH`
+
+  When `environment: production` is present on the job, the format changes to:
+    `repo:OWNER/REPO:environment:production`
+
+  The branch/ref component is replaced entirely by the environment name. AWS IAM
+  role trust policies, GCP Workload Identity Federation conditions, and Azure
+  federated credential filters that matched the branch-ref format now receive a
+  token with a different sub claim and reject the OIDC exchange with a 403 or
+  permission-denied error.
+
+  This commonly occurs when a team adds environment protection rules (required
+  reviewers, wait timers) to an existing workflow that already had OIDC
+  credentials working. CI passes before adding `environment:` but fails after.
+fix: |
+  Update the IdP trust policy to match the new subject format containing the
+  environment name. Options:
+  1. Narrow to environment: change the condition to match
+     `repo:OWNER/REPO:environment:production`.
+  2. Use a wildcard: match `repo:OWNER/REPO:*` to accept both formats (less secure).
+  3. GitHub subject claim customization (Enterprise): define a consistent sub
+     claim format that does not change based on environment presence.
+fix_code:
+  - language: yaml
+    label: "Workflow: annotate environment and required OIDC permissions"
+    code: |
+      permissions:
+        id-token: write
+        contents: read
+
+      jobs:
+        deploy:
+          # Adding this key changes the OIDC sub claim format — update IdP trust policy
+          environment: production
+          runs-on: ubuntu-latest
+          steps:
+            - uses: aws-actions/configure-aws-credentials@v4
+              with:
+                role-to-assume: arn:aws:iam::123456789012:role/DeployRole
+                aws-region: us-east-1
+                # AWS trust policy must now use:
+                # "token.actions.githubusercontent.com:sub":
+                #   "StringEquals": "repo:org/repo:environment:production"
+                # (not "repo:org/repo:ref:refs/heads/main")
+  - language: yaml
+    label: "AWS IAM trust policy: match environment sub claim"
+    code: |
+      # AWS IAM Role Trust Policy — update Condition after adding environment:
+      # Before (no environment):
+      #   "token.actions.githubusercontent.com:sub": "repo:org/repo:ref:refs/heads/main"
+      #
+      # After (with environment: production):
+      #   "token.actions.githubusercontent.com:sub": "repo:org/repo:environment:production"
+      #
+      # Wildcard to accept both (less restrictive):
+      #   "token.actions.githubusercontent.com:sub":
+      #     StringLike: "repo:org/repo:*"
+      #
+      # GCP: update attribute.repository_environment or use attribute mapping
+prevention:
+  - "Before adding `environment:` to a job using OIDC, audit and update all IdP trust policies"
+  - "Document the expected sub claim format in trust policy comments to avoid future confusion"
+  - "Use GitHub's OIDC token debugger step to inspect the actual sub claim at runtime"
+  - "For consistent sub format across environment and non-environment jobs, consider subject claim customization"
+docs:
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect#filtering-for-a-specific-environment"
+    label: "GitHub Docs: OIDC filtering for a specific environment"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-subject-claims-for-an-organization-or-repository"
+    label: "GitHub Docs: Customizing subject claims"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services"
+    label: "GitHub Docs: Configuring OIDC in AWS"

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

@@ -0,0 +1,120 @@
+id: silent-failures-087
+title: '`fail-fast: false` Does Not Prevent Downstream `needs:` Jobs From Being Skipped When Matrix Jobs Fail'
+category: silent-failures
+severity: silent-failure
+tags:
+  - matrix
+  - fail-fast
+  - needs
+  - downstream-job
+  - skipped
+  - strategy
+patterns:
+  - regex: 'fail-fast\s*:\s*false'
+    flags: 'i'
+  - regex: 'needs\s*:.*matrix|matrix.*needs\s*:'
+    flags: 'im'
+error_messages:
+  - "This job was skipped"
+  - "Job 'X' is skipped because all dependencies failed or were skipped"
+root_cause: |
+  `strategy.fail-fast: false` only prevents other MATRIX jobs from being
+  cancelled when one matrix job fails. It does NOT affect how downstream
+  jobs that `needs:` the matrix job handle the overall result.
+
+  When at least one matrix job fails (even with `fail-fast: false` allowing
+  all others to complete), the `needs.<matrix-job>.result` for the downstream
+  job evaluates to `'failure'`. A downstream job with a standard `needs:`
+  dependency is then SKIPPED — not because of `fail-fast`, but because its
+  dependency is in a failed state.
+
+  This surprises developers who add `fail-fast: false` expecting the entire
+  pipeline to continue running end-to-end. The final summary/report job
+  that needs the matrix job is silently skipped, producing no output.
+fix: |
+  Add `if: always()` to downstream jobs that should run regardless of matrix
+  outcome. Then explicitly check `needs.<job>.result` values to determine
+  pass/fail:
+
+  - `if: always()` ensures the job is never skipped due to upstream failure
+  - Check `contains(needs.*.result, 'failure')` to detect any matrix failure
+  - Use `needs.<job>.result == 'success'` for strict pass gates
+fix_code:
+  - language: yaml
+    label: "WRONG — summary job silently skipped when matrix job fails"
+    code: |
+      jobs:
+        test:
+          strategy:
+            fail-fast: false  # ❌ allows all matrix jobs to run, but...
+            matrix:
+              node: [18, 20, 22]
+          runs-on: ubuntu-latest
+          steps:
+            - run: npm test
+
+        summary:
+          needs: test           # ❌ still skipped if any matrix job failed
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "All tests done"
+  - language: yaml
+    label: "RIGHT — use if: always() and check result explicitly"
+    code: |
+      jobs:
+        test:
+          strategy:
+            fail-fast: false
+            matrix:
+              node: [18, 20, 22]
+          runs-on: ubuntu-latest
+          steps:
+            - run: npm test
+
+        summary:
+          needs: test
+          if: always()          # ✅ runs even when test jobs failed
+          runs-on: ubuntu-latest
+          steps:
+            - name: Check matrix results
+              if: contains(needs.test.result, 'failure')
+              run: |
+                echo "One or more matrix jobs failed"
+                exit 1
+            - name: Success
+              run: echo "All matrix jobs passed"
+  - language: yaml
+    label: "RIGHT — gate final deploy only when all matrix jobs pass"
+    code: |
+      jobs:
+        test:
+          strategy:
+            fail-fast: false
+            matrix:
+              node: [18, 20, 22]
+          runs-on: ubuntu-latest
+          outputs:
+            result: ${{ job.status }}
+          steps:
+            - run: npm test
+
+        deploy:
+          needs: test
+          if: always() && needs.test.result == 'success'  # ✅ explicit success check
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying"
+prevention:
+  - "Always add `if: always()` to aggregation/summary/deploy jobs that need to run after a matrix job."
+  - "Explicitly check `needs.<job>.result` or `contains(needs.*.result, 'failure')` rather than relying on implicit pass-through."
+  - "Understand that `fail-fast: false` is matrix-scoped — it does not change how the `needs:` graph handles failures."
+  - "Use job outputs combined with `if: always()` to build robust reporting jobs that capture all matrix outcomes."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-jobs-in-a-workflow#defining-prerequisite-jobs"
+    label: "Defining prerequisite jobs — needs context and result values"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategyfail-fast"
+    label: "workflow syntax — jobs.<job_id>.strategy.fail-fast"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#status-check-functions"
+    label: "Status check functions — always(), success(), failure()"
+  - url: "https://github.com/orgs/community/discussions/26822"
+    label: "GitHub Community — fail-fast: false but summary job still skipped"

package/errors/yaml-syntax/yaml-syntax-059.yml

@@ -0,0 +1,93 @@
+id: yaml-syntax-059
+title: "needs: key does not accept runtime expressions — must be static job IDs"
+category: yaml-syntax
+severity: error
+tags:
+  - needs
+  - expressions
+  - dynamic-jobs
+  - job-dependencies
+  - parse-time
+  - actionlint
+patterns:
+  - regex: "The pipeline is not valid.*needs|needs.*references.*job.*does not exist"
+    flags: 'i'
+  - regex: 'Unrecognized named-value.*steps.*in needs|needs.*invalid.*expression'
+    flags: 'i'
+error_messages:
+  - "The pipeline is not valid. Job 'deploy' needs 'steps' which does not exist"
+  - "Unrecognized named-value: 'steps'"
+  - "Job 'X' depends on unknown job '${{ fromJSON(...) }}'"
+  - "needs: field value '${{ ... }}' is not a valid job identifier"
+root_cause: |
+  The `needs:` key in a GitHub Actions job definition must contain static job ID
+  strings. It is evaluated at workflow parse time — before any step or job runs
+  — so runtime expressions such as `${{ steps.gen.outputs.jobs }}` or
+  `${{ fromJSON(env.DYNAMIC_JOBS) }}` are not evaluated. They are treated as
+  literal strings, and since no job with that literal name exists, GitHub reports
+  a validation error or the dependency is silently ignored.
+
+  This surprises developers who successfully use `fromJSON()` in `matrix:` or
+  `env:` blocks (which ARE expression-capable) and assume `needs:` works the
+  same way. The difference is that the job dependency graph must be fully
+  resolved before execution begins; expressions in `needs:` would create a
+  circular dependency at parse time.
+
+  actionlint statically detects this and reports: "needs: field cannot be
+  computed by a dynamic value. Use a literal value instead."
+fix: |
+  Job dependencies must be statically defined. Use one of these patterns:
+  1. List all potential dependent jobs statically; use `if:` conditions on
+     each downstream job to skip those not needed.
+  2. Use a matrix fan-out + fan-in pattern where the fan-in job has a single
+     static `needs:` on the matrix job name (not individual matrix legs).
+  3. Restructure so the dependency graph is known at workflow authoring time.
+fix_code:
+  - language: yaml
+    label: "Correct: static needs: with if: conditions to control execution"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            should_deploy: ${{ steps.check.outputs.deploy }}
+          steps:
+            - id: check
+              run: echo "deploy=true" >> $GITHUB_OUTPUT
+
+        deploy:
+          # Static needs: always declared; if: controls whether it runs
+          needs: [build]
+          if: needs.build.outputs.should_deploy == 'true'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "deploying"
+  - language: yaml
+    label: "Incorrect: expression in needs: causes parse-time validation error"
+    code: |
+      jobs:
+        generate:
+          runs-on: ubuntu-latest
+          outputs:
+            jobs: ${{ steps.list.outputs.jobs }}
+          steps:
+            - id: list
+              run: echo 'jobs=["build","lint"]' >> $GITHUB_OUTPUT
+
+        # ERROR: needs: does not evaluate expressions — this is a parse-time failure
+        deploy:
+          needs: ${{ fromJSON(needs.generate.outputs.jobs) }}
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "this never runs"
+prevention:
+  - "Always use static job ID string literals in `needs:` — no expressions, no fromJSON()"
+  - "Use actionlint to pre-validate workflows before pushing: it catches invalid expression contexts"
+  - "For dynamic fan-in, depend on the matrix job name itself, not individual matrix leg names"
+  - "Use `if: contains(needs.*.result, 'failure')` for conditional logic after static needs"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idneeds"
+    label: "GitHub Docs: jobs.<job_id>.needs"
+  - url: "https://rhysd.github.io/actionlint/"
+    label: "actionlint: Static checker for GitHub Actions workflow files"
+

package/package.json

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