@htekdev/actions-debugger 1.0.17 → 1.0.19

package/errors/concurrency-timing/cancel-runs-list-zombie-needs-jobs.yml

@@ -0,0 +1,89 @@
+id: concurrency-timing-015
+title: "Cancelling workflow from the Actions runs list leaves downstream needs/always() jobs zombie-queued"
+category: concurrency-timing
+severity: error
+tags:
+  - cancel
+  - needs
+  - always
+  - zombie
+  - matrix
+  - queued
+patterns:
+  - regex: "queued.*cancel|cancel.*queued"
+    flags: "i"
+  - regex: "This run has been cancelled"
+    flags: "i"
+error_messages:
+  - "This run has been cancelled"
+  - "Job is queued"
+root_cause: |
+  When a workflow is cancelled from the GitHub Actions **runs list page**
+  (https://github.com/{owner}/{repo}/actions), the cancellation signal does not
+  propagate to all pending/queued jobs. Specifically:
+
+  - Running jobs receive the cancellation correctly and terminate.
+  - Jobs that were not yet picked up by a runner but are waiting in a `needs:` chain
+    (especially with `if: always()`) remain stuck indefinitely in a "queued" state.
+  - These "zombie" queued jobs never start and never cancel on their own.
+
+  The problem is reproducible with:
+  1. A large matrix build (many parallel jobs)
+  2. A finalizer/aggregator job using `needs: [matrix-job]` + `if: always()`
+  3. Cancelling from the Actions overview list before all matrix jobs have started
+
+  The finalizer job enters the "queued" state but never receives the cancel signal
+  because the runs-list cancel does not do a full transitive cancel of downstream jobs.
+
+  Reported in actions/runner#4411 (May 2026) — closed as a known UI inconsistency.
+fix: |
+  **Workaround (immediate):** To fully cancel a stuck workflow:
+  1. Click through to the specific workflow run detail page
+     (not the Actions overview list)
+  2. Click the red "Cancel workflow" button from inside the run page
+
+  This second cancel terminates all zombie queued jobs immediately.
+
+  **Structural mitigation:** Add a `timeout-minutes` to your finalizer/aggregator job
+  so it self-terminates even if the cancel signal is not received:
+
+    jobs:
+      aggregate:
+        needs: [build]
+        if: always()
+        timeout-minutes: 5
+        runs-on: ubuntu-latest
+        steps:
+          - run: echo "Aggregating results"
+fix_code:
+  - language: yaml
+    label: "Add timeout-minutes to always() jobs as a safety net"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              target: [a, b, c, d, e, f, g, h]
+          runs-on: ubuntu-latest
+          steps:
+            - run: make ${{ matrix.target }}
+
+        aggregate:
+          needs: [build]
+          if: always()
+          timeout-minutes: 5      # prevents zombie queueing if cancel signal is lost
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Build result ${{ needs.build.result }}"
+prevention:
+  - "Always add `timeout-minutes` to finalizer jobs that use `if: always()` to limit zombie lifetime"
+  - "When cancelling a stuck workflow, navigate to the specific run page and use the in-run Cancel button"
+  - "Avoid relying on the Actions overview Cancel — it has incomplete propagation to queued downstream jobs"
+  - "Consider using a concurrency group to auto-cancel the entire workflow on re-trigger instead of manual cancellation"
+docs:
+  - url: "https://github.com/actions/runner/issues/4411"
+    label: "actions/runner#4411 — Cancellation from runs list leaves needs+always() jobs zombie-queued"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-jobs-in-a-workflow#defining-prerequisite-jobs"
+    label: "GitHub Docs — Defining prerequisite jobs (needs:)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/expressions#always"
+    label: "GitHub Docs — always() status check function"

package/errors/concurrency-timing/head-ref-empty-push-unintended-cancellation.yml

@@ -0,0 +1,76 @@
+id: concurrency-timing-014
+title: "github.head_ref empty on push events collapses concurrency group and cancels unrelated runs"
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - head_ref
+  - push-event
+  - cancel-in-progress
+  - cross-branch
+patterns:
+  - regex: "Run .*? was cancelled"
+    flags: "i"
+  - regex: "cancel-in-progress.*true"
+    flags: "i"
+error_messages:
+  - "Run <workflow-name> was cancelled"
+  - "This run has been cancelled by a newer run"
+root_cause: |
+  On `push` events, `github.head_ref` is always an empty string — it is only populated
+  for `pull_request` and `pull_request_target` events where a source branch exists.
+
+  When a concurrency group expression uses `github.head_ref` without a fallback value,
+  every push to any branch evaluates to the same empty-string group key. With
+  `cancel-in-progress: true`, each new push cancels any other in-progress run across
+  ALL branches — including unrelated feature branches and main.
+
+  Example of the broken pattern:
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.head_ref }}
+      cancel-in-progress: true
+
+  Pushing to `main` and `feature-branch` simultaneously means the second push cancels
+  the first, even though they are completely unrelated.
+
+  This is confirmed by GitHub Actions documentation and illustrated by Gitea's
+  implementation fix for the same semantic (go-gitea/gitea#37311, April 2026).
+fix: |
+  Use the `||` fallback operator so that push events fall back to `github.run_id`,
+  which is unique per workflow run and thus prevents any cross-run cancellation on push:
+
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+      cancel-in-progress: true
+
+  With this pattern:
+  - On pull_request events: `github.head_ref` is the source branch name — runs for the
+    same branch/PR cancel each other (desired behavior).
+  - On push events: `github.head_ref` is empty, so `github.run_id` is used — each
+    push run gets a unique group and is never cancelled by an unrelated run.
+fix_code:
+  - language: yaml
+    label: "Correct: fallback to github.run_id on push events"
+    code: |
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+        cancel-in-progress: true
+  - language: yaml
+    label: "Wrong: head_ref alone is empty on push — collapses all pushes to one group"
+    code: |
+      # DO NOT USE — cancels unrelated push runs
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.head_ref }}
+        cancel-in-progress: true
+prevention:
+  - "Always use `${{ github.head_ref || github.run_id }}` in concurrency groups, never `github.head_ref` alone"
+  - "Test concurrency behavior with simultaneous pushes to two unrelated branches to verify isolation"
+  - "If you only want per-PR cancellation and not per-push cancellation, restrict the concurrency block to PR events using an `if:` condition"
+  - "Add a CI job that verifies no two concurrent push runs share a group key"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs"
+    label: "GitHub Docs — Controlling workflow concurrency"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push"
+    label: "GitHub Docs — push event payload (head_ref is absent)"
+  - url: "https://github.com/go-gitea/gitea/pull/37311"
+    label: "go-gitea/gitea#37311 — Fix actions concurrency groups cross-branch leak"

package/errors/permissions-auth/create-github-app-token-jwt-decode-error.yml

@@ -0,0 +1,79 @@
+id: permissions-auth-021
+title: "create-github-app-token: A JSON web token could not be decoded (PEM key format)"
+category: permissions-auth
+severity: error
+tags:
+  - github-app
+  - jwt
+  - private-key
+  - pem
+  - create-github-app-token
+patterns:
+  - regex: "A JSON web token could not be decoded"
+    flags: "i"
+  - regex: "Failed to create token for .+\\(attempt \\d+\\): A JSON web token could not be decoded"
+    flags: "i"
+error_messages:
+  - "A JSON web token could not be decoded - https://docs.github.com/rest"
+  - "Failed to create token for \"repo-name\" (attempt 1): A JSON web token could not be decoded"
+  - "RequestError [HttpError]: A JSON web token could not be decoded"
+root_cause: |
+  The `actions/create-github-app-token` action signs a JWT using the GitHub App private key.
+  When the private key stored in the repository secret is malformed, every attempt to generate
+  a token fails with a 401 and this message. The action retries 4 times then fails the step.
+
+  Common causes:
+  1. Trailing whitespace or the final newline stripped when pasting the PEM into the GitHub
+     Secrets UI (the textarea strips trailing whitespace on save)
+  2. Windows-style CRLF line endings introduced during copy-paste from a text editor
+  3. Missing PEM header (`-----BEGIN RSA PRIVATE KEY-----`) or footer line
+  4. The Base64 body is correct but line breaks inside the key were removed
+  5. The full `.pem` file was Base64-encoded before being stored (double-encoded)
+
+  The GitHub API returns HTTP 401 with the message "A JSON web token could not be decoded"
+  whenever the JWT signature cannot be verified, which always indicates a malformed key.
+fix: |
+  Store the private key exactly as downloaded from GitHub — raw PEM format with LF line
+  endings, including the header and footer. Use the GitHub CLI to set the secret from the
+  downloaded file rather than copy-pasting it through the UI.
+
+  1. Download the private key from the GitHub App settings page
+     (Settings → Developer settings → GitHub Apps → Your App → Private keys)
+  2. Set the secret from the file:
+       gh secret set APP_PRIVATE_KEY < my-app.private-key.pem
+  3. Verify the secret was stored correctly by checking the Actions secrets list shows
+     the key was updated recently
+
+  If the key is already in a secret and you cannot change it, create a new private key
+  from the App settings and re-set the secret from the fresh download.
+fix_code:
+  - language: shell
+    label: "Set secret directly from downloaded .pem file (preserves newlines)"
+    code: |
+      # Download the .pem from GitHub App settings, then:
+      gh secret set APP_PRIVATE_KEY < my-app.2024-01-15.private-key.pem
+  - language: yaml
+    label: "Correct workflow: reference private key secret in action"
+    code: |
+      - uses: actions/create-github-app-token@v1
+        id: app-token
+        with:
+          app-id: ${{ vars.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+      
+      - name: Use generated token
+        run: echo "Token generated successfully"
+        env:
+          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
+prevention:
+  - "Always set the APP_PRIVATE_KEY secret using `gh secret set KEY < file.pem`, never by copy-pasting through the browser UI"
+  - "Regenerate and re-set the private key if you suspect formatting was corrupted during initial setup"
+  - "Verify the secret value in the GitHub UI shows the correct 'Updated' timestamp after setting via CLI"
+  - "Store private keys in a secrets manager (e.g., HashiCorp Vault, AWS Secrets Manager) and fetch at runtime to avoid manual copy-paste errors"
+docs:
+  - url: "https://github.com/actions/create-github-app-token"
+    label: "actions/create-github-app-token README"
+  - url: "https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-private-key-for-a-github-app"
+    label: "Generating a private key for a GitHub App"
+  - url: "https://github.com/actions/create-github-app-token/issues/153"
+    label: "actions/create-github-app-token#153: JWT decode error (27 comments)"

package/errors/permissions-auth/create-github-app-token-workflows-permission-denied.yml

@@ -0,0 +1,84 @@
+id: permissions-auth-022
+title: "create-github-app-token: push rejected — GitHub App missing `workflows` permission"
+category: permissions-auth
+severity: error
+tags:
+  - github-app
+  - create-github-app-token
+  - workflows-permission
+  - push
+  - git-push
+patterns:
+  - regex: "refusing to allow a GitHub App to create or update workflow .+ without `workflows` permission"
+    flags: "i"
+  - regex: "remote rejected.*refusing to allow a GitHub App.*workflows.*permission"
+    flags: "i"
+error_messages:
+  - "! [remote rejected]  ->  (refusing to allow a GitHub App to create or update workflow `.github/workflows/` without `workflows` permission)"
+  - "refusing to allow a GitHub App to create or update workflow `.github/workflows/my-workflow.yml` without `workflows` permission"
+  - "error: failed to push some refs to ''"
+root_cause: |
+  When a workflow uses `actions/create-github-app-token` to generate a token and then uses
+  that token to push commits that include changes to `.github/workflows/` files, GitHub
+  enforces that the GitHub App's installation token has the `workflows` write permission.
+
+  This permission gate was tightened in `actions/create-github-app-token` v2.1.4 due to
+  changes in `octokit/auth-app.js` (PR #712). Tokens generated without explicitly requesting
+  the `workflows` write permission no longer inherit it automatically, even if the GitHub App
+  itself has the permission enabled in its settings.
+
+  Two things must be true for the push to succeed:
+  1. The GitHub App has the `Workflows` repository permission set to Read & Write in the
+     App's settings page
+  2. The `permission-workflows: write` input is passed to `actions/create-github-app-token`
+     so the generated token explicitly includes that permission
+fix: |
+  Add `permission-workflows: write` to the `actions/create-github-app-token` step. Also
+  verify that the GitHub App itself has the Workflows permission enabled in its settings.
+
+  Steps:
+  1. Go to https://github.com/settings/apps/YOUR_APP/permissions
+  2. Under "Repository permissions", set "Workflows" to "Read and write"
+  3. Save changes and accept the permission update for affected organizations/users
+  4. Update your workflow to pass `permission-workflows: write`
+fix_code:
+  - language: yaml
+    label: "Add workflows write permission to token generation step"
+    code: |
+      - uses: actions/create-github-app-token@v1
+        id: app-token
+        with:
+          app-id: ${{ vars.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+          permission-workflows: write  # ✅ Required when pushing workflow file changes
+      
+      - name: Configure git with app token
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git remote set-url origin https://x-access-token:${{ steps.app-token.outputs.token }}@github.com/${{ github.repository }}
+      
+      - name: Push changes including workflow files
+        run: git push
+  - language: yaml
+    label: "Fallback: pin to v2.1.3 if immediate permission change is not possible"
+    code: |
+      # Pinning to a pre-v2.1.4 version is a temporary workaround only.
+      # Migrate to permission-workflows: write as soon as possible.
+      - uses: actions/create-github-app-token@v2.1.3
+        id: app-token
+        with:
+          app-id: ${{ vars.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+prevention:
+  - "Always specify `permission-workflows: write` when the token will be used to push `.github/workflows/` changes"
+  - "Verify the GitHub App's Workflows repository permission is set to Read & Write in the App settings"
+  - "Avoid pinning to old versions as a workaround — explicitly grant the required permission instead"
+  - "Use separate token generation steps with minimal permissions for each distinct operation"
+docs:
+  - url: "https://github.com/actions/create-github-app-token"
+    label: "actions/create-github-app-token README"
+  - url: "https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-workflows"
+    label: "Permissions required for GitHub Apps — Workflows"
+  - url: "https://github.com/actions/create-github-app-token/issues/301"
+    label: "actions/create-github-app-token#301: workflows permission push rejection"

package/errors/permissions-auth/enterprise-oidc-issuer-slug-mismatch.yml

@@ -0,0 +1,103 @@
+id: permissions-auth-020
+title: "GHEC enterprise OIDC issuer slug causes token verification mismatch with cloud tools"
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - enterprise
+  - ghec
+  - issuer
+  - attestation
+  - cloud-auth
+patterns:
+  - regex: "expected issuer.*got.*githubusercontent\\.com/[a-z0-9-]+"
+    flags: "i"
+  - regex: "issuer mismatch.*token\\.actions\\.githubusercontent\\.com"
+    flags: "i"
+  - regex: "no matching CertificateIdentity.*issuer"
+    flags: "i"
+error_messages:
+  - "Error: verifying with issuer \"sigstore.dev\": failed to verify certificate identity: no matching CertificateIdentity found, last error: expected issuer value \"https://token.actions.githubusercontent.com\", got \"https://token.actions.githubusercontent.com/my-enterprise\""
+  - "Error: expected issuer to be https://token.actions.githubusercontent.com, got https://token.actions.githubusercontent.com/my-enterprise"
+  - "UnauthorizedException: Issuer does not match configured value"
+root_cause: |
+  GitHub Enterprise Cloud (GHEC) organizations can customize the OIDC token issuer
+  claim to include their unique enterprise slug, for example:
+
+    Default issuer: https://token.actions.githubusercontent.com
+    Enterprise issuer: https://token.actions.githubusercontent.com/my-enterprise
+
+  This customization is a security feature (prevents tokens from one enterprise from
+  being used against another's cloud resources), but it creates a mismatch for:
+
+  1. **`gh attestation verify`**: The CLI tool defaults to verifying against the
+     standard issuer. If the enterprise issuer is active, verification fails with
+     "expected issuer … got … my-enterprise" unless `--cert-oidc-issuer` is passed.
+
+  2. **Cloud provider trust policies**: AWS, Azure, GCP OIDC federation configured
+     against the default issuer URL rejects enterprise-slug tokens with auth errors.
+
+  3. **Third-party actions**: Actions that validate the OIDC token internally may
+     hardcode the default issuer and fail silently.
+
+  This affects any GHEC organization that has enabled the enterprise issuer
+  customization (via Enterprise Settings → OIDC provider → Customize issuer).
+fix: |
+  **For `gh attestation verify`:** Pass the enterprise-specific issuer URL:
+
+    gh attestation verify artifact.zip \
+      --owner my-enterprise \
+      --cert-oidc-issuer https://token.actions.githubusercontent.com/my-enterprise
+
+  **For AWS IAM:** Update the OIDC provider URL in IAM to use the enterprise issuer:
+
+    Provider URL: https://token.actions.githubusercontent.com/my-enterprise
+    Audience: sts.amazonaws.com
+
+  **For Azure Workload Identity:** Set the issuer in the federated credential to:
+
+    https://token.actions.githubusercontent.com/my-enterprise
+
+  **For GCP Workload Identity Pool:** Set the issuer URI in the OIDC provider config
+  to the enterprise issuer URL.
+
+  **To check your enterprise issuer:**
+  Visit https://token.actions.githubusercontent.com/my-enterprise/.well-known/openid-configuration
+  — if it returns a valid document, enterprise issuer customization is active.
+fix_code:
+  - language: yaml
+    label: "gh attestation verify with enterprise issuer"
+    code: |
+      - name: Attest artifact
+        run: |
+          gh attestation verify dist/my-app \
+            --owner my-enterprise \
+            --cert-oidc-issuer https://token.actions.githubusercontent.com/my-enterprise
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  - language: yaml
+    label: "AWS credentials action with enterprise OIDC issuer"
+    code: |
+      # In AWS IAM, create the OIDC identity provider with the enterprise issuer URL
+      # instead of the default https://token.actions.githubusercontent.com
+      # Then configure the federated role trust policy:
+      {
+        "Condition": {
+          "StringEquals": {
+            "token.actions.githubusercontent.com/my-enterprise:aud": "sts.amazonaws.com",
+            "token.actions.githubusercontent.com/my-enterprise:sub": "repo:my-enterprise/my-repo:ref:refs/heads/main"
+          }
+        }
+      }
+prevention:
+  - "Document whether your GHEC enterprise has the custom issuer enabled — include it in your OIDC onboarding checklist"
+  - "Store the full enterprise issuer URL in a reusable variable or org-level secret to avoid hardcoding it in every workflow"
+  - "When setting up new cloud OIDC federation, verify the issuer from the well-known endpoint rather than copying from docs"
+  - "Pin `gh attestation verify` calls to always include `--cert-oidc-issuer` in enterprise repos"
+docs:
+  - url: "https://docs.github.com/en/enterprise-cloud@latest/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-issuer-value-for-an-enterprise"
+    label: "GitHub Docs — Customizing the OIDC issuer value for an enterprise"
+  - url: "https://github.com/cli/cli/pull/9616"
+    label: "cli/cli#9616 — Better messaging for attestation verify custom issuer mismatch error"
+  - url: "https://token.actions.githubusercontent.com/.well-known/openid-configuration"
+    label: "GitHub OIDC well-known endpoint (check your enterprise variant at /{slug}/.well-known/openid-configuration)"

package/errors/permissions-auth/oidc-sub-claim-repo-rename-breaks-trust.yml

@@ -0,0 +1,111 @@
+id: permissions-auth-019
+title: "OIDC sub claim breaks cloud trust policies after repository rename or transfer"
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - sub-claim
+  - repo-rename
+  - repo-transfer
+  - cloud-auth
+  - aws
+  - azure
+  - gcp
+patterns:
+  - regex: "no matching CertificateIdentity"
+    flags: "i"
+  - regex: "sub.*does not match|subject.*mismatch|token validation failed"
+    flags: "i"
+  - regex: "Error: Could not assume role.*subject claim"
+    flags: "i"
+error_messages:
+  - "Error: No matching identity found in OIDC token"
+  - "Error: Could not assume role with web identity: NotAuthorized"
+  - "no matching CertificateIdentity found, last error: certificate identity not found"
+  - "subject claim mismatch: expected repo:old-owner/old-repo, got repo:new-owner/new-repo"
+root_cause: |
+  GitHub Actions OIDC tokens include a `sub` (subject) claim that encodes the repository
+  owner and name using their **mutable string names**, for example:
+
+    repo:octocat/my-app:ref:refs/heads/main
+
+  Cloud providers (AWS, Azure, GCP) and tools like `gh attestation verify` configure
+  trust policies against this `sub` claim value. When a repository is **renamed** or
+  **transferred** to a different organization, the `sub` claim changes immediately:
+
+    Before transfer: repo:old-org/my-app:ref:refs/heads/main
+    After transfer:  repo:new-org/my-app:ref:refs/heads/main
+
+  All cloud trust policies that reference the old `sub` format instantly break.
+  OIDC authentication fails with "subject mismatch" or "no matching identity" errors
+  even though the workflow code and secrets are identical.
+
+  GitHub announced immutable sub claims (appending numeric owner/repo IDs) on
+  2026-04-23, but existing repositories must opt in explicitly. New repositories
+  created or transferred after June 18, 2026 automatically use the new format.
+
+  Old (mutable) format:  repo:owner/repo:ref:refs/heads/main
+  New (immutable) format: repo:owner-123456/repo-789012:ref:refs/heads/main
+fix: |
+  **Before renaming or transferring a repo:**
+
+  1. Enable immutable subject claims in repository or organization OIDC settings
+     (Settings → Actions → General → OIDC subject claims → Enable immutable format).
+  2. Use the preview endpoint to see the new sub claim format before it takes effect.
+  3. Update all cloud provider trust policies and IAM role conditions to accept the
+     new immutable format (includes numeric IDs alongside names).
+
+  **After an unplanned rename/transfer:**
+
+  1. Identify the new `sub` claim value by decoding the OIDC token from a failed run
+     or using the GitHub OIDC preview API.
+  2. Update the trust policy in each cloud provider to reference the new repo path.
+  3. Optionally opt into immutable claims to future-proof against further renames.
+
+  **For AWS IAM (StringLike condition):**
+    Condition:
+      StringLike:
+        token.actions.githubusercontent.com:sub:
+          - "repo:new-org/new-repo:*"
+fix_code:
+  - language: yaml
+    label: "AWS IAM trust policy update after repo rename"
+    code: |
+      # Update the StringLike condition in your IAM role trust policy
+      # Replace old path with new path after rename/transfer
+      {
+        "Condition": {
+          "StringLike": {
+            "token.actions.githubusercontent.com:sub": "repo:new-org/new-repo:*"
+          }
+        }
+      }
+  - language: yaml
+    label: "Workflow: use immutable OIDC subject for new repos (June 18 2026+)"
+    code: |
+      # No workflow change needed — immutable format is set in repo/org settings.
+      # Once enabled, the sub claim becomes:
+      #   repo:owner-123456/repo-789012:ref:refs/heads/main
+      # Update cloud trust policies to use the new format BEFORE enabling immutable claims.
+      jobs:
+        deploy:
+          permissions:
+            id-token: write
+            contents: read
+          steps:
+            - uses: aws-actions/configure-aws-credentials@v4
+              with:
+                role-to-assume: arn:aws:iam::123456789:role/my-role
+                aws-region: us-east-1
+prevention:
+  - "Enable immutable OIDC subject claims before any rename or transfer to prevent trust policy breakage"
+  - "Store the expected sub claim value in cloud trust policies as a wildcard (`repo:owner/repo:*`) rather than exact paths to tolerate ref changes"
+  - "Add OIDC trust policy updates to your repo rename/transfer runbook"
+  - "New repos created after June 18, 2026 automatically use immutable sub claims — update trust policies accordingly"
+docs:
+  - url: "https://github.blog/changelog/2026-04-23-immutable-subject-claims-for-github-actions-oidc-tokens/"
+    label: "GitHub Changelog 2026-04-23 — Immutable subject claims for GitHub Actions OIDC tokens"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect"
+    label: "GitHub Docs — About security hardening with OpenID Connect"
+  - url: "https://docs.github.com/en/enterprise-cloud@latest/actions/reference/security/oidc"
+    label: "GitHub Docs — OIDC token claims reference"

package/errors/silent-failures/attest-build-provenance-push-to-registry-404.yml

@@ -0,0 +1,105 @@
+id: silent-failures-025
+title: "attest-build-provenance: OCIError 404 when image not pushed to registry before attestation"
+category: silent-failures
+severity: error
+tags:
+  - attest-build-provenance
+  - oci
+  - container-registry
+  - slsa
+  - attestation
+  - push-to-registry
+patterns:
+  - regex: "OCIError: Error uploading artifact to container registry"
+    flags: "i"
+  - regex: "Error fetching .+/manifests/sha256:[a-f0-9]+ - expected 200, received 404"
+    flags: "i"
+  - regex: "expected 200, received 404"
+    flags: "i"
+error_messages:
+  - "Error: OCIError: Error uploading artifact to container registry"
+  - "Error: Error fetching https://ghcr.io/v2/owner/repo/manifests/sha256:abc123... - expected 200, received 404"
+root_cause: |
+  `actions/attest-build-provenance` with `push-to-registry: true` fetches the image manifest
+  from the container registry to embed it in the attestation bundle. If the image was built
+  with `load: true` in `docker/build-push-action` but `push: false` (or a conditional push
+  that evaluated to false), the image exists only in the runner's local Docker daemon — not
+  in the remote registry. The attestation step then fails with a 404 when fetching the
+  manifest from the registry URL.
+
+  This is a silent misconfiguration: the build step "succeeds" (because `load: true` works),
+  the attestation step then fails with a cryptic OCI/manifest error instead of a clear message
+  explaining that the image was never pushed.
+
+  Typical trigger: workflows that conditionally push (e.g., only on `main` branch) but run
+  the attestation step unconditionally on every push/PR.
+fix: |
+  Guard the attestation step with the same `if:` condition used for the image push.
+  The attestation step should only run when the image was actually pushed to the registry.
+
+  If you need to generate attestations on PRs (e.g., for preview images), ensure the image
+  is actually pushed to a staging registry before the attestation step runs.
+fix_code:
+  - language: yaml
+    label: "Wrong: attestation runs unconditionally even when image not pushed"
+    code: |
+      - name: Build and push
+        id: build-push
+        uses: docker/build-push-action@v6
+        with:
+          push: ${{ github.ref == 'refs/heads/main' }}  # Only pushes on main
+          load: true
+          tags: ghcr.io/org/app:latest
+      
+      - name: Generate attestation
+        uses: actions/attest-build-provenance@v2
+        with:
+          subject-name: ghcr.io/org/app
+          subject-digest: ${{ steps.build-push.outputs.digest }}
+          push-to-registry: true  # ❌ Fails on PRs — image is local-only
+  - language: yaml
+    label: "Fix: match attestation if condition to the push condition"
+    code: |
+      - name: Build and push
+        id: build-push
+        uses: docker/build-push-action@v6
+        with:
+          push: ${{ github.ref == 'refs/heads/main' }}
+          load: true
+          tags: ghcr.io/org/app:latest
+      
+      - name: Generate attestation
+        if: github.ref == 'refs/heads/main'  # ✅ Same condition as push
+        uses: actions/attest-build-provenance@v2
+        with:
+          subject-name: ghcr.io/org/app
+          subject-digest: ${{ steps.build-push.outputs.digest }}
+          push-to-registry: true
+  - language: yaml
+    label: "Alternative: use push-to-registry: false for GitHub-only attestations"
+    code: |
+      - name: Build and push
+        id: build-push
+        uses: docker/build-push-action@v6
+        with:
+          push: true
+          tags: ghcr.io/org/app:latest
+      
+      - name: Generate attestation (stored in GitHub, not registry)
+        uses: actions/attest-build-provenance@v2
+        with:
+          subject-name: ghcr.io/org/app
+          subject-digest: ${{ steps.build-push.outputs.digest }}
+          push-to-registry: false  # ✅ Default; stores attestation in GitHub only
+prevention:
+  - "Always guard `push-to-registry: true` attestation steps with the same `if:` condition used for the image push"
+  - "Remember: `load: true` in docker/build-push-action loads the image into the local Docker daemon only — it does not push to any registry"
+  - "Use `push-to-registry: false` (the default) when attestations only need to be verified via `gh attestation verify`, not via the registry manifest"
+  - "Set `push: ${{ steps.should-push.outputs.result }}` and reuse that output in the attestation step's `if:` condition to keep them in sync"
+docs:
+  - url: "https://github.com/actions/attest-build-provenance"
+    label: "actions/attest-build-provenance README"
+  - url: "https://docs.github.com/en/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds"
+    label: "Using artifact attestations to establish provenance for builds"
+  - url: "https://github.com/actions/attest-build-provenance/issues/747"
+    label: "actions/attest-build-provenance#747: 404 when uploading artifact to container registry"

package/errors/triggers/workflow-run-artifact-download-missing-run-id.yml

@@ -0,0 +1,106 @@
+id: triggers-018
+title: "workflow_run: download-artifact finds no artifacts without explicit run-id"
+category: triggers
+severity: silent-failure
+tags:
+  - workflow_run
+  - download-artifact
+  - run-id
+  - cross-workflow
+  - artifact
+patterns:
+  - regex: "No artifacts found"
+    flags: "i"
+  - regex: "Unable to find any artifacts for the associated workflow"
+    flags: "i"
+  - regex: "No artifacts were found with the provided run ID"
+    flags: "i"
+error_messages:
+  - "No artifacts found"
+  - "Unable to find any artifacts for the associated workflow run"
+  - "Warning: No artifacts were found with the provided run ID."
+  - "Error: Unable to find any artifacts for the associated workflow run"
+root_cause: |
+  When a workflow is triggered by the `workflow_run` event, it runs in the context of
+  **its own** workflow run — not the triggering workflow run. If `actions/download-artifact`
+  is called without specifying `run-id`, it defaults to `${{ github.run_id }}` which is the
+  ID of the triggered (consumer) workflow — not the upstream workflow that produced the
+  artifacts.
+
+  Since the consumer workflow produces no artifacts itself, `download-artifact` finds nothing.
+  This is a silent failure in some versions: the step exits without error but no files are
+  downloaded, causing subsequent steps that depend on the artifact to fail with confusing errors.
+
+  The artifact was uploaded in the triggering workflow's run. To download it, you must
+  explicitly reference `github.event.workflow_run.id` (the upstream run's ID).
+fix: |
+  Add `run-id: ${{ github.event.workflow_run.id }}` to the `actions/download-artifact`
+  step. This tells the action to download from the triggering workflow run rather than
+  the current workflow run.
+
+  Also ensure the token has `actions: read` permission to download artifacts from other runs.
+fix_code:
+  - language: yaml
+    label: "Wrong: download-artifact defaults to current run (finds nothing in workflow_run)"
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+      
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-output  # ❌ Defaults to github.run_id (this run, has no artifacts)
+  - language: yaml
+    label: "Fix: explicitly reference the triggering run's ID"
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+      
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          permissions:
+            actions: read  # Required to download artifacts from other workflow runs
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-output
+                run-id: ${{ github.event.workflow_run.id }}  # ✅ The upstream run's ID
+  - language: yaml
+    label: "Guard: only run if triggering workflow succeeded"
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+      
+      jobs:
+        deploy:
+          if: github.event.workflow_run.conclusion == 'success'  # ✅ Don't deploy on failure
+          runs-on: ubuntu-latest
+          permissions:
+            actions: read
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: build-output
+                run-id: ${{ github.event.workflow_run.id }}
+prevention:
+  - "Always specify `run-id: ${{ github.event.workflow_run.id }}` when downloading artifacts in a `workflow_run`-triggered workflow"
+  - "Add `permissions: actions: read` to any job that downloads artifacts from a different workflow run"
+  - "Guard the job with `if: github.event.workflow_run.conclusion == 'success'` to skip on upstream failures"
+  - "Use `github.event.workflow_run.id` (not `github.run_id`) — they are different: the former is the upstream run, the latter is the current consumer run"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run"
+    label: "Events that trigger workflows — workflow_run"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow#downloading-artifacts-from-a-different-workflow-run"
+    label: "Downloading artifacts from a different workflow run"
+  - url: "https://github.com/actions/download-artifact"
+    label: "actions/download-artifact README"

package/errors/yaml-syntax/reusable-workflow-env-context-with-inputs.yml

@@ -0,0 +1,102 @@
+id: yaml-syntax-023
+title: "Reusable workflow: env context rejected in `jobs.<job_id>.with` inputs"
+category: yaml-syntax
+severity: error
+tags:
+  - reusable-workflow
+  - env-context
+  - with-inputs
+  - workflow_call
+  - variable-scoping
+patterns:
+  - regex: "Unrecognized named-value: 'env'"
+    flags: "i"
+  - regex: "Context access might be invalid: env"
+    flags: "i"
+  - regex: "The env context is not available"
+    flags: "i"
+error_messages:
+  - "Unrecognized named-value: 'env'. Located at position 1 within expression: env.MY_VAR"
+  - "Context access might be invalid: env"
+  - "The env context is not available to reusable workflow inputs"
+root_cause: |
+  When calling a reusable workflow using `jobs.<job_id>.uses`, the `env` context is not
+  available inside the `with:` block. Only the following contexts are permitted at that
+  evaluation point: `github`, `inputs`, `needs`, `strategy`, and `matrix`.
+
+  This is a platform-level restriction. The `env` context is resolved during job execution
+  on the runner, but reusable workflow `with:` inputs are evaluated at workflow dispatch time
+  (before a runner is allocated), so `env` values are simply unavailable.
+
+  Top-level `env:` blocks defined in the caller workflow cannot be referenced inside
+  `jobs.<job_id>.with` — using `${{ env.MY_VAR }}` there produces a syntax validation
+  error that prevents the workflow from running at all.
+fix: |
+  Replace `${{ env.MY_VAR }}` in reusable workflow `with:` inputs with one of:
+
+  1. `${{ vars.MY_VAR }}` — repository or organization variable (preferred for non-secret
+     configuration values that are reused across workflows)
+  2. Hardcoded literal value directly in `with:`
+  3. An intermediate job that exposes the value as a job output, then reference it via
+     `${{ needs.prepare.outputs.my_var }}`
+fix_code:
+  - language: yaml
+    label: "Wrong: env context in reusable workflow with inputs"
+    code: |
+      env:
+        DEPLOY_ENV: "production"
+      
+      jobs:
+        deploy:
+          uses: org/repo/.github/workflows/deploy.yml@main
+          with:
+            environment: ${{ env.DEPLOY_ENV }}   # ❌ Error: env context not available
+  - language: yaml
+    label: "Fix option 1: use vars context (repository/org variable)"
+    code: |
+      jobs:
+        deploy:
+          uses: org/repo/.github/workflows/deploy.yml@main
+          with:
+            environment: ${{ vars.DEPLOY_ENV }}  # ✅ vars context works in with:
+  - language: yaml
+    label: "Fix option 2: propagate via intermediate job output"
+    code: |
+      env:
+        DEPLOY_ENV: "production"
+      
+      jobs:
+        prepare:
+          runs-on: ubuntu-latest
+          outputs:
+            deploy_env: ${{ steps.set-env.outputs.value }}
+          steps:
+            - id: set-env
+              run: echo "value=$DEPLOY_ENV" >> "$GITHUB_OUTPUT"
+        
+        deploy:
+          needs: prepare
+          uses: org/repo/.github/workflows/deploy.yml@main
+          with:
+            environment: ${{ needs.prepare.outputs.deploy_env }}  # ✅
+  - language: yaml
+    label: "Fix option 3: hardcode the value directly"
+    code: |
+      jobs:
+        deploy:
+          uses: org/repo/.github/workflows/deploy.yml@main
+          with:
+            environment: "production"  # ✅ Literal values always work
+prevention:
+  - "Store workflow-wide configuration values in repository or organization variables (`vars` context) so they are available in reusable workflow `with:` blocks"
+  - "Only `github`, `inputs`, `needs`, `strategy`, and `matrix` contexts are available in `jobs.<job_id>.with` — never `env`, `secrets`, or `steps`"
+  - "If a value must be computed at runtime, use an intermediate job with `outputs:` and reference via `needs.<job_id>.outputs.<key>`"
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows#limitations"
+    label: "Reusing workflows — Limitations"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#context-availability"
+    label: "GitHub Actions context availability by workflow key"
+  - url: "https://github.com/actions/runner/issues/1413"
+    label: "actions/runner#1413: env not available in reusable workflow with inputs (known limitation)"
+  - url: "https://github.com/actions/toolkit/issues/931"
+    label: "actions/toolkit#931: Variable scoping across reusable workflows (58 reactions)"

package/package.json

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