@htekdev/actions-debugger 1.0.99 → 1.0.101

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/triggers/triggers-067.yml

@@ -0,0 +1,134 @@
+id: triggers-067
+title: 'workflow_run types:[completed] fires prematurely with conclusion:null before referenced workflow finishes'
+category: triggers
+severity: error
+tags:
+  - workflow_run
+  - conclusion
+  - null
+  - premature-trigger
+  - race-condition
+  - completed
+patterns:
+  - regex: 'workflow_run\.conclusion.*null'
+    flags: 'i'
+  - regex: 'github\.event\.workflow_run\.conclusion'
+    flags: 'i'
+  - regex: 'conclusion.*randomly.*fail'
+    flags: 'i'
+error_messages:
+  - "github.event.workflow_run.conclusion returned null — job skipped unexpectedly"
+  - "Unable to extend GITHUB_TOKEN expiration time due to: GITHUB_TOKEN has expired."
+root_cause: |
+  The `workflow_run` event with `types: [completed]` is documented to fire only after the
+  referenced workflow finishes running. However, a known race condition in GitHub Actions'
+  event delivery (tracked in actions/runner#4035) causes the event to fire a second time
+  BEFORE the workflow has fully completed — specifically before GitHub has written the final
+  `conclusion` value to the workflow run record.
+
+  When this premature trigger fires, `github.event.workflow_run.conclusion` evaluates to
+  `null` (or an empty string `""`). Any job guarded with:
+
+    if: github.event.workflow_run.conclusion == 'success'
+
+  will evaluate to `false` and be skipped, producing a confusing pattern where the
+  downstream workflow runs twice — once skipped, once (correctly) executed.
+
+  GitHub Support confirmed this as a platform-side delay: the `conclusion` field remains
+  `null` while GitHub's backend is still updating the workflow run record. The event
+  is dispatched before the record is fully consistent.
+
+  This affects all workflows that use `on.workflow_run` with `types: [completed]` and
+  check `github.event.workflow_run.conclusion` to gate job execution.
+fix: |
+  Two mitigations are available:
+
+  1. **Guard with `conclusion != ''`** — Add a condition that explicitly rejects null/empty
+     `conclusion` values before checking for `'success'`:
+
+     if: >-
+       github.event.workflow_run.conclusion != '' &&
+       github.event.workflow_run.conclusion == 'success'
+
+  2. **Re-query via REST API** — Instead of trusting `github.event.workflow_run.conclusion`,
+     use the Actions REST API to fetch the current workflow run conclusion at step runtime:
+
+     gh api /repos/${{ github.repository }}/actions/runs/${{ github.event.workflow_run.id }} \
+       --jq '.conclusion'
+
+     This always returns the up-to-date value, bypassing the event payload race condition.
+
+  Note: adding a `sleep` between trigger and conclusion check is NOT a reliable fix, as
+  the delay between trigger and backend consistency is variable and can exceed seconds.
+fix_code:
+  - language: yaml
+    label: 'Problem: conclusion check fails on premature null trigger'
+    code: |
+      on:
+        workflow_run:
+          workflows: ['CI Build']
+          types: [completed]
+
+      jobs:
+        deploy:
+          # This randomly evaluates to false when conclusion is null
+          if: github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying..."
+  - language: yaml
+    label: 'Fix: guard against null conclusion before equality check'
+    code: |
+      on:
+        workflow_run:
+          workflows: ['CI Build']
+          types: [completed]
+
+      jobs:
+        deploy:
+          # Explicitly reject null/empty conclusion to avoid premature-trigger skips
+          if: >-
+            github.event.workflow_run.conclusion != '' &&
+            github.event.workflow_run.conclusion == 'success'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying..."
+  - language: yaml
+    label: 'Fix: re-query conclusion via REST API for reliable value'
+    code: |
+      on:
+        workflow_run:
+          workflows: ['CI Build']
+          types: [completed]
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Check conclusion via API
+              id: check
+              env:
+                GH_TOKEN: ${{ github.token }}
+              run: |
+                conclusion=$(gh api \
+                  /repos/${{ github.repository }}/actions/runs/${{ github.event.workflow_run.id }} \
+                  --jq '.conclusion')
+                echo "conclusion=$conclusion" >> "$GITHUB_OUTPUT"
+
+            - name: Deploy
+              if: steps.check.outputs.conclusion == 'success'
+              run: echo "Deploying..."
+prevention:
+  - "Never rely solely on `github.event.workflow_run.conclusion == 'success'` without a null guard."
+  - "Add `github.event.workflow_run.conclusion != ''` as an explicit first condition to reject premature triggers."
+  - "If downstream jobs must be fully reliable, re-query conclusion via the REST API rather than reading from the event payload."
+  - "Monitor the Actions tab for unexpectedly skipped `workflow_run` triggered runs — they indicate premature triggers."
+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://github.com/actions/runner/issues/4035'
+    label: 'actions/runner#4035: workflow_run triggers before referenced workflow completes'
+  - url: 'https://stackoverflow.com/questions/73107307/any-workaround-for-github-actions-workflow-run-conclusion-randomly-failing'
+    label: 'Stack Overflow: workflow_run.conclusion randomly failing'
+  - url: 'https://github.com/orgs/community/discussions/58929'
+    label: 'GitHub Community #58929: github.event.workflow_run.conclusion is always null'

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

@@ -0,0 +1,119 @@
+id: yaml-syntax-064
+title: 'strategy.matrix.include/exclude entry value specified as array causes "A sequence was not expected"'
+category: yaml-syntax
+severity: error
+tags:
+  - matrix
+  - include
+  - exclude
+  - array-value
+  - sequence
+  - validation-error
+  - strategy
+patterns:
+  - regex: 'A sequence was not expected'
+    flags: 'i'
+  - regex: 'matrix\.(include|exclude).*\[.*\]'
+    flags: 'i'
+  - regex: 'strategy.*matrix.*include.*sequence'
+    flags: 'i'
+error_messages:
+  - "Error: The template is not valid. .github/workflows/workflow.yml (Line: 12, Col: 18): A sequence was not expected"
+  - "A sequence was not expected"
+root_cause: |
+  In a `strategy.matrix`, the top-level matrix dimensions accept arrays of scalars:
+
+    php: ['8.2', '8.3', '8.4']   # valid — array of scalars
+
+  However, inside `include:` and `exclude:` entries, ALL values must be scalars
+  (string, number, boolean). Arrays are not allowed:
+
+    include:
+      - os: ubuntu-latest
+        php: ['8.2']              # INVALID — array not allowed in include/exclude entries
+
+  This is a common mistake when a developer copies the variable name from the main
+  matrix definition (where it IS an array) and pastes it into an `include:` or
+  `exclude:` entry without unwrapping it.
+
+  GitHub Actions' expression evaluator validates the template before execution and
+  throws an immediate hard failure:
+
+    Error: The template is not valid. .github/workflows/X.yml (Line: N, Col: M):
+    A sequence was not expected
+
+  The error points to the line where the array value starts (the `[` character),
+  which can be confusing because arrays are valid YAML and valid in other matrix
+  contexts. The fix is simply to remove the brackets and use a scalar value.
+
+  Tracked in rhysd/actionlint#630 (actionlint static analysis issue requesting
+  detection of this pattern).
+fix: |
+  Replace any array-valued entries inside `include:` or `exclude:` with scalar values.
+  Each `include:`/`exclude:` entry is a single-combination filter — it selects or adds
+  one specific combination, so the value must be a scalar that matches exactly one item.
+
+  If you need to include multiple values for a key, write separate `include:` entries,
+  one per value.
+fix_code:
+  - language: yaml
+    label: 'Problem: array value inside include entry — triggers "A sequence was not expected"'
+    code: |
+      strategy:
+        matrix:
+          os: [ubuntu-latest, macos-latest]
+          php: ['8.3', '8.4', '8.5']
+
+          include:
+            # ERROR: php value is an array — not allowed inside include entries
+            - os: ubuntu-latest
+              php: ['8.2']      # ← "A sequence was not expected" on this line
+
+          exclude:
+            # ERROR: os value is an array — not allowed inside exclude entries
+            - os: [macos-latest]
+              php: '8.3'        # ← "A sequence was not expected"
+  - language: yaml
+    label: 'Fix: use scalar values inside include/exclude entries'
+    code: |
+      strategy:
+        matrix:
+          os: [ubuntu-latest, macos-latest]
+          php: ['8.3', '8.4', '8.5']
+
+          include:
+            # CORRECT: scalar value — adds ubuntu-latest × 8.2 as an extra job
+            - os: ubuntu-latest
+              php: '8.2'        # ← scalar, not array
+
+          exclude:
+            # CORRECT: scalar value — excludes macos-latest × 8.3 combination
+            - os: macos-latest
+              php: '8.3'        # ← scalar, not array
+  - language: yaml
+    label: 'Multiple include entries for multiple specific combinations'
+    code: |
+      strategy:
+        matrix:
+          os: [ubuntu-latest, macos-latest]
+          node: [18, 20]
+
+          include:
+            # To include multiple specific combinations, write separate entries:
+            - os: ubuntu-latest
+              node: 22          # one entry per extra combination
+            - os: ubuntu-latest
+              node: 23          # another entry for a different combination
+            # NOT: node: [22, 23]  ← this would fail with "A sequence was not expected"
+prevention:
+  - "Values inside `include:` and `exclude:` entries must be scalars — never use array syntax `[...]` there."
+  - "When copying matrix variable names from the top-level dimensions to include/exclude entries, remove the brackets."
+  - "Use actionlint (github.com/rhysd/actionlint) to statically validate your workflow files before pushing."
+  - "If you need multiple combinations, write multiple separate `include:` entries instead of one entry with an array value."
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/running-variations-of-jobs-in-a-workflow#expanding-or-adding-matrix-configurations'
+    label: 'GitHub Docs: Expanding or adding matrix configurations'
+  - url: 'https://github.com/rhysd/actionlint/issues/630'
+    label: 'rhysd/actionlint#630: Detect array values in matrix include/exclude entries'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrixinclude'
+    label: 'GitHub Docs: jobs.<job_id>.strategy.matrix.include syntax reference'

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