@htekdev/actions-debugger 1.0.96 → 1.0.98

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

@@ -0,0 +1,102 @@
+id: caching-artifacts-054
+title: "upload-artifact@v4 Rejects Artifact Names Containing Special Characters"
+category: caching-artifacts
+severity: error
+tags:
+  - upload-artifact
+  - artifact-name
+  - v4-migration
+  - special-characters
+  - validation
+  - branch-name
+patterns:
+  - regex: 'The artifact name is not valid'
+    flags: "i"
+  - regex: 'Artifact name .+ is not valid'
+    flags: "i"
+  - regex: 'characters are not allowed in artifact names?'
+    flags: "i"
+error_messages:
+  - "Error: The artifact name is not valid. The following characters are not allowed in artifact names: \\ / : * ? \" < > |"
+  - "Artifact name 'feature/login-ui' is not valid. The following characters are not allowed: /"
+  - "Error: An artifact name must not contain the following characters: \\ / : * ? \" < > |"
+root_cause: |
+  actions/upload-artifact@v4 introduced strict server-side validation of
+  artifact names. The following characters are now explicitly rejected because
+  they are illegal in file or directory names on the artifact storage backend:
+
+    \ / : * ? " < > |
+
+  In v3, artifact names were either silently sanitized or accepted with these
+  characters (depending on the storage backend behavior). v4 fails hard with a
+  clear error.
+
+  The most common failure mode is dynamic artifact names constructed from:
+  - Branch names: github.ref_name or github.head_ref (contain /)
+  - Pull request titles: github.event.pull_request.title (contain : / " etc.)
+  - Matrix values: matrix.os or matrix.target (may contain : on Windows paths)
+  - Composite keys: combining multiple context values with : as separator
+
+  Example patterns that break:
+    name: build-${{ github.ref_name }}         # "feature/login" contains /
+    name: results-${{ matrix.os }}             # "windows-latest" is fine but
+                                               # some custom os values may not be
+    name: ${{ github.event.pull_request.title }} # PR titles can contain any char
+fix: |
+  Sanitize the artifact name before passing it to upload-artifact. Replace or
+  strip disallowed characters using a shell substitution or a prior step that
+  outputs a safe name. The simplest approach is replacing / with - or _.
+fix_code:
+  - language: yaml
+    label: "Sanitize branch name artifact using shell substitution"
+    code: |
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          # Replace / with - to make branch name safe
+          name: build-${{ github.ref_name && replace(github.ref_name, '/', '-') || 'main' }}
+          path: dist/
+
+  - language: yaml
+    label: "Compute safe artifact name in prior step output"
+    code: |
+      - name: Compute safe artifact name
+        id: artifact-name
+        run: |
+          # Strip or replace characters not allowed in artifact names: \ / : * ? " < > |
+          SAFE_NAME=$(echo "${{ github.ref_name }}" | tr '/:*?"<>|\\' '-')
+          echo "name=build-${SAFE_NAME}" >> $GITHUB_OUTPUT
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ steps.artifact-name.outputs.name }}
+          path: dist/
+
+  - language: yaml
+    label: "Use matrix hash or index for safe matrix artifact names"
+    code: |
+      strategy:
+        matrix:
+          config: [debug, release]
+          os: [ubuntu-latest, windows-latest, macos-latest]
+
+      steps:
+        - name: Upload matrix artifact
+          uses: actions/upload-artifact@v4
+          with:
+            # Safe: all matrix.* values here contain no special chars
+            name: build-${{ matrix.os }}-${{ matrix.config }}
+            path: dist/
+prevention:
+  - "Never pass github.ref_name, github.head_ref, or PR titles directly as artifact names without sanitization."
+  - "When constructing dynamic artifact names, run them through tr or sed to replace / : * ? \" < > | \\ with - or _."
+  - "Use actionlint or a pre-commit hook to flag unescaped context expressions in artifact name: fields."
+  - "Consider using a matrix index or a hash of the artifact key for truly collision-safe names."
+docs:
+  - url: "https://github.com/actions/upload-artifact/releases/tag/v4.0.0"
+    label: "upload-artifact v4.0.0 release notes — breaking changes"
+  - url: "https://github.com/actions/upload-artifact#inputs"
+    label: "upload-artifact README — name input and allowed characters"
+  - url: "https://stackoverflow.com/questions/77975069"
+    label: "SO#77975069 — upload-artifact v4 artifact name is not valid"

package/errors/known-unsolved/reusable-workflow-github-event-is-workflow-call-event.yml

@@ -0,0 +1,112 @@
+id: known-unsolved-054
+title: 'github.event in a reusable workflow is the workflow_call event, not the caller event'
+category: known-unsolved
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - workflow-call
+  - github-event
+  - context
+  - inputs
+  - github-context
+patterns:
+  - regex: 'github\.event\.(pull_request|commits|release|head_commit)\b'
+    flags: 'i'
+error_messages: []
+root_cause: |
+  When a caller workflow invokes a reusable workflow via jobs.<id>.uses, the
+  github.event context inside the callee is the workflow_call event object,
+  NOT the triggering event (push, pull_request, schedule, etc.) of the caller.
+
+  All event-specific payload fields are undefined inside the reusable workflow
+  and evaluate to empty string or null without any error:
+  - github.event.pull_request (undefined — returns null)
+  - github.event.commits (undefined — returns null)
+  - github.event.release (undefined — returns null)
+  - github.event.head_commit (undefined — returns null)
+  - github.event.inputs (undefined — use inputs context instead)
+
+  Additionally, github.event_name inside the callee always returns 'workflow_call',
+  regardless of what event triggered the caller.
+
+  Importantly, github.ref, github.sha, and github.actor DO retain the caller's
+  values inside the callee — it is specifically github.event and github.event_name
+  that reflect the workflow_call context, not the caller's triggering event.
+
+  This catches developers by surprise when refactoring inline jobs into reusable
+  workflows: the refactored callee silently loses access to the event payload it
+  previously used, with no validation error or warning at parse time or runtime.
+
+  This is by design — reusable workflows execute as independent workflow_call
+  events and there is no mechanism to inherit the caller's event context. GitHub
+  has confirmed this will not change.
+fix: |
+  There is no workaround that exposes the caller's github.event inside the callee.
+  The required approach is to declare all needed event data as explicit inputs:
+  in the reusable workflow and forward them via with: in the caller.
+
+  github.ref, github.sha, and github.actor are available in the callee without
+  any explicit forwarding — they are inherited automatically from the caller context.
+fix_code:
+  - language: yaml
+    label: 'Wrong — accessing caller event payload inside reusable workflow (silently empty)'
+    code: |
+      # .github/workflows/reusable.yml — these are all EMPTY inside the callee
+      on:
+        workflow_call:
+
+      jobs:
+        process:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "PR = ${{ github.event.pull_request.number }}"  # null
+            - run: echo "Event = ${{ github.event_name }}"               # 'workflow_call'
+            - run: echo "Commit = ${{ github.event.head_commit.message }}" # null
+  - language: yaml
+    label: 'Correct — declare inputs in callee and forward event data from caller'
+    code: |
+      # .github/workflows/reusable.yml — declare needed event data as inputs
+      on:
+        workflow_call:
+          inputs:
+            pr_number:
+              type: number
+              default: 0
+              description: 'Pull request number from github.event.pull_request.number'
+            triggering_event:
+              type: string
+              required: true
+              description: 'The caller event name (github.event_name)'
+
+      jobs:
+        process:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "PR = ${{ inputs.pr_number }}"
+            - run: echo "Triggered by = ${{ inputs.triggering_event }}"
+            # github.ref and github.sha are safe to use directly — they are inherited
+            - run: echo "SHA = ${{ github.sha }}"
+
+      # ---- CALLER WORKFLOW ----
+      # .github/workflows/caller.yml — forward event data via with:
+      on: [push, pull_request]
+
+      jobs:
+        call-reusable:
+          uses: ./.github/workflows/reusable.yml
+          with:
+            pr_number: ${{ github.event.pull_request.number || 0 }}
+            triggering_event: ${{ github.event_name }}
+prevention:
+  - 'Never access github.event.* fields directly inside a reusable workflow — they will always be empty'
+  - 'github.event_name inside a reusable workflow always returns workflow_call, not the caller event'
+  - 'Declare all required event data as explicit workflow_call inputs and forward with with: in the caller'
+  - 'github.ref, github.sha, and github.actor are inherited from the caller and are safe to use'
+  - 'Add a comment in the reusable workflow reminding contributors not to use github.event directly'
+docs:
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#limitations'
+    label: 'GitHub Docs — Reusing workflows: Limitations'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#github-context'
+    label: 'GitHub Docs — github context'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#passing-inputs-and-secrets-to-a-called-workflow'
+    label: 'GitHub Docs — Passing inputs and secrets to a called workflow'

package/errors/permissions-auth/oidc-token-rate-limited-large-parallel-matrix.yml

@@ -0,0 +1,114 @@
+id: permissions-auth-056
+title: 'OIDC token requests rate-limited in large parallel matrix — random 429 job failures'
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - id-token
+  - rate-limit
+  - matrix
+  - parallel
+  - aws
+  - gcp
+  - azure
+patterns:
+  - regex: 'Failed to get ID token.*429'
+    flags: 'i'
+  - regex: 'ACTIONS_ID_TOKEN_REQUEST_URL.*429'
+    flags: 'i'
+  - regex: 'No ID token is available.*rate.limit'
+    flags: 'i'
+error_messages:
+  - "Error: Failed to get ID token: Request failed with status code 429"
+  - "Error: Failed to get ID token: Error code: 429"
+root_cause: |
+  GitHub's OIDC token endpoint (ACTIONS_ID_TOKEN_REQUEST_URL) has per-workflow-run
+  rate limits on simultaneous token requests. When a large matrix workflow spawns
+  many parallel jobs (typically 20+) that all request OIDC tokens at the start of
+  their runs, the burst of simultaneous requests can exceed the endpoint's rate
+  limit, and some jobs receive HTTP 429 responses.
+
+  Cloud provider actions that call the OIDC endpoint internally during setup
+  are affected:
+  - aws-actions/configure-aws-credentials
+  - google-github-actions/auth
+  - azure/login (with OIDC federated credentials)
+
+  In a large matrix, all legs start within seconds of each other, creating a
+  simultaneous burst that exceeds the endpoint limit. The failure is
+  non-deterministic: some jobs succeed and some fail on any given run. Manually
+  re-running the failed jobs typically succeeds because the burst window has
+  passed. This intermittent behavior makes the 429 root cause difficult to
+  diagnose without inspecting verbose action output for the HTTP status code.
+
+  The rate limit is enforced per workflow run, not per repository or per user.
+  Actions that include built-in retry logic may mask the error by successfully
+  retrying, but add latency to affected jobs.
+fix: |
+  Reduce parallel OIDC token requests by setting max-parallel on the matrix
+  strategy. A value between 5 and 15 typically prevents rate limit breaches
+  while still providing meaningful parallelism.
+
+  Alternatively, restructure the workflow to acquire a single OIDC-derived
+  credential in a setup job and pass it as a job output to downstream matrix
+  jobs — but this must be done carefully to avoid exposing short-lived tokens
+  in workflow logs. Check the cloud provider's documentation for recommended
+  token-sharing patterns.
+
+  Enable step debug logging (ACTIONS_STEP_DEBUG secret set to 'true') to
+  confirm the 429 root cause when diagnosing intermittent OIDC failures.
+fix_code:
+  - language: yaml
+    label: 'Set max-parallel to prevent simultaneous OIDC token request burst'
+    code: |
+      jobs:
+        deploy:
+          strategy:
+            matrix:
+              region: [us-east-1, us-west-2, eu-west-1, ap-southeast-1, ap-northeast-1,
+                       sa-east-1, ca-central-1, ap-south-1, ap-east-1, eu-central-1]
+            max-parallel: 5  # Prevents simultaneous OIDC token burst
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write
+            contents: read
+          steps:
+            - name: Configure AWS credentials
+              uses: aws-actions/configure-aws-credentials@v4
+              with:
+                role-to-assume: arn:aws:iam::123456789:role/deploy-${{ matrix.region }}
+                aws-region: ${{ matrix.region }}
+            - name: Deploy
+              run: ./scripts/deploy.sh ${{ matrix.region }}
+  - language: yaml
+    label: 'Enable OIDC debug logging to confirm 429 rate limit as root cause'
+    code: |
+      # Add this secret to the repository: ACTIONS_STEP_DEBUG = true
+      # Then re-run the failing workflow and check step logs for:
+      # "Request failed with status code 429"
+      # in the cloud auth action's output to confirm rate limiting.
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write
+          steps:
+            - name: Configure credentials (verbose for debugging)
+              uses: aws-actions/configure-aws-credentials@v4
+              with:
+                role-to-assume: arn:aws:iam::123456789:role/ci-role
+                aws-region: us-east-1
+prevention:
+  - 'Use max-parallel on matrix strategies that use OIDC authentication to limit burst requests'
+  - 'Enable ACTIONS_STEP_DEBUG secret to see HTTP status codes in cloud auth action logs'
+  - 'Treat intermittent OIDC failures in large matrix workflows as a 429 rate limit until proven otherwise'
+  - 'Check whether the cloud auth action has built-in retry logic — some versions retry automatically'
+  - 'Consider staggering matrix jobs with a sleep step if max-parallel alone does not resolve the issue'
+docs:
+  - 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/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymax-parallel'
+    label: 'GitHub Docs — jobs.<job_id>.strategy.max-parallel'
+  - url: 'https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging'
+    label: 'GitHub Docs — Enabling debug logging'

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

@@ -0,0 +1,110 @@
+id: permissions-auth-055
+title: "GITHUB_TOKEN Cannot Push to .github/workflows/ — Requires PAT with workflow Scope"
+category: permissions-auth
+severity: error
+tags:
+  - github-token
+  - workflow-files
+  - workflow-scope
+  - pat
+  - contents-write
+  - self-modifying-workflow
+patterns:
+  - regex: 'refusing to allow .+ to create or update workflow .+\.yml'
+    flags: "i"
+  - regex: 'refusing to allow a GitHub Actions App to create or update workflow'
+    flags: "i"
+  - regex: 'GH006.*refusing to allow.*workflow'
+    flags: "i"
+error_messages:
+  - "refusing to allow a GitHub Actions App to create or update workflow .github/workflows/ci.yml"
+  - "remote: error: GH006: Protected branch update failed for refs/heads/main. remote: error: refusing to allow a GitHub Actions App to create or update workflow .github/workflows/deploy.yml"
+  - "refusing to allow GitHub Actions Bot to update .github/workflows/release.yml"
+  - "remote: Resolving deltas: 100% (1/1), done. remote: error: refusing to allow a GitHub Actions App to create or update workflow"
+root_cause: |
+  GitHub enforces a hard server-side restriction preventing GITHUB_TOKEN from
+  creating or modifying files under .github/workflows/. This restriction applies
+  regardless of the permissions: block in the workflow. Even with
+  permissions: contents: write, GITHUB_TOKEN will be rejected when the push
+  includes changes to workflow files.
+
+  This security control exists to prevent privilege escalation: a compromised or
+  malicious workflow cannot modify itself or other workflows to gain additional
+  permissions or persist access. The restriction is enforced at the remote push
+  validation layer, not by the GitHub Actions runtime.
+
+  Common scenarios that trigger this:
+  - Automated dependency update workflows that pin action versions
+    (e.g., actions/checkout@v3 -> @v4) in workflow files
+  - Workflow generators that create or update .github/workflows/*.yml
+  - Renovate, Dependabot, or custom bots using GITHUB_TOKEN to update action refs
+  - Release automation that stamps version information into workflow files
+  - Repository template sync tools that propagate workflow updates
+
+  Note: fine-grained PATs WITH the repository contents:write permission DO allow
+  workflow file updates (this restriction only applies to GITHUB_TOKEN
+  specifically, not all tokens).
+fix: |
+  Use a Personal Access Token (classic PAT) with the workflow scope, a
+  fine-grained PAT with the repository contents:write permission, or a GitHub
+  App with the workflows repository permission. Store the token as a repository
+  or organization secret and use it in place of GITHUB_TOKEN for the checkout
+  or push steps.
+fix_code:
+  - language: yaml
+    label: "Use PAT with workflow scope via checkout persist-credentials"
+    code: |
+      jobs:
+        update-workflow:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                # Use a PAT with workflow scope — GITHUB_TOKEN cannot push workflow files
+                token: ${{ secrets.WORKFLOW_PAT }}
+
+            - name: Update workflow file
+              run: |
+                sed -i 's/actions\/checkout@v3/actions\/checkout@v4/g' .github/workflows/*.yml
+
+            - name: Commit and push workflow changes
+              env:
+                GH_TOKEN: ${{ secrets.WORKFLOW_PAT }}
+              run: |
+                echo "Commit workflow changes using PAT token"
+                # repository operations using the authenticated token
+
+  - language: yaml
+    label: "Use GitHub App token with workflows permission"
+    code: |
+      jobs:
+        update-workflow:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/create-github-app-token@v1
+              id: app-token
+              with:
+                app-id: ${{ secrets.APP_ID }}
+                private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+            - uses: actions/checkout@v4
+              with:
+                token: ${{ steps.app-token.outputs.token }}
+
+            - name: Modify workflow file and push
+              env:
+                GH_TOKEN: ${{ steps.app-token.outputs.token }}
+              run: |
+                echo "Commit workflow changes via GitHub App token"
+prevention:
+  - "Store a classic PAT with the workflow scope as a secret (e.g., WORKFLOW_PAT) for any job that writes to .github/workflows/."
+  - "Do not expect permissions: contents: write to grant GITHUB_TOKEN the ability to modify workflow files — it will always be rejected."
+  - "Use GitHub Apps with the workflows repository permission for scalable, org-wide workflow automation."
+  - "Prefer Renovate or Dependabot (which use their own token/app with workflow scope) for automated action version pinning."
+docs:
+  - url: "https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic"
+    label: "GitHub Docs — Classic PAT workflow scope"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token"
+    label: "GitHub Docs — GITHUB_TOKEN permissions"
+  - url: "https://stackoverflow.com/questions/64059610"
+    label: "SO#64059610 — refusing to allow GitHub Actions App to create or update workflow"

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

@@ -0,0 +1,97 @@
+id: permissions-auth-057
+title: "gh CLI Uses GITHUB_TOKEN Env Variable, Not actions/checkout Custom Token"
+category: permissions-auth
+severity: silent-failure
+tags:
+  - gh-cli
+  - GITHUB_TOKEN
+  - checkout
+  - PAT
+  - token-scope
+patterns:
+  - regex: 'Resource not accessible by integration'
+    flags: "i"
+  - regex: 'gh:.*HTTP 403'
+    flags: "i"
+  - regex: 'gh:.*could not resolve to a node'
+    flags: "i"
+error_messages:
+  - "gh: Resource not accessible by integration (HTTP 403)"
+  - "remote: Permission to org/repo.git denied to github-actions[bot]."
+  - "gh: GraphQL: Could not resolve to a node with the global id of ''"
+root_cause: |
+  When `actions/checkout` is configured with a custom `token:` (e.g., a PAT or
+  GitHub App installation token), the custom token is written into the local
+  git credential helper so that git operations (push, fetch) authenticate with
+  the custom token.
+
+  However, the `gh` CLI does NOT read from the git credential helper. It resolves
+  authentication by checking these environment variables in priority order:
+    1. `GH_TOKEN`
+    2. `GITHUB_TOKEN`
+    3. System keychain / credential store (unavailable on hosted runners)
+
+  GitHub Actions always sets `GITHUB_TOKEN` to the default job token, regardless
+  of any custom token supplied to `actions/checkout`. When a step uses `gh` CLI
+  without an explicit `GH_TOKEN`, it picks up the default `GITHUB_TOKEN` which
+  may lack the required scopes (e.g., packages:write, org membership, cross-repo
+  access) — producing a 403 or permission error that appears to contradict the
+  checkout step succeeding with the PAT.
+
+  This mismatch is especially confusing because `git push` (using credentials
+  from checkout) succeeds while `gh pr create` or `gh release create` (using
+  GITHUB_TOKEN) fails in the same job.
+fix: |
+  Explicitly pass the custom token to `gh` via the `GH_TOKEN` or `GITHUB_TOKEN`
+  environment variable. Do not rely on `actions/checkout token:` to authenticate
+  `gh` CLI.
+
+  Setting `GH_TOKEN` at the step or job level is preferred as it keeps the scope
+  limited to where the elevated token is needed.
+fix_code:
+  - language: yaml
+    label: "Explicitly set GH_TOKEN for gh CLI steps"
+    code: |
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                # Custom token sets git credentials — does NOT affect gh CLI
+                token: ${{ secrets.ORG_PAT }}
+
+            - name: Create GitHub release
+              # gh reads GH_TOKEN (not checkout token) — pass it explicitly
+              env:
+                GH_TOKEN: ${{ secrets.ORG_PAT }}
+              run: |
+                gh release create v1.0.0 --title "v1.0.0" --generate-notes
+  - language: yaml
+    label: "Set GITHUB_TOKEN at job level to override for all gh CLI steps"
+    code: |
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          # Override GITHUB_TOKEN for the entire job so all gh steps use the PAT
+          env:
+            GITHUB_TOKEN: ${{ secrets.ORG_PAT }}
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                token: ${{ secrets.ORG_PAT }}
+            - run: gh pr create --title "Automated PR" --body "Auto-generated"
+prevention:
+  - "Always check which token gh CLI is using — it reads GH_TOKEN or GITHUB_TOKEN, not git credentials set by actions/checkout."
+  - "Set GH_TOKEN or GITHUB_TOKEN explicitly in env: blocks for any step that uses gh CLI with elevated permissions."
+  - "Use permissions: at the job level to grant additional scopes to the default GITHUB_TOKEN before reaching for a PAT."
+  - "When using a custom checkout token for git operations, remember gh CLI still needs GH_TOKEN set separately."
+docs:
+  - url: "https://cli.github.com/manual/gh_help_environment"
+    label: "gh CLI — GH_TOKEN environment variable"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication"
+    label: "GitHub Docs — GITHUB_TOKEN automatic authentication"
+  - url: "https://github.com/cli/cli/issues/2534"
+    label: "cli/cli#2534 — gh CLI ignores git credential helper token"
+  - url: "https://github.com/actions/checkout/issues/1168"
+    label: "actions/checkout#1168 — Custom token not used by gh CLI"

package/errors/runner-environment/runner-environment-164.yml

@@ -0,0 +1,89 @@
+id: runner-environment-164
+title: "setup-python python-version-file Fails with pyenv Pre-Release Version Notation"
+category: runner-environment
+severity: error
+tags:
+  - setup-python
+  - python-version-file
+  - pyenv
+  - pre-release
+  - version-format
+patterns:
+  - regex: 'Version \d+\.\d+\.\d+[ab]\d+ with arch .* not found'
+    flags: "i"
+  - regex: 'No available version found for [\d.]+[ab]'
+    flags: "i"
+  - regex: 'python-version-file.*\.python-version'
+    flags: "i"
+error_messages:
+  - "Version 3.13.0a4 with arch x64 not found"
+  - "Version 3.14.0b2 with arch x64 not found"
+  - "No available version found for 3.13.0a1"
+  - "The version '3.13.0rc1' with architecture 'x64' was not found."
+root_cause: |
+  pyenv-style `.python-version` files use native Python pre-release notation:
+    - `3.13.0a4`  (alpha 4)
+    - `3.14.0b2`  (beta 2)
+    - `3.13.0rc1` (release candidate 1)
+
+  `actions/setup-python` looks up versions using semver-style notation in the
+  GitHub toolcache, where pre-releases are labeled differently:
+    - `3.13.0-alpha.4`
+    - `3.14.0-beta.2`
+    - `3.13.0-rc.1`
+
+  When setup-python reads a `.python-version` file containing pyenv-style
+  notation (e.g., `3.13.0a4`), it cannot find a matching toolcache entry and
+  fails with "Version not found". Stable releases (e.g., `3.11.5`, `3.12.3`)
+  are unaffected because their notation is identical in both conventions.
+
+  This commonly surprises developers who pin a pre-release Python locally for
+  testing using pyenv and commit the `.python-version` file expecting CI to
+  use the same version.
+fix: |
+  Convert the `.python-version` file to semver notation for pre-releases, or
+  specify the Python version directly in the workflow using `python-version:`
+  to avoid relying on the file format.
+
+  For CI purposes, pinning to a stable minor version (e.g., `3.13`) is usually
+  sufficient and avoids both the notation mismatch and toolcache fallback issues.
+fix_code:
+  - language: yaml
+    label: "Use semver notation in .python-version for pre-releases"
+    code: |
+      # .python-version — use semver, not pyenv pre-release notation
+      #
+      # Wrong (pyenv style):   3.13.0a4
+      # Correct (semver style): 3.13.0-alpha.4
+      #
+      # Other mappings:
+      #   3.14.0b2  →  3.14.0-beta.2
+      #   3.13.0rc1 →  3.13.0-rc.1
+
+      # Workflow using the corrected file:
+      - uses: actions/setup-python@v5
+        with:
+          python-version-file: '.python-version'
+          allow-prereleases: true  # Required for any pre-release version
+  - language: yaml
+    label: "Pin version directly in workflow to bypass file format issues"
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          # Use stable minor version — avoids pre-release notation issues
+          python-version: '3.13'
+          # Or use explicit semver pre-release notation:
+          # python-version: '3.13.0-alpha.4'
+          allow-prereleases: true
+prevention:
+  - "Use semver notation (3.13.0-alpha.4) not pyenv notation (3.13.0a4) in .python-version files consumed by CI."
+  - "Prefer pinning to a stable minor version (3.13) in CI rather than a specific pre-release patch."
+  - "Always set allow-prereleases: true in setup-python when using any pre-release Python version."
+  - "Add a comment in .python-version documenting the notation convention to avoid confusion for contributors."
+docs:
+  - url: "https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md#using-the-python-version-file-input"
+    label: "setup-python docs — python-version-file input"
+  - url: "https://github.com/actions/setup-python/issues/770"
+    label: "actions/setup-python#770 — Pre-release version notation mismatch"
+  - url: "https://docs.python.org/3/faq/general.html#how-does-the-python-version-numbering-scheme-work"
+    label: "Python.org — Version numbering scheme"

package/errors/runner-environment/runner-environment-165.yml

@@ -0,0 +1,86 @@
+id: runner-environment-165
+title: "ARM64 Linux Runners: Python Packages Without linux_aarch64 Binary Wheels Fail Installation"
+category: runner-environment
+severity: error
+tags:
+  - arm64
+  - ubuntu-arm
+  - python
+  - pip
+  - binary-wheels
+  - linux-aarch64
+patterns:
+  - regex: 'No matching distribution found for .+==[\d.]+'
+    flags: "i"
+  - regex: 'Could not find a version that satisfies the requirement .+ \(from versions: none\)'
+    flags: "i"
+  - regex: 'ERROR: .+ is not supported on this platform'
+    flags: "i"
+error_messages:
+  - "ERROR: Could not find a version that satisfies the requirement numpy==1.21.0 (from versions: none)"
+  - "ERROR: No matching distribution found for numpy==1.21.0"
+  - "error: command '/usr/bin/gcc' failed with exit code 1"
+  - "Building wheels for collected packages: X ... error: subprocess-exited-with-error"
+root_cause: |
+  When migrating from x64 runners (ubuntu-latest, ubuntu-22.04) to ARM64
+  runners (ubuntu-24.04-arm, ubuntu-22.04-arm), Python packages pinned to
+  older versions may not have linux_aarch64 binary wheels on PyPI. Without a
+  pre-compiled wheel, pip falls back to building from source, which either
+  fails outright (missing build dependencies, compiler errors) or succeeds
+  slowly. For packages like numpy, scipy, Pillow, cryptography, and pandas,
+  ARM64 wheel support was only added in later releases. The error message "No
+  matching distribution found" is misleading because the package does exist on
+  PyPI — just not the specific version for the linux_aarch64 platform.
+
+  Commonly affected packages and the minimum version with ARM64 wheel support:
+  - numpy: >= 1.24.0
+  - Pillow: >= 9.2.0
+  - cryptography: >= 38.0.0
+  - grpcio: >= 1.50.0
+  - scipy: >= 1.9.0
+  - lxml: >= 4.9.0
+
+  This is distinct from PEP 668 (system pip blocked by externally managed env),
+  macOS Rosetta (x86_64 binary executing on Apple Silicon), and
+  ubuntu-arm64-docker-not-preinstalled (Docker not available on arm runners).
+fix: |
+  Upgrade pinned package versions to releases that include linux_aarch64 binary
+  wheels. Use pip install --only-binary=:all: to get a clear platform error
+  instead of a slow source-build failure. If upgrading is impossible, install
+  the required build dependencies (gcc, python3-dev, libssl-dev, etc.) before
+  running pip install.
+fix_code:
+  - language: yaml
+    label: "Upgrade pinned packages to ARM64-compatible versions"
+    code: |
+      - name: Install Python dependencies (ARM64 compatible)
+        run: |
+          # Upgrade pinned packages to versions with linux_aarch64 wheels
+          pip install "numpy>=1.24.0" "Pillow>=9.2.0" "cryptography>=38.0.0"
+
+  - language: yaml
+    label: "Use --only-binary to detect missing wheels early"
+    code: |
+      - name: Install dependencies (fail fast if no wheel)"
+        run: pip install --only-binary=:all: -r requirements.txt
+
+  - language: yaml
+    label: "Install build dependencies for packages requiring source compilation"
+    code: |
+      - name: Install build dependencies for source compilation
+        run: sudo apt-get install -y gcc python3-dev libssl-dev libffi-dev
+
+      - name: Install Python packages
+        run: pip install -r requirements.txt
+prevention:
+  - "Before migrating to ARM64 runners, audit requirements.txt for packages lacking linux_aarch64 wheels at pinned versions."
+  - "Use pip install --only-binary=:all: -r requirements.txt in a test run to surface platform compatibility gaps."
+  - "Reference PyPI package pages to verify linux_aarch64 wheel availability for the specific version you are pinning."
+  - "Prefer unpinned or range-pinned dependencies (numpy>=1.24) over exact-pinned (numpy==1.21.0) to allow ARM64-capable versions."
+docs:
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "GitHub Docs — Supported GitHub-hosted runners (ARM64)"
+  - url: "https://pip.pypa.io/en/stable/cli/pip_install/#cmdoption-only-binary"
+    label: "pip docs — --only-binary option"
+  - url: "https://stackoverflow.com/questions/75782839"
+    label: "SO#75782839 — pip no matching distribution on ARM64 runner"

package/errors/silent-failures/vars-context-environment-shadows-repo-org.yml

@@ -0,0 +1,97 @@
+id: silent-failures-088
+title: 'vars.* context: environment-scoped variable silently shadows repository and org variable'
+category: silent-failures
+severity: silent-failure
+tags:
+  - vars
+  - variables
+  - environment
+  - precedence
+  - shadow
+  - configuration
+patterns:
+  - regex: 'vars\.[A-Z_]+'
+    flags: 'i'
+error_messages: []
+root_cause: |
+  The vars.* context resolves configuration variables in strict precedence order:
+  environment-scoped > repository-level > organization-level. When a job specifies
+  an environment: key, any variable defined at that deployment environment's scope
+  with the same name as a repository or organization variable silently overrides
+  the higher-scope value.
+
+  No warning or error is emitted when shadowing occurs. The workflow runs
+  successfully but uses the environment-scoped value rather than the expected
+  org or repository value.
+
+  Common scenario: an organization defines vars.REGION='us-east-1' for all repos.
+  A production deployment environment defines vars.REGION='eu-west-1' to override
+  it for EU deploys. All jobs that reference the production environment now receive
+  'eu-west-1' — including notification jobs, post-deploy validation jobs, or any
+  other job that happens to run in the production environment but was not intended
+  to use the EU override.
+
+  Unlike secrets, where absence raises a validation error, variable shadowing is
+  entirely transparent to the workflow author. Debugging requires manually
+  inspecting variable scopes in GitHub Settings across three levels (org, repo,
+  environment) to find the effective value.
+fix: |
+  Use scope-specific prefixes for variables that intentionally override
+  parent-scope defaults (e.g., PROD_REGION instead of REGION). Audit effective
+  variable values at runtime by echoing vars.* at the start of critical jobs.
+
+  To inspect what is currently configured:
+  - GitHub > Organization Settings > Variables (org-level)
+  - Repo Settings > Secrets and variables > Variables (repo-level)
+  - Repo Settings > Environments > <name> > Variables (environment-level)
+fix_code:
+  - language: yaml
+    label: 'Debug effective vars.* resolution in a job with environment scope'
+    code: |
+      jobs:
+        deploy:
+          environment: production
+          runs-on: ubuntu-latest
+          steps:
+            - name: Audit effective variable values
+              run: |
+                echo "REGION (effective): ${{ vars.REGION }}"
+                # If this shows 'eu-west-1' when you expected 'us-east-1',
+                # the 'production' environment has a REGION variable that
+                # silently shadows the org or repository-level value.
+  - language: yaml
+    label: 'Use environment-scoped prefixes to make overrides explicit'
+    code: |
+      # Organization variable: REGION=us-east-1
+      # Environment 'production' variable: PROD_REGION=eu-west-1  (distinct name)
+
+      jobs:
+        deploy:
+          environment: production
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy to production
+              run: |
+                # Explicit — no ambiguity about which scope is used
+                deploy --region ${{ vars.PROD_REGION }}
+
+        notify:
+          environment: production
+          runs-on: ubuntu-latest
+          steps:
+            - name: Notify
+              run: |
+                # Without prefix, this would silently get 'eu-west-1' instead
+                # of 'us-east-1' if REGION is defined at environment scope
+                notify --datacenter ${{ vars.NOTIFICATION_REGION }}
+prevention:
+  - 'Prefix environment-scoped variable names to make overrides explicit — PROD_REGION not REGION'
+  - 'Audit all three variable scopes before deployments: org, repo, and environment'
+  - 'Add a comment in the workflow file documenting which variables each environment is expected to override'
+  - 'For critical deployment config, avoid relying on implicit variable inheritance — reference scope-prefixed names'
+  - 'Run a variable audit step at the start of critical jobs to log effective vars.* values'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#precedence-for-variable-values'
+    label: 'GitHub Docs — Variable precedence for the vars.* context'
+  - url: 'https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment'
+    label: 'GitHub Docs — Managing environments for deployment'

package/errors/triggers/triggers-064.yml

@@ -0,0 +1,122 @@
+id: triggers-064
+title: "workflow_run Triggered Workflow Cannot Access github.event.pull_request — PR Number Is Empty"
+category: triggers
+severity: silent-failure
+tags:
+  - workflow_run
+  - pull-request
+  - event-context
+  - pr-number
+  - artifact
+patterns:
+  - regex: 'github\.event\.pull_request\.number'
+    flags: "i"
+  - regex: 'event\.number.*workflow_run'
+    flags: "i"
+error_messages:
+  - "# No error thrown — github.event.pull_request.number evaluates to empty string"
+  - "Error: PR number is empty"
+root_cause: |
+  When a workflow is triggered by `on: workflow_run`, the event payload is a
+  `workflow_run` object — NOT the event that triggered the upstream workflow.
+
+  This means `github.event.pull_request`, `github.event.number`, and all
+  other pull_request-specific context keys evaluate to empty string (not an
+  error). The only event data available is under `github.event.workflow_run.*`,
+  which exposes run metadata (run ID, head branch, head SHA, conclusion, etc.)
+  but NOT the original pull request event payload.
+
+  The common pattern breaks when developers write `workflow_run`-triggered
+  workflows to post PR comments or add labels and reference
+  `${{ github.event.pull_request.number }}` — the expression silently evaluates
+  to empty string, causing downstream API calls to fail or act on the wrong
+  resource without a clear error.
+
+  `github.event.workflow_run.pull_requests` is populated by GitHub only when
+  the triggering workflow was itself triggered by a pull_request event, providing
+  a lighter-weight alternative to the artifact pattern.
+fix: |
+  Upload the needed PR context (number, head SHA, labels) as a JSON artifact
+  in the upstream workflow. In the downstream `workflow_run` workflow, download
+  the artifact and extract the values.
+
+  For simpler cases, read `github.event.workflow_run.pull_requests[0].number`
+  — GitHub populates this array when the triggering workflow ran on a PR.
+fix_code:
+  - language: yaml
+    label: "Upstream workflow: upload PR context as artifact"
+    code: |
+      on:
+        pull_request:
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+            - name: Save PR context for downstream workflow
+              run: |
+                mkdir -p /tmp/pr-context
+                echo '${{ toJSON(github.event.pull_request) }}' \
+                  > /tmp/pr-context/pr.json
+            - uses: actions/upload-artifact@v4
+              with:
+                name: pr-context
+                path: /tmp/pr-context/pr.json
+  - language: yaml
+    label: "Downstream workflow_run: download artifact and read PR number"
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+
+      jobs:
+        report:
+          runs-on: ubuntu-latest
+          permissions:
+            actions: read
+            pull-requests: write
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                name: pr-context
+                run-id: ${{ github.event.workflow_run.id }}
+                github-token: ${{ secrets.GITHUB_TOKEN }}
+            - name: Read PR number and comment
+              run: |
+                PR_NUMBER=$(jq '.number' pr.json)
+                echo "PR: $PR_NUMBER"
+              env:
+                GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  - language: yaml
+    label: "Lightweight alternative: use github.event.workflow_run.pull_requests array"
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+
+      jobs:
+        report:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Get PR number from workflow_run context
+              run: |
+                echo "PR: ${{ github.event.workflow_run.pull_requests[0].number }}"
+                # Note: pull_requests array is only populated when the triggering
+                # workflow was triggered by a pull_request event from a non-fork.
+                # For forks, the array is empty — use the artifact pattern instead.
+prevention:
+  - "Never reference github.event.pull_request in workflow_run-triggered workflows — the event payload is workflow_run, not pull_request."
+  - "Upload PR context (number, head SHA, labels) as a JSON artifact in the upstream workflow for downstream consumption."
+  - "Use github.event.workflow_run.pull_requests[0].number for a lighter approach when the triggering workflow ran on a non-fork pull_request."
+  - "Add defensive checks: if the PR number resolves to empty, skip steps that require it to avoid silent API failures."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run"
+    label: "GitHub Docs — workflow_run event"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#using-data-from-the-triggering-workflow"
+    label: "GitHub Docs — Using data from the triggering workflow"
+  - url: "https://stackoverflow.com/questions/71570882"
+    label: "SO#71570882 — Get PR number in workflow_run triggered workflow"

package/errors/yaml-syntax/timeout-minutes-env-context-unavailable.yml

@@ -0,0 +1,93 @@
+id: yaml-syntax-061
+title: 'env context unavailable in job-level timeout-minutes field'
+category: yaml-syntax
+severity: error
+tags:
+  - env
+  - timeout-minutes
+  - context
+  - context-availability
+  - job-level
+patterns:
+  - regex: 'Unrecognized named-value: .env.'
+    flags: 'i'
+  - regex: 'timeout-minutes.*\$\{\{.*env\.'
+    flags: 'i'
+error_messages:
+  - "The workflow is not valid. .github/workflows/<workflow>.yml (Line: X, Col: Y): Unrecognized named-value: 'env'. Located at position Z within expression: env.MY_TIMEOUT"
+root_cause: |
+  The env context is not available in job-level timeout-minutes expressions.
+  GitHub Actions evaluates jobs.<job_id>.timeout-minutes before steps run and
+  before step-level env values are populated. The available contexts at this
+  position are: github, inputs, vars, needs, strategy, and matrix only.
+
+  Developers commonly try to make timeouts configurable by setting a workflow-level
+  env: block (e.g., env: { JOB_TIMEOUT: 60 }) and referencing it as
+  ${{ env.JOB_TIMEOUT }} in timeout-minutes, expecting it to work like env
+  references inside steps. This fails with a parse-time validation error because
+  the env context is not evaluated at job metadata positions.
+
+  Note: env IS available in step-level timeout-minutes
+  (jobs.<job_id>.steps[*].timeout-minutes) — this restriction only applies at
+  the job level. This asymmetry trips up developers who test in steps first
+  and then try to lift the same expression to job level.
+fix: |
+  Use the vars context (repository or environment variables) instead of env for
+  job-level timeout-minutes. Repository variables can be set under
+  Settings > Secrets and variables > Variables and are available at job-evaluation
+  time.
+
+  If the timeout value needs to vary per workflow run, pass it as a workflow
+  input (inputs.*) for workflow_dispatch or workflow_call, or use matrix values
+  to parameterize timeouts per leg.
+fix_code:
+  - language: yaml
+    label: 'Wrong — env context in job-level timeout-minutes (validation error)'
+    code: |
+      env:
+        JOB_TIMEOUT: 60
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: ${{ env.JOB_TIMEOUT }}  # ERROR: env not available here
+          steps:
+            - run: make build
+  - language: yaml
+    label: 'Correct — use vars context for a configurable job timeout'
+    code: |
+      # Set JOB_TIMEOUT_MINUTES in repository Settings > Variables (e.g., "60")
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: ${{ fromJSON(vars.JOB_TIMEOUT_MINUTES || '60') }}
+          steps:
+            - run: make build
+  - language: yaml
+    label: 'Correct — pass timeout as workflow_dispatch input'
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            timeout:
+              type: number
+              default: 60
+              description: 'Job timeout in minutes'
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: ${{ inputs.timeout }}
+          steps:
+            - run: make build
+prevention:
+  - 'Use vars.* (repository or environment variables) for static configurable timeouts at job level'
+  - 'Use inputs.* for runtime-configurable timeouts passed via workflow_dispatch or workflow_call'
+  - 'env context is only available at step level and below — not at the job metadata level'
+  - 'step-level timeout-minutes does support env context; only job-level timeout-minutes does not'
+  - 'Available contexts in job-level fields: github, inputs, vars, needs, strategy, matrix'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#context-availability'
+    label: 'GitHub Docs — Context availability per workflow position'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes'
+    label: 'GitHub Docs — jobs.<job_id>.timeout-minutes'

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

@@ -0,0 +1,100 @@
+id: yaml-syntax-060
+title: "Object Filter Expression .* on Null Parent Context Raises Template Validation Error"
+category: yaml-syntax
+severity: error
+tags:
+  - expression
+  - object-filter
+  - null-context
+  - wildcard
+  - pull_request
+  - multi-trigger
+patterns:
+  - regex: 'Object filter left operand must be of type Array or Object but is Null'
+    flags: "i"
+  - regex: 'github\.event\.[a-z_]+\.\*\.[a-z_]+'
+    flags: "i"
+  - regex: 'The template is not valid.*Object filter'
+    flags: "i"
+error_messages:
+  - "Error: The template is not valid. .github/workflows/ci.yml (Line: 12, Col: 8): Object filter left operand must be of type Array or Object but is Null"
+  - "Object filter left operand must be of type Array or Object but is Null"
+  - "Unexpected value 'null'. Located at position 0 within expression: contains(github.event.pull_request.labels.*.name, 'skip-ci')"
+root_cause: |
+  GitHub Actions supports object filtering via the .* wildcard syntax, which
+  maps over an array or object and extracts a named property from each element.
+  For example: github.event.pull_request.labels.*.name returns an array of
+  label names on a pull_request event.
+
+  When the parent context object is null — which occurs whenever the event
+  payload does not include that property — the .* filter throws a template
+  validation error at expression evaluation time rather than returning an empty
+  array. This is a common pitfall in workflows that handle multiple event types:
+
+  - On push events, github.event.pull_request is null
+  - On schedule events, github.event.issue is null
+  - On workflow_dispatch events, github.event.commits is null
+
+  The expression evaluator does NOT fall back to an empty result for null .*.
+  Instead it fails the step with a template error, even though null.property
+  (single property access) would silently return an empty string.
+
+  Typical pattern that fails on push events:
+    if: contains(github.event.pull_request.labels.*.name, 'skip-ci')
+fix: |
+  Guard the object filter expression with an event type check so the .* filter
+  is only evaluated when the parent context is known to be non-null. Use
+  github.event_name to gate the condition, or split the if: into separate
+  trigger-specific jobs.
+fix_code:
+  - language: yaml
+    label: "Guard with event type check"
+    code: |
+      # BAD: fails on push events because pull_request context is null
+      # if: contains(github.event.pull_request.labels.*.name, 'skip-ci')
+
+      # GOOD: gate on event type first
+      - name: Check for skip-ci label
+        if: >
+          github.event_name == 'pull_request' &&
+          contains(github.event.pull_request.labels.*.name, 'skip-ci')
+        run: echo "skip-ci label found, skipping build"
+
+  - language: yaml
+    label: "Use separate jobs per event trigger"
+    code: |
+      on:
+        push:
+          branches: [main]
+        pull_request:
+
+      jobs:
+        # Only runs on pull_request — safe to use pull_request context
+        label-check:
+          if: github.event_name == 'pull_request'
+          runs-on: ubuntu-latest
+          steps:
+            - name: Check labels
+              if: contains(github.event.pull_request.labels.*.name, 'skip-ci')
+              run: echo "Label found"
+
+        # Runs on both push and pull_request — no pull_request context access
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+prevention:
+  - "Before using github.event.X.*.property, verify the event type with github.event_name == 'X' in the same if: expression."
+  - "In multi-trigger workflows (on: push, pull_request), never access pull_request context properties without an event type guard."
+  - "Use actionlint to catch null context dereferences statically before they fail in CI."
+  - "When checking PR labels in workflows triggered by both push and pull_request, consider splitting into separate per-event jobs."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#object-filters"
+    label: "GitHub Docs — Object filters in expressions"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#github-context"
+    label: "GitHub Docs — github context availability by event"
+  - url: "https://github.com/rhysd/actionlint"
+    label: "actionlint — Static checker for GitHub Actions workflow files"
+  - url: "https://stackoverflow.com/questions/67368005"
+    label: "SO#67368005 — Object filter left operand must be of type Array or Object but is Null"

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

@@ -0,0 +1,101 @@
+id: yaml-syntax-062
+title: "if: always() Runs Even on Manual Workflow Cancellation — Use if: !cancelled() for Cleanup Jobs"
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - if-condition
+  - always
+  - cancelled
+  - status-functions
+  - cleanup-job
+patterns:
+  - regex: 'if:\s*always\(\)'
+    flags: "i"
+  - regex: 'always\(\).*cleanup\|cleanup.*always\(\)'
+    flags: "i"
+error_messages:
+  - "# No error — cleanup job unexpectedly runs after manual workflow cancellation"
+  - "# Job marked 'Cancelled' in UI but cleanup/notify step still executed"
+root_cause: |
+  The `always()` status check function evaluates to `true` in ALL job states:
+  `success`, `failure`, `cancelled`, and `skipped`. This is intentional and
+  documented, but the implication for cleanup/notification jobs surprises many
+  developers.
+
+  When a workflow is manually cancelled (via the GitHub UI, API, or CLI), all
+  running and queued jobs receive a `cancelled` status. Jobs with
+  `if: always()` will still execute because `always()` explicitly includes the
+  `cancelled` state.
+
+  The common intent is "always run this cleanup step even if the build failed"
+  — but the actual effect includes "run even when an operator stops the workflow
+  mid-run." This can cause cleanup jobs to run unexpectedly, send spurious
+  notifications, or consume runner minutes after an intentional cancellation.
+
+  Status function reference:
+    - `success()`    — true only when job status is success (default when no if:)
+    - `failure()`    — true only when job status is failure
+    - `cancelled()`  — true only when workflow was manually cancelled
+    - `always()`     — true for success, failure, cancelled, AND skipped
+    - `!cancelled()` — true for success and failure; skips on cancelled/skipped
+
+  `if: always()` and `if: !cancelled()` are NOT equivalent — the difference
+  becomes apparent only when workflows are manually cancelled.
+fix: |
+  For cleanup and notification jobs that should respect manual cancellation,
+  use `if: !cancelled()` instead of `if: always()`.
+
+  Reserve `if: always()` for jobs that genuinely must run in every state,
+  including intentional cancellations (rare).
+fix_code:
+  - language: yaml
+    label: "Use !cancelled() for cleanup jobs that should respect manual cancellation"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: make build
+
+        notify:
+          runs-on: ubuntu-latest
+          needs: build
+          # Bad: always() runs even when workflow is manually cancelled
+          # if: ${{ always() }}
+
+          # Good: !cancelled() runs on success and failure, skips on cancellation
+          if: ${{ !cancelled() }}
+          steps:
+            - name: Send Slack notification
+              run: echo "Build result: ${{ needs.build.result }}"
+  - language: yaml
+    label: "Status function comparison"
+    code: |
+      jobs:
+        # Runs only on success (implicit default — no if: needed)
+        deploy:
+          if: ${{ success() }}
+
+        # Runs on success or failure — skips on manual cancellation
+        notify:
+          if: ${{ !cancelled() }}
+
+        # Runs in every state including manual cancellation (use sparingly)
+        audit-log:
+          if: ${{ always() }}
+
+        # Runs only when the workflow was manually cancelled
+        on-cancel:
+          if: ${{ cancelled() }}
+prevention:
+  - "Use if: !cancelled() for cleanup and notification jobs to respect manual workflow cancellation."
+  - "Reserve if: always() for jobs that must run even when an operator intentionally stops the workflow."
+  - "When combining status functions with needs: checks, use needs.X.result == 'failure' for explicit conditions."
+  - "Run actionlint to detect common if: expression issues before pushing."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#status-check-functions"
+    label: "GitHub Docs — Status check functions"
+  - url: "https://github.com/rhysd/actionlint/blob/main/docs/checks.md"
+    label: "actionlint — Expression checks"
+  - url: "https://stackoverflow.com/questions/58457140"
+    label: "SO#58457140 — Difference between if: always() and if: !cancelled()"

package/package.json

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