@htekdev/actions-debugger 1.0.99 → 1.0.100

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

@@ -0,0 +1,104 @@
+id: caching-artifacts-055
+title: 'setup-python cache: poetry broken when poetry is installed before setup-python — virtualenv 20.33.0+ Python version mismatch'
+category: caching-artifacts
+severity: error
+tags:
+  - setup-python
+  - poetry
+  - cache
+  - virtualenv
+  - python-version
+  - pipx
+  - ordering
+patterns:
+  - regex: 'Current Python version \([\d.]+\) is not allowed by the project'
+    flags: 'i'
+  - regex: 'poetry.*install.*exit code 1'
+    flags: 'i'
+  - regex: 'Please change python executable via the "env use" command'
+    flags: 'i'
+  - regex: 'installed package poetry.*using Python \d+\.\d+'
+    flags: 'i'
+error_messages:
+  - "Current Python version (3.12.3) is not allowed by the project (>= 3.13, < 4). Please change python executable via the \"env use\" command."
+  - "Current Python version (3.11.9) is not allowed by the project (>=3.12,<3.13). Please change python executable via the \"env use\" command."
+  - "Error: Process completed with exit code 1."
+root_cause: |
+  When using actions/setup-python with cache: 'poetry', the action requires
+  poetry to be installed BEFORE it runs (to resolve the cache path). Developers
+  commonly install poetry via pipx before calling setup-python, which causes
+  pipx to anchor poetry to the runner's pre-installed system Python (e.g., 3.12.3).
+
+  After setup-python runs and installs the project's target Python version
+  (e.g., 3.13), poetry's internal virtualenv logic still references the Python
+  version it was originally installed with. Consequently, when poetry creates
+  or activates a virtual environment, it resolves to the old Python version —
+  which violates the project's python requirement and produces the
+  "Current Python version is not allowed" error.
+
+  This became a consistent failure in August 2025 when virtualenv 20.33.0
+  changed how it resolves the Python interpreter for new virtual environments,
+  making the version mismatch explicit and fatal rather than silently using
+  the wrong interpreter.
+
+  The fundamental issue is a circular dependency in the documented workflow:
+  setup-python needs poetry installed to set up caching, but poetry must be
+  installed after setup-python to use the correct Python version.
+fix: |
+  Use actions/cache manually instead of setup-python's built-in poetry cache.
+  Install poetry AFTER setup-python so it is anchored to the correct Python.
+  This avoids the circular ordering problem entirely.
+fix_code:
+  - language: yaml
+    label: 'Workaround — Manual cache + install poetry after setup-python'
+    code: |
+      steps:
+        - uses: actions/setup-python@v5
+          id: setup-python
+          with:
+            python-version: '3.13'
+            # Do NOT use cache: 'poetry' here
+
+        - name: Install poetry
+          run: pipx install poetry
+
+        - name: Cache poetry virtualenv
+          uses: actions/cache@v4
+          with:
+            path: ~/.cache/pypoetry/virtualenvs
+            key: ${{ runner.os }}-poetry-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
+            restore-keys: |
+              ${{ runner.os }}-poetry-${{ steps.setup-python.outputs.python-version }}-
+
+        - name: Install dependencies
+          run: poetry install
+  - language: yaml
+    label: 'Alternative — pin virtualenv version as a short-term patch'
+    code: |
+      steps:
+        - name: Install poetry (with pinned virtualenv)
+          run: |
+            pipx install poetry
+            pipx inject poetry virtualenv==20.26.6
+
+        - uses: actions/setup-python@v5
+          with:
+            python-version: '3.13'
+            cache: 'poetry'
+
+        - name: Install dependencies
+          run: poetry install
+prevention:
+  - "Never use setup-python cache: poetry in combination with a poetry install step that runs before setup-python."
+  - "Use actions/cache manually to avoid the circular dependency between poetry installation and Python version resolution."
+  - "Keep poetry updated — poetry 2.1.4+ partially mitigates the virtualenv version mismatch for some project configurations."
+  - "Use uv as an alternative to poetry; uv is installed on GitHub-hosted runners and handles Python version resolution differently."
+docs:
+  - url: 'https://github.com/actions/setup-python/issues/1167'
+    label: 'actions/setup-python #1167 — Issues with poetry caching (Aug 2025)'
+  - url: 'https://github.com/python-poetry/poetry/issues/10490'
+    label: 'python-poetry/poetry #10490 — virtualenv 20.33.0 compatibility issue'
+  - url: 'https://github.com/pypa/virtualenv/issues/2931'
+    label: 'pypa/virtualenv #2931 — Python interpreter resolution change'
+  - url: 'https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md#caching-packages'
+    label: 'actions/setup-python — Caching packages documentation'

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

@@ -0,0 +1,124 @@
+id: known-unsolved-055
+title: 'github.event.workflow_run.pull_requests is empty for fork PRs — PR context unavailable in triggered workflow'
+category: known-unsolved
+severity: silent-failure
+tags:
+  - workflow_run
+  - fork
+  - pull-requests
+  - event-context
+  - security
+  - limitation
+  - pull_request
+patterns:
+  - regex: 'github\.event\.workflow_run\.pull_requests'
+    flags: 'i'
+  - regex: 'pull_requests.*\[\]|workflow_run.*pull_requests.*empty'
+    flags: 'i'
+error_messages:
+  - "# No error thrown — github.event.workflow_run.pull_requests evaluates to [] for fork PRs"
+  - "Error: PR number is empty or undefined"
+  - "Cannot read properties of undefined (reading 'number')"
+root_cause: |
+  When a workflow is triggered by on: workflow_run: and the upstream workflow
+  was triggered by a pull_request event from a fork, the
+  github.event.workflow_run.pull_requests array is deliberately empty ([]).
+
+  For same-repository PRs, the pull_requests array is populated with PR
+  metadata (number, head.sha, head.ref, base.ref, etc.). For fork PRs, it
+  is always an empty array for security reasons: GitHub does not expose PR
+  metadata from fork branches through this event payload to prevent
+  untrusted code from accessing repository information via the privileged
+  workflow_run context.
+
+  This is a known, by-design limitation (GitHub closed the tracker issue as
+  "not planned"). The result is that workflows designed to comment on PRs,
+  post status checks, or download artifacts using the PR number silently
+  fail or crash when run against fork-originated pull requests because
+  github.event.workflow_run.pull_requests[0].number evaluates to undefined.
+
+  The limitation is easy to miss during development because the workflow
+  works correctly for PRs from within the same organization — the failure
+  only appears when an external contributor opens a fork PR.
+fix: |
+  Pass the required PR information as an artifact from the upstream
+  (untrusted) workflow to the downstream (privileged) workflow_run workflow.
+  The upstream workflow writes the PR number to a file and uploads it as
+  an artifact; the downstream workflow downloads the artifact and reads
+  the PR number from it.
+
+  This is the officially documented pattern for safe fork PR workflows.
+fix_code:
+  - language: yaml
+    label: 'Upstream (untrusted) workflow — upload PR number as artifact'
+    code: |
+      # .github/workflows/pr-checks.yml (runs on pull_request, limited privileges)
+      name: PR Checks
+      on:
+        pull_request:
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "${{ github.event.number }}" > pr_number.txt
+            - uses: actions/upload-artifact@v4
+              with:
+                name: pr-number
+                path: pr_number.txt
+  - language: yaml
+    label: 'Downstream (privileged) workflow — download artifact to get PR number'
+    code: |
+      # .github/workflows/pr-comment.yml (runs on workflow_run, full privileges)
+      name: PR Comment
+      on:
+        workflow_run:
+          workflows: ["PR Checks"]
+          types: [completed]
+
+      jobs:
+        comment:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Download PR number artifact
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  const artifacts = await github.rest.actions.listWorkflowRunArtifacts({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    run_id: context.payload.workflow_run.id,
+                  });
+                  const prArtifact = artifacts.data.artifacts.find(a => a.name === 'pr-number');
+                  if (!prArtifact) { core.setFailed('No pr-number artifact'); return; }
+                  const download = await github.rest.actions.downloadArtifact({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    artifact_id: prArtifact.id,
+                    archive_format: 'zip',
+                  });
+                  require('fs').writeFileSync('pr_number.zip', Buffer.from(download.data));
+            - run: unzip pr_number.zip && echo "PR=$(cat pr_number.txt)" >> $GITHUB_ENV
+            - name: Post comment
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  await github.rest.issues.createComment({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    issue_number: Number(process.env.PR),
+                    body: 'Checks passed!'
+                  });
+prevention:
+  - "Always use the artifact-passing pattern for workflow_run workflows that need PR context — never assume github.event.workflow_run.pull_requests is populated."
+  - "Check the triggering event type: if github.event.workflow_run.event == 'pull_request' and the array is empty, the PR came from a fork."
+  - "Use github.event.workflow_run.head_branch and head_sha for correlating runs, but not for PR numbers (which are unavailable for forks)."
+  - "Consider using the gh-action-pr-number community action which handles the artifact-based lookup pattern automatically."
+docs:
+  - url: 'https://github.com/actions/runner/issues/3444'
+    label: 'actions/runner #3444 — workflow_run from fork pull_request lacks pull_requests payload'
+  - url: 'https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#using-data-from-the-triggering-workflow'
+    label: 'GitHub Docs — Using data from the triggering workflow (artifact pattern)'
+  - url: 'https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_run'
+    label: 'GitHub Docs — workflow_run event reference'

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

@@ -0,0 +1,101 @@
+id: permissions-auth-058
+title: 'actions/checkout does not rewrite ssh:// submodule URLs — only git@github.com: format is rewritten'
+category: permissions-auth
+severity: error
+tags:
+  - checkout
+  - submodules
+  - ssh
+  - gitmodules
+  - URL-rewriting
+  - host-key-verification
+  - ssh-key
+patterns:
+  - regex: 'Host key verification failed'
+    flags: 'i'
+  - regex: 'ssh://.*Permission denied|ssh://.*Could not read from remote'
+    flags: 'i'
+  - regex: 'fatal: clone of .ssh://. into submodule path .* failed'
+    flags: 'i'
+  - regex: 'git@github\.com.*vs.*ssh://github\.com'
+    flags: 'i'
+error_messages:
+  - "Host key verification failed."
+  - "fatal: Could not read from remote repository."
+  - "Please make sure you have the correct access rights and the repository exists."
+  - "fatal: clone of 'ssh://git@github.com/Org/SubRepo.git' into submodule path '<path>' failed"
+root_cause: |
+  actions/checkout rewrites submodule URLs in .gitmodules to inject the
+  provided ssh-key or GITHUB_TOKEN credentials, but the rewriting logic only
+  handles the git@github.com: URL format. URLs using the alternative
+  ssh://git@github.com/ scheme are NOT rewritten and are passed to git
+  as-is.
+
+  When git attempts to clone an ssh:// URL without an SSH agent providing
+  the key, and without the runner having github.com in ~/.ssh/known_hosts,
+  the clone fails with "Host key verification failed." or permission errors.
+
+  The affected code path is actions/checkout/src/git-auth-helper.ts which
+  contains an explicit regex that only matches the git@ style:
+    /^git@github\.com:/
+  The ssh:// variant does not match, so the credential injection and
+  known_hosts population steps are skipped for those URLs.
+
+  This is a confirmed open bug with a pending fix (PR #2367), but as of
+  early 2026 it remains unmerged and unreleased.
+fix: |
+  Convert all submodule URLs in .gitmodules from ssh:// to git@github.com:
+  format. This ensures actions/checkout's URL rewriting logic applies the
+  SSH key and adds the host key to known_hosts.
+
+  If you cannot change .gitmodules (e.g., the submodule is a third-party
+  repo), use a manual git config insteadOf URL rewrite in a pre-checkout
+  step to normalize the URL before the checkout action runs.
+fix_code:
+  - language: bash
+    label: 'Option A — Change .gitmodules to use git@ format instead of ssh://'
+    code: |
+      # .gitmodules — BEFORE (broken)
+      [submodule "MySubrepo"]
+          path = MySubrepo
+          url = ssh://git@github.com/Org/MySubrepo.git
+
+      # .gitmodules — AFTER (working)
+      [submodule "MySubrepo"]
+          path = MySubrepo
+          url = git@github.com:Org/MySubrepo.git
+  - language: yaml
+    label: 'Option B — Add git config URL rewrite step before checkout'
+    code: |
+      steps:
+        - name: Rewrite ssh:// submodule URLs to git@ format
+          run: |
+            git config --global url."git@github.com:".insteadOf "ssh://git@github.com/"
+
+        - uses: actions/checkout@v4
+          with:
+            submodules: recursive
+            ssh-key: ${{ secrets.SSH_DEPLOY_KEY }}
+  - language: yaml
+    label: 'Option C — Use HTTPS with token for submodule auth (avoids SSH entirely)'
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+          with:
+            submodules: recursive
+            token: ${{ secrets.PAT_WITH_SUBMODULE_ACCESS }}
+            # Requires .gitmodules to use https:// URLs
+prevention:
+  - "Standardize on git@github.com: format for all .gitmodules URLs in repositories using actions/checkout with SSH keys."
+  - "Use HTTPS URLs with a PAT for submodule access when possible — this is simpler and avoids SSH host key issues entirely."
+  - "Add a linting step (e.g., grep .gitmodules for ssh://) to your repo's pre-commit hooks to catch the wrong URL format early."
+  - "Track actions/checkout PR #2367 for the fix; upgrade once it is merged and released."
+docs:
+  - url: 'https://github.com/actions/checkout/issues/2178'
+    label: 'actions/checkout #2178 — ssh:// URLs in .gitmodules do not work'
+  - url: 'https://github.com/actions/checkout/pull/2367'
+    label: 'actions/checkout PR #2367 — Fix: also rewrite ssh:// URLs'
+  - url: 'https://github.com/actions/checkout/blob/main/src/git-auth-helper.ts'
+    label: 'actions/checkout git-auth-helper.ts — URL rewriting source code'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-conditions-to-control-job-execution'
+    label: 'GitHub Docs — Checking out submodules'

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

@@ -0,0 +1,88 @@
+id: runner-environment-169
+title: 'actions/runner 2.320.0+ container image removes SSH — "error: cannot run ssh: No such file or directory"'
+category: runner-environment
+severity: error
+tags:
+  - runner
+  - ssh
+  - openssh-client
+  - git-submodules
+  - self-hosted
+  - container-runner
+  - 2.320
+patterns:
+  - regex: 'error: cannot run ssh: No such file or directory'
+    flags: 'i'
+  - regex: 'fatal: unable to fork'
+    flags: 'i'
+  - regex: 'Unable to locate executable file: ssh'
+    flags: 'i'
+  - regex: 'error downloading.*ssh://.*No such file or directory'
+    flags: 'i'
+error_messages:
+  - "error: cannot run ssh: No such file or directory"
+  - "fatal: unable to fork"
+  - "Unable to locate executable file: ssh. Please verify either the file path exists or the file can be found within a directory specified by the PATH environment variable."
+  - "error downloading 'ssh://git@github.com/...': /usr/bin/git exited with 128: error: cannot run ssh: No such file or directory"
+root_cause: |
+  Starting with actions/runner 2.320.0, the base container image
+  (ghcr.io/actions/actions-runner) no longer ships openssh-client by default.
+  Workflows that rely on git operations over SSH — including submodule cloning
+  via SSH URLs, Terragrunt module downloads over ssh://, or any step that
+  calls ssh-keyscan — fail at runtime because the ssh binary is absent from
+  the runner's PATH.
+
+  This affected both self-hosted runners built from the official container
+  image and any ephemeral runners (Actions Runner Controller / ARC) that
+  derive from ghcr.io/actions/actions-runner:2.320.0+. Hosted runners
+  (ubuntu-latest, etc.) were not affected because they use a separate,
+  pre-loaded VM image that still includes openssh-client.
+
+  The regression was introduced when the container image was slimmed down
+  between 2.319.1 and 2.320.0 without a corresponding changelog callout,
+  leaving self-hosted container runners silently broken on upgrade.
+fix: |
+  Install openssh-client in the runner container image before the runner
+  process starts. For Dockerfiles extending the official image, add an
+  explicit RUN instruction. For ARC runner deployments, add an
+  initContainers step or a containerStartupCommand to install the package.
+
+  If you do not control the image, add an installation step at the top of
+  the failing workflow job before any SSH-dependent steps.
+fix_code:
+  - language: yaml
+    label: 'Option A — Add install step in the workflow before any SSH steps'
+    code: |
+      jobs:
+        build:
+          runs-on: self-hosted
+          steps:
+            - name: Install SSH client
+              run: |
+                apt-get update -qq && apt-get install -y --no-install-recommends openssh-client
+            - name: Checkout with submodules
+              uses: actions/checkout@v4
+              with:
+                submodules: recursive
+                ssh-key: ${{ secrets.SSH_KEY }}
+  - language: dockerfile
+    label: 'Option B — Bake openssh-client into a custom runner image'
+    code: |
+      FROM ghcr.io/actions/actions-runner:latest
+      USER root
+      RUN apt-get update && apt-get install -y --no-install-recommends openssh-client && rm -rf /var/lib/apt/lists/*
+      USER runner
+prevention:
+  - "Pin your ARC / self-hosted runner image to a tested version (e.g., ghcr.io/actions/actions-runner:2.319.1) and test upgrades in a staging environment before rolling out."
+  - "Add a pre-flight check step that runs 'which ssh || (apt-get install -y openssh-client)' if your workflow requires SSH."
+  - "Prefer HTTPS-based submodule URLs and GITHUB_TOKEN for submodule auth in GitHub Actions — this avoids SSH entirely."
+  - "Subscribe to the actions/runner GitHub Releases feed to catch breaking changes in container image composition."
+docs:
+  - url: 'https://github.com/actions/runner/issues/3490'
+    label: 'actions/runner #3490 — Runner 2.320.0 no longer has SSH installed'
+  - url: 'https://github.com/actions/runner/issues/3488'
+    label: 'actions/runner #3488 — Runner version 2.320.0 breaks custom image'
+  - url: 'https://github.com/actions/checkout/issues/1942'
+    label: 'actions/checkout #1942 — Unable to locate executable file: ssh'
+  - url: 'https://github.com/actions/runner/releases'
+    label: 'actions/runner releases'

package/errors/silent-failures/github-event-pull-request-null-on-non-pr-events.yml

@@ -0,0 +1,96 @@
+id: silent-failures-090
+title: '`github.event.pull_request.*` Fields Are Null on Non-PR Events — Comparisons Silently Evaluate Incorrectly'
+category: silent-failures
+severity: silent-failure
+tags:
+  - github-context
+  - pull_request
+  - null-context
+  - push-event
+  - multi-event
+  - expression
+patterns:
+  - regex: 'github\.event\.pull_request\.\w+'
+    flags: 'i'
+error_messages:
+  - "Unexpected value '' in expression"
+root_cause: |
+  When a workflow is triggered by a non-pull_request event — such as `push`, `schedule`,
+  `workflow_dispatch`, `workflow_call`, or `release` — the `github.event.pull_request`
+  object is null. Every child field evaluates to empty string `""` in expressions.
+
+  This silently breaks conditions in multi-event workflows:
+
+  - `if: github.event.pull_request.draft == false`
+    On a push event, `draft` resolves to `""`. The comparison `"" == false` evaluates to
+    FALSE (empty string is not boolean false), so the step silently skips.
+
+  - `if: github.event.pull_request.merged == true`
+    Always false on push events, causing steps intended for merged-PR context to silently
+    never execute.
+
+  - `env: PR_NUMBER: ${{ github.event.pull_request.number }}`
+    Sets `PR_NUMBER` to empty string on push events. Downstream scripts that require a
+    PR number fail with "invalid argument" or use `0` as the number.
+
+  - `if: github.event.pull_request.head.repo.fork != true`
+    Always evaluates to true on push events (empty string != true), bypassing fork guards.
+
+  The root issue is that workflows triggered by multiple events (e.g., `on: [push,
+  pull_request]`) share the same `if:` conditions and `env:` references, but the
+  `github.event` object structure differs per event type. Note that `yaml-syntax-060`
+  covers the object filter `.*` operator on null — this entry covers field-level null
+  comparisons in `if:` and `env:` contexts.
+fix: |
+  Guard all `github.event.pull_request.*` access with an event type check:
+
+    if: github.event_name == 'pull_request' && github.event.pull_request.draft == false
+
+  For env variables that should only apply on PR events, set them conditionally:
+  use a step to export the variable only when running under a pull_request trigger,
+  or use separate jobs per event type.
+
+  For the fork guard pattern, use `github.event_name == 'pull_request' &&
+  github.event.pull_request.head.repo.fork` as a combined check rather than relying
+  on the fork field being non-null.
+fix_code:
+  - language: yaml
+    label: "Guard PR context access with event type check in if: condition"
+    code: |
+      jobs:
+        check-draft:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Skip if draft PR (only meaningful on PR events)
+              # Without the event_name guard, draft is "" on push — comparison silently fails
+              if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
+              run: echo "Proceeding — not a draft PR"
+  - language: yaml
+    label: "Export PR-specific context safely in multi-event workflows"
+    code: |
+      on: [push, pull_request]
+      
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Export PR metadata (PR events only)
+              if: github.event_name == 'pull_request'
+              run: |
+                echo "PR_NUMBER=${{ github.event.pull_request.number }}" >> $GITHUB_ENV
+                echo "IS_DRAFT=${{ github.event.pull_request.draft }}" >> $GITHUB_ENV
+            
+            - name: Deploy
+              run: |
+                echo "Branch: ${{ github.ref_name }}"
+                # Use PR_NUMBER only after confirming event_name == pull_request above
+prevention:
+  - "In multi-event workflows, always guard `github.event.pull_request.*` access with `github.event_name == 'pull_request'`"
+  - "Run actionlint on workflow files — it detects context availability mismatches per event type"
+  - "Test workflows manually for both push and pull_request trigger types to verify that conditional logic works as expected"
+  - "Prefer separate jobs or separate workflow files per event type rather than a single workflow handling multiple events with shared conditions"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows"
+    label: "GitHub Docs: Events that trigger workflows — context availability per event"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#github-context"
+    label: "GitHub Docs: Contexts — github.event object structure"

package/errors/triggers/pull-request-edited-type-not-in-defaults.yml

@@ -0,0 +1,82 @@
+id: triggers-066
+title: '`pull_request` Default Event Types Exclude `edited` — PR Title, Body, and Base Branch Changes Do Not Trigger CI'
+category: triggers
+severity: silent-failure
+tags:
+  - pull_request
+  - event-types
+  - edited
+  - silent
+  - title-body
+  - default-types
+patterns:
+  - regex: 'types:\s*\[.*edited.*\]'
+    flags: 'i'
+error_messages:
+  - "Workflow not triggered on pull_request edited event"
+root_cause: |
+  The `pull_request` event defaults to `types: [opened, synchronize, reopened]`.
+  The `edited` type — which fires when the PR title, body (description), base branch,
+  or milestone is modified — is NOT included in the defaults.
+
+  Workflows configured as `on: pull_request:` without an explicit `types:` key do NOT
+  run when a developer:
+  - Corrects a typo in the PR title
+  - Adds required information to the PR description (e.g., issue reference, testing notes)
+  - Changes the PR target base branch to a different branch
+
+  This creates a common silent failure: PR validation workflows that enforce title
+  conventions (Conventional Commits, Jira ticket format), required description sections,
+  or base branch policies run correctly on initial PR open and on new commits — but they
+  silently skip when the developer edits the PR title or description to fix a violation.
+  The developer believes CI re-ran and passed, but the workflow never executed.
+
+  This follows the same pattern as `labeled` and `ready_for_review` not being in
+  pull_request defaults — both are documented but frequently overlooked.
+fix: |
+  Explicitly declare the types your workflow responds to. Add `edited` to the types list
+  for any workflow that validates or reacts to PR metadata:
+
+    on:
+      pull_request:
+        types: [opened, synchronize, reopened, edited]
+
+  Only include the types you actually need. Adding `edited` to workflows that don't use
+  PR metadata (title, body, base) causes unnecessary runs.
+fix_code:
+  - language: yaml
+    label: "Include 'edited' in types to trigger on PR title and body changes"
+    code: |
+      on:
+        pull_request:
+          types: [opened, synchronize, reopened, edited]
+  - language: yaml
+    label: "Workflow that validates PR title only on open and edit events"
+    code: |
+      on:
+        pull_request:
+          types: [opened, edited]  # Only metadata-relevant events — no need for synchronize
+      
+      jobs:
+        validate-title:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Check PR title format
+              env:
+                PR_TITLE: ${{ github.event.pull_request.title }}
+              run: |
+                echo "Validating title: $PR_TITLE"
+                if [[ ! "$PR_TITLE" =~ ^(feat|fix|chore|docs|refactor|test|ci)\: ]]; then
+                  echo "ERROR: PR title must follow Conventional Commits format"
+                  exit 1
+                fi
+prevention:
+  - "Always explicitly list all required `types` in pull_request triggers — never rely on defaults for validation workflows"
+  - "Test PR validation workflows end-to-end by editing the PR title and verifying the workflow re-runs"
+  - "Add a comment above the `on:` block documenting which event types the workflow responds to and why"
+  - "Refer to the full list of pull_request event types in GitHub docs when creating new PR workflows"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request"
+    label: "GitHub Docs: Events that trigger workflows — pull_request"
+  - url: "https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request"
+    label: "GitHub Docs: Webhook events — pull_request event payload and types"

package/errors/triggers/skip-ci-commit-message-silently-skips-workflows.yml

@@ -0,0 +1,80 @@
+id: triggers-065
+title: '`[skip ci]` and `[skip actions]` Commit Message Flags Silently Skip All Triggered Workflows'
+category: triggers
+severity: silent-failure
+tags:
+  - skip-ci
+  - commit-message
+  - workflow-skip
+  - silent
+  - push
+  - pull_request
+patterns:
+  - regex: '\[skip[ -]ci\]'
+    flags: 'i'
+  - regex: '\[ci[ -]skip\]'
+    flags: 'i'
+  - regex: '\[skip actions\]'
+    flags: 'i'
+error_messages:
+  - "[skip ci]"
+  - "[ci skip]"
+  - "[no ci]"
+  - "[skip actions]"
+  - "[actions skip]"
+root_cause: |
+  GitHub Actions inspects the HEAD commit message (and all commits in a push batch) for
+  skip directives: [skip ci], [ci skip], [no ci], [skip actions], and [actions skip].
+  When any directive is found, GitHub skips ALL workflows triggered by that push or its
+  associated pull_request events — completely silently.
+
+  No workflow run is created, no status check is posted to the commit, no email or
+  notification is sent, and the PR shows "No checks" or prior checks disappear without
+  explanation. There is no indicator in the UI that workflows were intentionally skipped.
+
+  Common causes of unintended skips:
+  - Automated commits from bots (changelog updates, version bumps) that include [skip ci]
+    are squash-merged and the directive ends up in the merge commit message
+  - Dependabot or Renovate PRs that carry skip flags from upstream commit messages
+  - Developers testing locally add [skip ci] to a commit and forget to remove it before
+    the final push to a shared branch
+  - CI automation that auto-amends commit messages and inadvertently includes the pattern
+fix: |
+  Remove the skip directive from the commit message. To re-trigger CI without rewriting
+  history, create an empty commit (a commit with no file changes) and upload it — this
+  creates a new push event without any skip directive.
+
+  If an automated process is adding skip flags unintentionally, update the automation's
+  commit template to exclude them. If the skip is intentional for one workflow but not
+  others, note that there is no per-workflow opt-out — the skip is global across all
+  workflows triggered by that push.
+
+  To control workflow execution without commit message flags, prefer path filters
+  (on.push.paths) or branch filters (on.push.branches) for selective CI execution.
+fix_code:
+  - language: yaml
+    label: "Use path filters instead of commit-message skip flags to reduce unnecessary runs"
+    code: |
+      on:
+        push:
+          branches: [main]
+          paths:
+            - 'src/**'
+            - 'tests/**'
+            - '!docs/**'   # Ignore documentation-only changes without needing [skip ci]
+  - language: yaml
+    label: "Add workflow_dispatch as a manual fallback trigger if push was silently skipped"
+    code: |
+      on:
+        push:
+          branches: [main]
+        workflow_dispatch:  # Allows manual re-trigger if a skip-flagged push missed CI
+prevention:
+  - "Audit any automation that commits to your repository and verify it does not include [skip ci] unless intentional"
+  - "Establish a team convention: [skip ci] skips ALL workflows — prefer path filters for selective skipping"
+  - "Review squash-merge commit messages before merging PRs whose titles contain skip directives"
+  - "Check the GitHub Actions tab for missing runs rather than assuming a test passed silently"
+  - "Use `on: workflow_dispatch` as a manual safety valve to re-run CI on any branch"
+docs:
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/skipping-workflow-runs"
+    label: "GitHub Docs: Skipping workflow runs"

package/errors/yaml-syntax/yaml-syntax-error-hides-workflow-from-actions-ui.yml

@@ -0,0 +1,94 @@
+id: yaml-syntax-063
+title: 'YAML Syntax Error in Workflow File Silently Hides Workflow from Actions UI and Disables `workflow_dispatch`'
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - yaml-syntax
+  - workflow-dispatch
+  - ui-hidden
+  - silent
+  - parse-error
+  - debugging
+patterns:
+  - regex: 'invalid workflow file'
+    flags: 'i'
+  - regex: 'You have an error in your yaml syntax'
+    flags: 'i'
+error_messages:
+  - "You have an error in your YAML syntax on line N"
+  - "No workflow file found for event"
+  - "invalid workflow file: .github/workflows/X.yml"
+root_cause: |
+  When a GitHub Actions workflow file contains a YAML syntax error or schema validation
+  error, GitHub silently stops showing the workflow in the Actions tab and removes any
+  `workflow_dispatch` "Run workflow" button associated with it. No email, notification,
+  annotation, or repository-level banner is surfaced to warn the owner. The workflow
+  simply disappears from the UI.
+
+  Error categories that cause silent hiding:
+  - Standard YAML parse errors: incorrect indentation, unquoted colons in values,
+    duplicate keys, or tab characters used in place of spaces
+  - Missing required workflow keys: `runs-on` on a job, `steps` on a job, `on:` trigger
+  - Unrecognized keys that fail schema validation (e.g., typos in top-level keys)
+  - Invalid expression syntax inside `${{ }}` blocks
+  - Workflow exceeding GitHub's size limit (~500 KB)
+
+  This is distinct from the "workflow_dispatch button missing because the workflow file
+  is not on the default branch" issue. That error requires the file to be absent from
+  the default branch; this error occurs even when the file IS on the default branch but
+  is syntactically or structurally invalid.
+
+  Developers spend significant time investigating why CI "stopped running" or why the
+  dispatch button "disappeared" without realizing the workflow file has an error — because
+  GitHub provides no proactive notification.
+fix: |
+  Validate workflow YAML before every change:
+
+  1. Use actionlint locally to catch both YAML parse errors and GitHub Actions-specific
+     schema errors before the change reaches the default branch.
+  2. Use the GitHub web editor — it highlights YAML parse errors inline as you type.
+  3. Check the repository Actions tab: workflows with parse errors may show a yellow
+     warning triangle, or they may simply be absent from the list.
+  4. Query the REST API to verify workflow state:
+     GET /repos/{owner}/{repo}/actions/workflows
+     Workflows missing from the response or with state "disabled_manually" may indicate
+     a parse failure on the default branch.
+fix_code:
+  - language: yaml
+    label: "Add actionlint to CI to catch workflow YAML errors before they reach the default branch"
+    code: |
+      name: Lint Workflows
+      on:
+        pull_request:
+          paths:
+            - '.github/workflows/**'
+      jobs:
+        lint:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run actionlint
+              uses: rhysd/actionlint@latest
+  - language: yaml
+    label: "Correct structure for a minimal valid workflow file"
+    code: |
+      name: My Workflow          # Optional but recommended
+      on:                        # Required: at least one trigger
+        push:
+          branches: [main]
+      jobs:                      # Required: at least one job
+        build:                   # Job ID
+          runs-on: ubuntu-latest # Required: runner label
+          steps:                 # Required: at least one step
+            - uses: actions/checkout@v4
+prevention:
+  - "Install the actionlint VS Code extension to get inline YAML validation while editing workflow files"
+  - "Add a pull_request workflow that runs actionlint on all files under .github/workflows/ to catch errors before merging"
+  - "If workflow_dispatch button disappears, immediately check the Actions tab for parse error indicators"
+  - "Use GitHub's web editor for quick edits — it provides inline YAML validation"
+  - "Never use tab characters for indentation in YAML files — use spaces (2-space indent is standard)"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-syntax-for-github-actions"
+    label: "GitHub Docs: Workflow syntax for GitHub Actions"
+  - url: "https://github.com/rhysd/actionlint"
+    label: "actionlint — Static checker for GitHub Actions workflow files"

package/package.json

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