@htekdev/actions-debugger 1.0.18 → 1.0.20

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/fine-grained-pat-org-restricted-forbidden.yml

@@ -0,0 +1,104 @@
+id: permissions-auth-024
+title: "Fine-Grained PATs Blocked by Organization Policy — 'forbidden from accessing this repository'"
+category: permissions-auth
+severity: error
+tags:
+  - fine-grained-pat
+  - organization-policy
+  - personal-access-token
+  - authentication
+  - 403
+patterns:
+  - regex: "Fine-grained personal access tokens are forbidden from accessing this repository"
+    flags: "i"
+  - regex: "fine.grained.*forbidden|forbidden.*fine.grained"
+    flags: "i"
+  - regex: "personal access tokens.*not permitted|PAT.*restricted"
+    flags: "i"
+error_messages:
+  - "remote: Fine-grained personal access tokens are forbidden from accessing this repository."
+  - "fatal: unable to access 'https://github.com/org/repo.git/': The requested URL returned error: 403"
+  - "Fine-grained personal access tokens are forbidden from accessing this repository."
+root_cause: |
+  GitHub organizations can restrict which types of PATs are allowed to access their
+  resources. When an organization enables "Restrict access via fine-grained personal
+  access tokens" (or sets PAT policy to "Disable fine-grained personal access tokens"),
+  any fine-grained PAT — regardless of its scopes or permissions — will be rejected
+  with a 403 error containing the message "Fine-grained personal access tokens are
+  forbidden from accessing this repository."
+
+  This policy applies even if:
+  - The fine-grained PAT has all required permissions (contents: write, etc.)
+  - The PAT was created by an org owner
+  - The repository is public
+  - The user is an org admin
+
+  Common confusion: developers who switch from classic PATs to fine-grained PATs
+  for better security/granularity hit this org-level block and cannot understand
+  why a seemingly correct token still fails with 403.
+
+  Sources: stackoverflow.com/questions/79471500,
+           GitHub Docs on PAT policies for organizations
+fix: |
+  Option 1 (Immediate fix): Use a classic PAT with the required scopes instead of
+  a fine-grained PAT. Classic PATs are not subject to the fine-grained restriction.
+
+  Option 2 (Organization change — requires admin): Have an org admin update the
+  organization's PAT policy to allow fine-grained PATs:
+    Settings → Developer Settings → Personal access token policy
+    → Allow fine-grained personal access tokens
+    → (optionally require approval for each token)
+
+  Option 3 (Recommended long-term): Replace the PAT with a GitHub App token.
+  GitHub App tokens are not subject to org-level PAT restrictions and provide
+  better auditability and short-lived credentials.
+fix_code:
+  - language: yaml
+    label: "Use classic PAT (immediate workaround)"
+    code: |
+      # Replace the fine-grained PAT secret with a classic PAT:
+      # GitHub.com > Settings > Developer settings > Personal access tokens > Tokens (classic)
+      # Create new token with required scopes (e.g., repo)
+      # Add to repo secrets as CLASSIC_PAT
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                token: ${{ secrets.CLASSIC_PAT }}
+                # Classic PATs work even when org blocks fine-grained PATs
+  - language: yaml
+    label: "Use a GitHub App token (recommended)"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Generate GitHub App token
+              id: app-token
+              uses: actions/create-github-app-token@v1
+              with:
+                app-id: ${{ vars.APP_ID }}
+                private-key: ${{ secrets.APP_PRIVATE_KEY }}
+                owner: ${{ github.repository_owner }}
+              # GitHub App tokens bypass org-level PAT restrictions entirely
+
+            - uses: actions/checkout@v4
+              with:
+                token: ${{ steps.app-token.outputs.token }}
+prevention:
+  - "Before using fine-grained PATs for org repositories, verify the org allows them via Settings → Third-party access → Personal access tokens."
+  - "Document the org's PAT policy in your CI/onboarding docs so contributors know which token types are accepted."
+  - "Prefer GitHub App tokens over any PAT type — they are not subject to PAT restriction policies and provide short-lived, auditable credentials."
+  - "When a PAT fails with 403, check if the error message contains 'fine-grained' before debugging scopes — the token type itself may be blocked."
+docs:
+  - url: "https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization"
+    label: "Setting a PAT policy for your organization"
+  - url: "https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens"
+    label: "Managing personal access tokens"
+  - url: "https://stackoverflow.com/questions/79471500/github-actions-authentication-failed-for-pushing-to-repository"
+    label: "SO: GitHub Actions — Authentication Failed for Pushing to Repository (fine-grained PAT forbidden)"
+  - url: "https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow"
+    label: "Using GitHub App tokens in GitHub Actions"

package/errors/permissions-auth/pat-sso-org-not-authorized-checkout-404.yml

@@ -0,0 +1,107 @@
+id: permissions-auth-023
+title: "PAT Fails with 'Not Found' on SSO-Protected Organization Repository"
+category: permissions-auth
+severity: error
+tags:
+  - personal-access-token
+  - saml-sso
+  - organization
+  - checkout
+  - authentication
+patterns:
+  - regex: "Not Found - https://docs\\.github\\.com/rest/repos/repos#get-a-repository"
+    flags: "i"
+  - regex: "fatal: unable to access.*403|Syncing repository.*Not Found"
+    flags: "i"
+  - regex: "could not read Username.*https://github\\.com"
+    flags: "i"
+error_messages:
+  - "Not Found - https://docs.github.com/rest/repos/repos#get-a-repository"
+  - "Retrieving the default branch name"
+  - "  Not Found - https://docs.github.com/rest/repos/repos#get-a-repository"
+  - "Error: Not Found - https://docs.github.com/rest/repos/repos#get-a-repository"
+root_cause: |
+  When a GitHub organization enforces SAML SSO (Single Sign-On), every PAT
+  (Personal Access Token) used to access that organization's resources must be
+  explicitly authorized for the SSO organization — even if the token has all the
+  correct scopes (repo, read:org, etc.).
+
+  A PAT that hasn't been authorized for the SSO org will receive a 404 "Not Found"
+  response when attempting to access org resources via the API or when cloning/
+  checking out a repository. The response is 404 (not 401/403) because GitHub
+  treats an unauthorized SSO request as "resource doesn't exist for this token."
+
+  Common symptoms:
+  - `actions/checkout` fails with "Not Found" on the default branch retrieval step
+  - The PAT works locally in a browser (which has an active SSO session) but fails
+    in GitHub Actions
+  - The token has `repo` scope or `contents: read` permission but still 404s
+
+  Sources: stackoverflow.com/questions/79874764,
+           stackoverflow.com/questions/77957649,
+           GitHub Docs on SAML SSO authorization
+fix: |
+  Authorize the PAT for the SSO organization:
+
+  1. Go to GitHub → Settings → Developer settings → Personal access tokens
+  2. Select the PAT used in the workflow
+  3. Click "Configure SSO" next to the token
+  4. Click "Authorize" next to the target organization
+  5. Complete any SSO prompts
+
+  The PAT is now authorized for that org and will work in Actions workflows.
+
+  For fine-grained PATs: ensure the token's "Resource owner" is the organization
+  (not your personal account) and that the org admin has approved it.
+fix_code:
+  - language: yaml
+    label: "Authorize the PAT for SSO org (no workflow change needed)"
+    code: |
+      # This is a GitHub settings action, not a workflow change.
+      # GitHub.com > Settings > Developer settings > Personal access tokens
+      # > (select token) > Configure SSO > Authorize > (org name)
+      #
+      # After authorizing, your workflow using the PAT will work:
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                repository: my-org/private-repo
+                token: ${{ secrets.MY_ORG_PAT }}
+                # MY_ORG_PAT must have 'repo' scope AND be SSO-authorized for my-org
+  - language: yaml
+    label: "Use a GitHub App token instead (recommended for SSO orgs)"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Generate GitHub App token
+              id: app-token
+              uses: actions/create-github-app-token@v1
+              with:
+                app-id: ${{ vars.APP_ID }}
+                private-key: ${{ secrets.APP_PRIVATE_KEY }}
+                owner: my-org
+                # GitHub App tokens for org installations are not subject to
+                # SAML SSO PAT authorization requirements
+            - uses: actions/checkout@v4
+              with:
+                repository: my-org/private-repo
+                token: ${{ steps.app-token.outputs.token }}
+prevention:
+  - "After creating a new PAT for use with an SSO-enforcing organization, always authorize it via Configure SSO before adding it to Actions secrets."
+  - "Test PAT access locally with `gh auth login --with-token` and `gh repo view my-org/repo` to confirm SSO authorization before using in CI."
+  - "Prefer GitHub App tokens over PATs for organization repositories — they are not subject to SAML SSO authorization requirements."
+  - "Document which secrets require SSO authorization in your repo's CONTRIBUTING or CI documentation to prevent the same issue for new contributors."
+docs:
+  - url: "https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on"
+    label: "Authorizing a PAT for use with SAML SSO"
+  - url: "https://docs.github.com/en/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on"
+    label: "About SAML SSO for organizations"
+  - url: "https://stackoverflow.com/questions/79874764/github-actions-checkout-fails-with-not-found-error-for-sso-protected-enterprise"
+    label: "SO: checkout fails with Not Found for SSO-protected enterprise repo"
+  - url: "https://stackoverflow.com/questions/77957649/repository-not-found-error-while-using-actions-checkoutv4-to-clone-a-private-re"
+    label: "SO: Repository not found error with actions/checkout@v4 on private repo"

package/errors/runner-environment/docker-buildx-matrix-platform-tag-overwrite.yml

@@ -0,0 +1,143 @@
+id: runner-environment-052
+title: "Docker Multi-Platform Build Uses Matrix per Platform — Tags Overwrite Each Other"
+category: runner-environment
+severity: silent-failure
+tags:
+  - docker
+  - buildx
+  - multi-platform
+  - matrix
+  - ghcr
+  - manifest
+patterns:
+  - regex: "no matching manifest for .* in the manifest list entries"
+    flags: "i"
+  - regex: "image operating system .* does not match host operating system"
+    flags: "i"
+  - regex: "manifest unknown"
+    flags: "i"
+error_messages:
+  - "no matching manifest for linux/amd64 in the manifest list entries"
+  - "Error response from daemon: manifest unknown: manifest unknown"
+  - "image operating system \"linux\" does not match host operating system \"linux\""
+root_cause: |
+  A common pattern for multi-platform Docker images in GitHub Actions is to use
+  `strategy.matrix` with one platform per job and `docker/build-push-action` in
+  each job. This approach is incorrect: each job pushes a single-platform image
+  to the same tag, and each push *overwrites* the previous one. There is no merging
+  of single-platform images into a multi-platform manifest list.
+
+  After all matrix jobs complete, the tag only contains the image from the last
+  job to push — typically whichever platform finished last. All other platforms are
+  silently lost.
+
+  When another host tries to pull the image on a different architecture (e.g.,
+  linux/arm64 pulling after linux/amd64 was last to write), they receive:
+  "no matching manifest for linux/arm64 in the manifest list entries"
+
+  The workflow itself reports success — all matrix jobs push successfully. The
+  failure is silent until image consumers on other architectures try to pull.
+
+  Sources: stackoverflow.com/questions/79315376,
+           Docker multi-platform build documentation
+fix: |
+  Use a single `docker/build-push-action` step with comma-separated platforms
+  instead of a matrix. Docker Buildx handles building all platforms in one job
+  and pushes a proper multi-platform manifest list.
+
+  If you need dedicated builders for each platform (e.g., native ARM runners),
+  use the "bake + merge manifest" pattern with `docker buildx imagetools create`
+  to merge per-platform digests into a single manifest after all builds complete.
+fix_code:
+  - language: yaml
+    label: "Single buildx job with comma-separated platforms (recommended)"
+    code: |
+      jobs:
+        build-and-push:
+          runs-on: ubuntu-latest
+          permissions:
+            packages: write
+            contents: read
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Set up QEMU
+              uses: docker/setup-qemu-action@v3
+
+            - name: Set up Docker Buildx
+              uses: docker/setup-buildx-action@v3
+
+            - name: Login to GHCR
+              uses: docker/login-action@v3
+              with:
+                registry: ghcr.io
+                username: ${{ github.actor }}
+                password: ${{ secrets.GITHUB_TOKEN }}
+
+            - name: Build and push multi-platform image
+              uses: docker/build-push-action@v6
+              with:
+                push: true
+                platforms: linux/amd64,linux/arm64,linux/arm/v7
+                # All platforms in one step → proper manifest list created
+                tags: ghcr.io/${{ github.repository_owner }}/myapp:latest
+  - language: yaml
+    label: "Native-builder pattern: build per platform, merge manifest (advanced)"
+    code: |
+      # Build per-platform in parallel jobs, then merge into a manifest list
+      jobs:
+        build:
+          strategy:
+            matrix:
+              include:
+                - platform: linux/amd64
+                  runner: ubuntu-latest
+                - platform: linux/arm64
+                  runner: ubuntu-24.04-arm  # native ARM runner
+          runs-on: ${{ matrix.runner }}
+          outputs:
+            digest: ${{ steps.push.outputs.digest }}
+          steps:
+            - uses: actions/checkout@v4
+            - uses: docker/setup-buildx-action@v3
+            - uses: docker/login-action@v3
+              with:
+                registry: ghcr.io
+                username: ${{ github.actor }}
+                password: ${{ secrets.GITHUB_TOKEN }}
+            - name: Build and push by digest (no tag yet)
+              id: push
+              uses: docker/build-push-action@v6
+              with:
+                push: true
+                platforms: ${{ matrix.platform }}
+                # Push by digest only — do NOT set a tag here
+                outputs: type=image,name=ghcr.io/${{ github.repository_owner }}/myapp,push-by-digest=true,name-canonical=true
+
+        merge:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - uses: docker/login-action@v3
+              with:
+                registry: ghcr.io
+                username: ${{ github.actor }}
+                password: ${{ secrets.GITHUB_TOKEN }}
+            - name: Create and push multi-platform manifest
+              run: |
+                docker buildx imagetools create \
+                  -t ghcr.io/${{ github.repository_owner }}/myapp:latest \
+                  ${{ needs.build.outputs.digest }}
+                  # Merges per-platform digests into one manifest list
+prevention:
+  - "Never use strategy.matrix to build separate platforms and push to the same tag — each push overwrites the previous."
+  - "Use a single build-push-action step with comma-separated platforms for most multi-platform use cases."
+  - "Validate multi-platform images after push with `docker buildx imagetools inspect ghcr.io/owner/image:tag` to confirm all platforms are present."
+  - "When matrix builds are needed for native performance, use push-by-digest and a fan-in merge job."
+docs:
+  - url: "https://docs.docker.com/build/ci/github-actions/multi-platform/"
+    label: "Docker: Multi-platform image with GitHub Actions"
+  - url: "https://github.com/docker/build-push-action"
+    label: "docker/build-push-action — multi-platform examples"
+  - url: "https://stackoverflow.com/questions/79315376/docker-multiplatform-image-pushed-successfully-to-ghcr-but-pulling-image-result"
+    label: "SO: Docker multiplatform image pushed successfully but pulling results in manifest not found"

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/silent-failures/docker-run-pipe-tee-exit-code-zero.yml

@@ -0,0 +1,99 @@
+id: silent-failures-026
+title: "Docker Run Exit Code Masked When Output Is Piped to tee"
+category: silent-failures
+severity: silent-failure
+tags:
+  - docker
+  - exit-code
+  - pipe
+  - tee
+  - bash
+  - pipefail
+patterns:
+  - regex: "docker run.*\\|.*tee"
+    flags: "i"
+  - regex: "PIPESTATUS|pipefail"
+    flags: "i"
+error_messages:
+  - "Pipe status: 0"
+  - "Exit status: 0"
+  - "The command succeeded."
+root_cause: |
+  When a `docker run` command is piped to `tee` for dual-output (file + console),
+  the shell's `$?` variable captures the exit code of the *last command in the
+  pipeline* — which is `tee`. Since `tee` always exits 0 (unless it cannot write
+  to the output file), the workflow step always reports success even when the
+  container process exits with a non-zero code.
+
+  Example:
+    docker run myimage pytest tests/ 2>&1 | tee output.txt
+    echo $?  # Always 0 — tee's exit code, not docker's
+
+  GitHub Actions enables `set -e` and `set -o pipefail` by default for bash steps,
+  but `pipefail` only propagates failures if the pipeline command itself fails.
+  When the output of `docker run` is piped, the runner still sees `tee`'s exit code
+  as the step's result.
+
+  `${PIPESTATUS[0]}` is the bash array of exit codes for each pipeline segment, but
+  it must be captured *immediately* after the pipeline — it is overwritten by the
+  next command.
+
+  Sources: stackoverflow.com/questions/79075923
+fix: |
+  Option 1 (Recommended): Capture the docker exit code via PIPESTATUS immediately
+  after the pipeline, before running any other command.
+
+  Option 2: Run docker without piping, capturing output to a variable first, then
+  echo it and write to file. This avoids the PIPESTATUS problem entirely.
+
+  Option 3: Enable `set -o pipefail` in the step shell (note: GitHub Actions bash
+  steps do NOT enable pipefail by default despite documentation implying otherwise —
+  test explicitly).
+fix_code:
+  - language: yaml
+    label: "Capture docker exit code via PIPESTATUS[0]"
+    code: |
+      - name: Run tests in Docker
+        run: |
+          docker run myimage pytest tests/ 2>&1 | tee output.txt
+          DOCKER_EXIT=${PIPESTATUS[0]}
+          # PIPESTATUS must be captured immediately after the pipeline
+          echo "Docker exit code: $DOCKER_EXIT"
+          if [ "$DOCKER_EXIT" -ne 0 ]; then
+            echo "Tests failed inside container."
+            exit "$DOCKER_EXIT"
+          fi
+  - language: yaml
+    label: "Avoid piping: capture output in variable, then write and echo"
+    code: |
+      - name: Run tests in Docker
+        run: |
+          # Capture output without piping — preserves $? correctly
+          docker_output=$(docker run myimage pytest tests/ 2>&1)
+          DOCKER_EXIT=$?
+          echo "$docker_output"          # Show in Actions log
+          echo "$docker_output" > output.txt  # Also write to file
+          if [ "$DOCKER_EXIT" -ne 0 ]; then
+            echo "Tests failed (exit $DOCKER_EXIT)"
+            exit "$DOCKER_EXIT"
+          fi
+  - language: yaml
+    label: "Use process substitution to write to file without a pipeline"
+    code: |
+      - name: Run tests in Docker
+        run: |
+          # tee via process substitution — preserves docker's exit code
+          docker run myimage pytest tests/ 2>&1 > >(tee output.txt)
+          # $? is now docker's exit code, not tee's
+prevention:
+  - "Never check $? after a piped command to determine success — always use ${PIPESTATUS[0]} or avoid piping."
+  - "Add an explicit exit-code check after any docker run step, especially when the step uses | tee or redirections."
+  - "Consider adding `set -o pipefail` at the top of multi-command run steps to catch pipeline failures automatically."
+  - "Test workflows with a deliberately failing container command to confirm the step actually fails as expected."
+docs:
+  - url: "https://www.gnu.org/software/bash/manual/bash.html#index-PIPESTATUS"
+    label: "Bash manual — PIPESTATUS"
+  - url: "https://stackoverflow.com/questions/79075923/how-can-i-get-the-error-codes-in-github-actions-shell-when-a-docker-run-command"
+    label: "SO: Get error codes in github-actions shell when docker run command fails while piping output"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions"
+    label: "GitHub Actions workflow commands"

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.18",
+  "version": "1.0.20",
   "description": "65+ real GitHub Actions errors, queryable by agents. MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",