@htekdev/actions-debugger 1.0.16 → 1.0.18

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/known-unsolved/no-automatic-job-retry.yml

@@ -0,0 +1,92 @@
+id: known-unsolved-019
+title: "No built-in automatic retry for individual failed jobs — only full workflow re-run or manual step"
+category: known-unsolved
+severity: limitation
+tags:
+  - retry
+  - flaky
+  - job
+  - re-run
+  - known-limitation
+  - matrix
+patterns:
+  - regex: "retry|re-run|rerun|flaky"
+    flags: "i"
+error_messages:
+  - "There is no native retry: N option for jobs in GitHub Actions"
+root_cause: |
+  GitHub Actions provides no built-in retry: count field at the job level. When a
+  job fails due to a flaky test, a transient network error, or an intermittent
+  service dependency, the only native options are: (1) manually re-run the failed
+  job via the UI or API, (2) re-run the entire workflow, or (3) add shell-level
+  retry loops inside run steps. There is no declarative way to say "retry this job
+  up to N times automatically before marking it as failed." This is a long-standing
+  platform limitation tracked in multiple GitHub Community discussions. The
+  workflow-level timeout-minutes and job-level timeout-minutes exist, but neither
+  provides automatic retry semantics. For matrix jobs, a single flaky matrix entry
+  failing causes the whole matrix (or the workflow, with default fail-fast:true) to
+  fail with no automatic per-matrix-slot retry.
+fix: |
+  Workarounds depend on the scope of flakiness. For step-level flakiness, use a
+  shell retry loop or the nick-fields/retry third-party action. For job-level
+  flakiness in CI, consider using the GitHub REST API with a calling orchestrator
+  workflow that re-dispatches on failure. For matrix flakiness, capture failed
+  matrix entries and dispatch a targeted follow-up workflow run. Manual re-run via
+  gh run rerun --failed is the simplest workaround for human-in-the-loop flows.
+fix_code:
+  - language: yaml
+    label: "Workaround — shell-level retry loop inside a run step"
+    code: |
+      steps:
+        - name: Flaky network step with retry
+          run: |
+            for i in 1 2 3; do
+              curl -sf https://api.example.com/deploy && break
+              echo "Attempt $i failed, retrying in 10s..."
+              sleep 10
+            done
+  - language: yaml
+    label: "Workaround — nick-fields/retry action for step-level retry"
+    code: |
+      steps:
+        - name: Retry flaky step
+          uses: nick-fields/retry@v3
+          with:
+            timeout_minutes: 10
+            max_attempts: 3
+            command: npm test
+  - language: yaml
+    label: "Workaround — re-run only failed jobs via gh CLI after workflow completes"
+    code: |
+      # In a post-pipeline script or calling workflow:
+      # gh run rerun <RUN_ID> --failed  re-runs only the jobs that failed
+      # Automate this with an on.workflow_run trigger checking conclusion == 'failure'
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+
+      jobs:
+        auto-retry:
+          if: github.event.workflow_run.conclusion == 'failure'
+          runs-on: ubuntu-latest
+          steps:
+            - name: Re-run failed jobs once
+              env:
+                GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+              run: |
+                gh run rerun ${{ github.event.workflow_run.id }} --failed --repo ${{ github.repository }}
+prevention:
+  - "Design tests and deployment steps to be idempotent so manual re-runs are safe"
+  - "Use step-level retry wrappers (shell loops or nick-fields/retry) for known-flaky external calls"
+  - "Separate flaky integration tests into their own workflow so re-runs are scoped and cheaper"
+  - "Track flakiness metrics; persistent flakiness signals a real bug, not just a retry need"
+docs:
+  - url: "https://github.com/orgs/community/discussions/26186"
+    label: "GitHub Community — native job retry support request"
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/re-running-workflows-and-jobs"
+    label: "Re-running workflows and jobs — GitHub Actions"
+  - url: "https://github.com/nick-fields/retry"
+    label: "nick-fields/retry — step-level retry action (third-party workaround)"
+  - url: "https://cli.github.com/manual/gh_run_rerun"
+    label: "gh run rerun — GitHub CLI reference"

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/github-env-same-step-not-available.yml

@@ -0,0 +1,72 @@
+id: silent-failures-024
+title: "GITHUB_ENV variable written in a step is not available within the same step"
+category: silent-failures
+severity: silent-failure
+tags:
+  - GITHUB_ENV
+  - environment-variables
+  - step-ordering
+  - run
+  - same-step
+patterns:
+  - regex: "GITHUB_ENV[^\\n]*\\n[^\\n]*\\$\\{?[A-Z_][A-Z0-9_]*\\}?"
+    flags: "ms"
+  - regex: "echo\\s+[\"']?[A-Z_][A-Z0-9_]*=[^\"'\\n]+[\"']?\\s*>>\\s*\\$GITHUB_ENV"
+    flags: "i"
+error_messages:
+  - "echo MY_VAR=value >> $GITHUB_ENV"
+root_cause: |
+  Writes to $GITHUB_ENV (appending NAME=value lines to the runner's environment file)
+  take effect for all SUBSEQUENT steps in the same job, but NOT for the current
+  step's run block. The Actions runner reads the environment file once at the start
+  of each step, before the run block executes. Any $GITHUB_ENV writes made during
+  that run block are not re-read until the next step begins. Consequently, if a run
+  block writes `echo "BUILD_ID=abc" >> $GITHUB_ENV` and then immediately references
+  `$BUILD_ID` later in the same run block, the variable is empty. No error or warning
+  is emitted — the reference silently evaluates to an empty string. The identical
+  delayed-effect behavior applies to $GITHUB_PATH: path entries added in one step
+  are only visible in the PATH of subsequent steps.
+fix: |
+  Split the write and the read into separate steps. If you need the value within the
+  same shell invocation, use a native shell variable assignment (VAR=value) for
+  immediate access and still write to $GITHUB_ENV if the value is needed by later
+  steps. Do not rely on $GITHUB_ENV for intra-step communication.
+fix_code:
+  - language: yaml
+    label: "Wrong — reference GITHUB_ENV variable in the same step that writes it"
+    code: |
+      steps:
+        - name: Set and use variable (BROKEN — BUILD_ID is empty)
+          run: |
+            echo "BUILD_ID=abc123" >> $GITHUB_ENV
+            echo "Build ID is: $BUILD_ID"  # Empty — GITHUB_ENV not re-read mid-step
+  - language: yaml
+    label: "Correct — read the exported variable in the following step"
+    code: |
+      steps:
+        - name: Export variable
+          run: echo "BUILD_ID=abc123" >> $GITHUB_ENV
+
+        - name: Use exported variable
+          run: echo "Build ID is: $BUILD_ID"  # Available here — next step reads GITHUB_ENV
+  - language: yaml
+    label: "Correct — use a shell variable for same-step access, also export for later steps"
+    code: |
+      steps:
+        - name: Compute and export build ID
+          run: |
+            BUILD_ID=$(git rev-parse --short HEAD)
+            echo "BUILD_ID=${BUILD_ID}" >> $GITHUB_ENV   # Export for later steps
+            echo "Build ID is: ${BUILD_ID}"               # Shell var — available immediately
+prevention:
+  - "Never reference a variable by its GITHUB_ENV name ($VAR_NAME) in the same run block that writes it"
+  - "Use native shell variables (VAR=value; echo $VAR) for same-step access; only use GITHUB_ENV for cross-step sharing"
+  - "The same rule applies to $GITHUB_PATH — path additions take effect in the next step, not the current one"
+  - "If a step relies on a GITHUB_ENV variable set by a prior step in the same run, ensure step ordering is correct"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#passing-a-value-between-steps"
+    label: "Passing values between steps using GITHUB_ENV — GitHub Actions"
+  - url: "https://github.com/orgs/community/discussions/26672"
+    label: "GitHub Community — GITHUB_ENV variable not available in same step it is written"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-an-environment-variable"
+    label: "Setting an environment variable via workflow commands — GitHub Actions"

package/errors/triggers/push-pull-request-duplicate-runs.yml

@@ -0,0 +1,74 @@
+id: triggers-017
+title: "push and pull_request events both fire for same-repo PR branches causing duplicate CI runs"
+category: triggers
+severity: warning
+tags:
+  - push
+  - pull_request
+  - duplicate-runs
+  - concurrency
+  - same-repo
+  - branch
+patterns:
+  - regex: "on:\\s*\\n\\s+(push|pull_request):"
+    flags: "ms"
+error_messages:
+  - "Duplicate workflow runs triggered for the same commit SHA"
+  - "Two simultaneous CI runs on the same branch"
+root_cause: |
+  When a developer pushes to a branch that has an open pull request within the same
+  repository (not a fork), both the push event and the pull_request event (types:
+  [synchronize]) fire independently for the same commit SHA. This creates two
+  separate workflow runs executing identical CI checks simultaneously. For fork PRs
+  only the pull_request event fires (the fork push doesn't trigger the base repo),
+  so duplication only affects same-repository branches. The redundant run wastes
+  billed minutes, creates confusing duplicate status check entries on the PR, and
+  can cause race conditions in deployment or release workflows where two runs race
+  to update the same environment.
+fix: |
+  For workflows intended purely as PR checks, use only on.pull_request and remove
+  the push trigger. If the same workflow needs to run both on PRs and on direct
+  pushes to main/trunk (post-merge), filter with branches: so they don't overlap.
+  Adding a concurrency group keyed on github.ref or github.head_ref automatically
+  cancels the slower duplicate run when both triggers must remain.
+fix_code:
+  - language: yaml
+    label: "Option 1 — separate triggers so they do not overlap"
+    code: |
+      on:
+        # PR CI: only pull_request covers commits pushed to the PR branch
+        pull_request:
+          branches: [main]
+        # Post-merge CI: only the push to main after merging
+        push:
+          branches: [main]
+      # This way a push to a feature branch triggers pull_request ONLY,
+      # and a merge to main triggers push ONLY — no duplicates.
+  - language: yaml
+    label: "Option 2 — concurrency group to cancel the slower duplicate"
+    code: |
+      on:
+        push:
+          branches-ignore: [main]
+        pull_request:
+          branches: [main]
+
+      concurrency:
+        group: ci-${{ github.head_ref || github.ref }}
+        cancel-in-progress: true
+      # When both push and pull_request fire for the same branch, the second
+      # run cancels the first, leaving only one active run per branch.
+prevention:
+  - "Audit every workflow with both on.push and on.pull_request — verify the branch filters don't overlap for same-repo contributors"
+  - "For PR validation CI, prefer on.pull_request only; add a separate on.push.branches: [main] for post-merge checks"
+  - "Always add a concurrency group when both push and pull_request triggers are needed to prevent redundant runs"
+  - "Check your Actions billing dashboard for unexpectedly doubled minute usage as a signal for duplicate trigger overlap"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request"
+    label: "pull_request event — GitHub Actions documentation"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push"
+    label: "push event — GitHub Actions documentation"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs"
+    label: "Controlling concurrency of workflows and jobs — GitHub Actions"
+  - url: "https://github.com/orgs/community/discussions/26284"
+    label: "GitHub Community — avoiding duplicate workflow runs on push and pull_request"

package/errors/triggers/workflow-dispatch-inputs-string-coercion.yml

@@ -0,0 +1,89 @@
+id: triggers-016
+title: "workflow_dispatch inputs are always string type regardless of declared type"
+category: triggers
+severity: silent-failure
+tags:
+  - workflow_dispatch
+  - inputs
+  - type-coercion
+  - boolean
+  - number
+  - expression
+patterns:
+  - regex: "inputs\\.[a-zA-Z_][a-zA-Z0-9_]*\\s*==\\s*(true|false)"
+    flags: "i"
+  - regex: "inputs\\.[a-zA-Z_][a-zA-Z0-9_]*\\s*[><!]=?\\s*[0-9]"
+    flags: "i"
+error_messages:
+  - "if: ${{ inputs.enable_debug == true }}"
+  - "if: ${{ inputs.retry_count > 3 }}"
+  - "if: ${{ inputs.deploy == false }}"
+root_cause: |
+  All workflow_dispatch input values are delivered as strings at runtime, regardless
+  of the type: boolean or type: number declaration in the workflow YAML. The type
+  declaration controls the GitHub UI widget (checkbox vs text field) but does NOT
+  change the runtime data type. Comparing inputs.my_flag == true evaluates as
+  string('true') == boolean(true) which is always false. Similarly, arithmetic
+  comparisons like inputs.count > 3 perform lexicographic string comparison, not
+  numeric comparison. This is documented in GitHub Actions docs but commonly missed
+  by developers relying on the YAML type declaration to enforce runtime types.
+  The same caveat applies to inputs passed via the GitHub REST API and GitHub CLI.
+fix: |
+  Compare boolean inputs against the string 'true' or 'false'. For numeric inputs,
+  wrap with fromJSON() before arithmetic comparison. The expression
+  inputs.enable_debug == 'true' correctly evaluates when the checkbox is checked
+  in the GitHub UI or when the value 'true' is passed via the API.
+fix_code:
+  - language: yaml
+    label: "Boolean input — compare against string literal 'true'"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            enable_debug:
+              type: boolean
+              description: "Enable debug mode"
+              default: false
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Debug step
+              # WRONG: inputs.enable_debug == true  (string vs boolean, always false)
+              # CORRECT: compare against string
+              if: inputs.enable_debug == 'true'
+              run: echo "Debug mode enabled"
+  - language: yaml
+    label: "Number input — use fromJSON() for numeric comparison"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            retry_count:
+              type: number
+              description: "Number of retries"
+              default: 3
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: High-retry warning
+              # WRONG: inputs.retry_count > 5  (string comparison, '6' > '5' is true but '10' > '5' is false lexicographically)
+              # CORRECT: cast to number first
+              if: fromJSON(inputs.retry_count) > 5
+              run: echo "Warning: high retry count configured"
+prevention:
+  - "Always compare workflow_dispatch boolean inputs against the string 'true' or 'false', never native boolean literals"
+  - "Use fromJSON(inputs.my_number) before any arithmetic or numeric comparison on number inputs"
+  - "Add an early diagnostic step echoing ${{ toJSON(inputs) }} to inspect actual runtime types during development"
+  - "Document in workflow comments that all workflow_dispatch inputs are strings at runtime, regardless of declared type"
+  - "When passing inputs via API or gh CLI, always pass boolean values as the strings 'true' or 'false'"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#providing-inputs"
+    label: "workflow_dispatch inputs documentation — GitHub Actions"
+  - url: "https://github.com/actions/runner/issues/1483"
+    label: "actions/runner#1483 — Boolean workflow_dispatch inputs treated as strings"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#fromjson"
+    label: "fromJSON() expression function — GitHub Actions"

package/package.json

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