@htekdev/actions-debugger 1.0.63 → 1.0.64

package/errors/known-unsolved/service-containers-not-supported-macos-windows.yml

@@ -0,0 +1,88 @@
+id: known-unsolved-041
+title: "services: Block Not Supported on macOS and Windows Runners — Silently Ignored"
+category: known-unsolved
+severity: limitation
+tags:
+  - services
+  - service-containers
+  - macos
+  - windows
+  - linux-only
+patterns:
+  - regex: 'services\s*:'
+    flags: 'im'
+  - regex: 'runs-on\s*:\s*(macos|windows)'
+    flags: 'i'
+error_messages:
+  - "Connection refused 127.0.0.1:5432"
+  - "Unable to connect to the database server"
+  - "ECONNREFUSED"
+  - "connect ECONNREFUSED 127.0.0.1:6379"
+root_cause: |
+  GitHub Actions `services:` containers are only supported on Linux (Ubuntu) runners.
+  On macOS and Windows GitHub-hosted runners, the `services:` block is silently ignored
+  — the job starts without the service containers, and no warning or error is emitted
+  at the workflow syntax level.
+
+  This happens because the runner agent's service container feature requires Docker
+  to be integrated at the runner daemon level. GitHub-hosted macOS and Windows runners
+  do not have a running Docker daemon available to the runner agent by default, making
+  the `services:` lifecycle management impossible.
+
+  The failure is deceptive: the job starts normally, all steps run, but any step that
+  tries to connect to the service (e.g., PostgreSQL on port 5432, Redis on port 6379)
+  receives a connection refused error. The `services:` block produces no visible error
+  of its own.
+
+  There is no GitHub Actions built-in mechanism to make `services:` work on macOS or
+  Windows runners. This is a permanent platform limitation.
+fix: |
+  Use a Linux (ubuntu-*) runner for any job that requires service containers. If macOS
+  or Windows testing is required alongside a service dependency, start the service
+  manually as workflow steps within the job instead of using the `services:` block.
+fix_code:
+  - language: yaml
+    label: "services: block — only works on Linux runners"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest  # services: requires Linux
+          services:
+            postgres:
+              image: postgres:15
+              env:
+                POSTGRES_PASSWORD: postgres
+              ports:
+                - 5432:5432
+              options: >-
+                --health-cmd pg_isready
+                --health-interval 10s
+                --health-timeout 5s
+                --health-retries 5
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+  - language: yaml
+    label: "macOS/Windows: start service manually as a workflow step"
+    code: |
+      jobs:
+        test-macos:
+          runs-on: macos-latest
+          # services: is NOT supported here — start the service manually instead
+          steps:
+            - uses: actions/checkout@v4
+            - name: Start PostgreSQL (services: not supported on macOS)
+              run: |
+                brew install postgresql@15
+                brew services start postgresql@15
+                sleep 5
+            - run: npm test
+prevention:
+  - "Always pair the `services:` block with a Linux (ubuntu-*) runner — treat this as a hard rule in code review"
+  - "If cross-platform testing needs a service dependency, isolate the service-dependent tests into a Linux-only job"
+  - "Add a comment near the `services:` block to document that this job must run on Linux"
+docs:
+  - url: "https://docs.github.com/en/actions/use-cases-and-examples/using-containerized-services/about-service-containers"
+    label: "GitHub Docs: About service containers (Linux-only requirement)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idservices"
+    label: "GitHub Docs: jobs.<job_id>.services syntax reference"

package/errors/silent-failures/workflow-run-github-sha-is-default-branch.yml

@@ -0,0 +1,78 @@
+id: silent-failures-064
+title: "workflow_run Trigger: github.sha Points to Default Branch HEAD, Not Triggering Workflow's Commit"
+category: silent-failures
+severity: silent-failure
+tags:
+  - workflow_run
+  - github-sha
+  - checkout
+  - wrong-commit
+  - cross-workflow
+patterns:
+  - regex: 'on\s*:\s*\n\s+workflow_run'
+    flags: 'im'
+  - regex: 'github\.sha'
+    flags: 'i'
+error_messages:
+  - "Unexpected checkout SHA — does not match pull request head commit"
+  - "Tests passing on default branch but failing on PR commit"
+root_cause: |
+  When a workflow is triggered by `on: workflow_run`, the `github.sha` and `github.ref`
+  context variables point to the HEAD of the **default branch** at the time the trigger
+  fires, NOT to the commit that triggered the upstream workflow. This is by design: the
+  `workflow_run` event executes in the context of the base repository's default branch.
+
+  Workflows that use `actions/checkout` without specifying a `ref` will silently check
+  out the default branch — running against entirely different code than the PR or branch
+  that triggered the original CI workflow. CI results, security scans, and deployments
+  end up referencing the wrong commit with no visible error.
+
+  The correct commit SHA from the triggering workflow is available in the event payload
+  as `github.event.workflow_run.head_sha`.
+fix: |
+  Use `github.event.workflow_run.head_sha` as the `ref` in `actions/checkout` within
+  any `workflow_run` triggered workflow. When the triggering workflow originates from a
+  fork PR, also supply `github.event.workflow_run.head_repository.full_name` as the
+  `repository` input so the correct fork is checked out.
+fix_code:
+  - language: yaml
+    label: "Wrong: default checkout uses github.sha (default branch HEAD)"
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+
+      jobs:
+        process:
+          runs-on: ubuntu-latest
+          steps:
+            # Silently checks out default branch, NOT the triggering commit
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: "Correct: use workflow_run event payload for the right commit"
+    code: |
+      on:
+        workflow_run:
+          workflows: ["CI"]
+          types: [completed]
+
+      jobs:
+        process:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                repository: ${{ github.event.workflow_run.head_repository.full_name }}
+                ref: ${{ github.event.workflow_run.head_sha }}
+                token: ${{ secrets.GITHUB_TOKEN }}
+prevention:
+  - "Always set `ref: ${{ github.event.workflow_run.head_sha }}` in checkout steps inside workflow_run triggered workflows"
+  - "Log both `github.sha` and `github.event.workflow_run.head_sha` at workflow start to verify they match when expected"
+  - "For fork-originated PRs, also set `repository: ${{ github.event.workflow_run.head_repository.full_name }}`"
+  - "Add a comment in the workflow explaining why head_sha is used instead of github.sha to avoid future confusion"
+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 (context behavior)"
+  - url: "https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/"
+    label: "GitHub Security Lab: Preventing pwn requests (workflow_run checkout patterns)"

package/errors/triggers/push-commits-truncated-20-limit.yml

@@ -0,0 +1,78 @@
+id: triggers-046
+title: "github.event.commits Array Truncated to 20 Commits on Large Pushes"
+category: triggers
+severity: silent-failure
+tags:
+  - push
+  - commits
+  - github-event
+  - truncated
+  - commit-messages
+patterns:
+  - regex: 'github\.event\.commits'
+    flags: 'i'
+error_messages:
+  - "Only processing 20 of N commits"
+  - "Missing commits in push event payload"
+root_cause: |
+  When a push event triggers a workflow, the `github.event.commits` array is capped at
+  a maximum of 20 commit objects, regardless of how many commits were included in the
+  push. This limit applies to the webhook payload that populates the `github.event`
+  context and is documented in the GitHub webhook specification.
+
+  Workflows that iterate over `github.event.commits` to extract commit messages for
+  changelog generation, enforce commit message formatting (Conventional Commits, etc.),
+  or trigger conditional logic based on commit content will silently miss any commits
+  beyond the 20th. The job completes successfully with no indication that commits were
+  dropped from the payload.
+
+  Commonly affected use cases:
+  - Automated changelog or release note generation from push commit messages
+  - Commit message linting or conventional commits enforcement
+  - Workflows triggered by specific keywords in commit messages
+  - Security scanning workflows that enumerate all modified files from commit diffs
+fix: |
+  Use `git log` with the push SHA range (`github.event.before..github.event.after`) to
+  enumerate all commits in the push, regardless of count. This requires checking out
+  the repository with `fetch-depth: 0` (full history) or at minimum enough depth to
+  span the push range. Guard against the `before` SHA being all zeros (first push to
+  a new branch).
+fix_code:
+  - language: yaml
+    label: "Wrong: iterating github.event.commits silently misses commits beyond 20"
+    code: |
+      - name: Lint commit messages
+        run: |
+          # Silently processes only up to 20 commits even on large pushes
+          echo '${{ toJSON(github.event.commits) }}' \
+            | jq -r '.[].message' \
+            | npx commitlint --from stdin
+  - language: yaml
+    label: "Correct: use git log with push range to enumerate all commits"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history required for git log range
+
+      - name: Lint all commit messages in push
+        run: |
+          BEFORE="${{ github.event.before }}"
+          AFTER="${{ github.event.after }}"
+
+          # Guard: first push to a new branch has before = 000...000
+          if [ "$BEFORE" = "0000000000000000000000000000000000000000" ]; then
+            echo "First push to new branch — scanning tip commit only"
+            git log -1 --format="%s" "$AFTER"
+          else
+            git log --format="%s" "${BEFORE}..${AFTER}"
+          fi | npx commitlint --from stdin
+prevention:
+  - "Never rely on `github.event.commits` for exhaustive commit enumeration on pushes — use `git log` with the SHA range instead"
+  - "Always add `fetch-depth: 0` to checkout when your workflow needs to enumerate commits from the push range"
+  - "Guard against `github.event.before` being all zeros (new branch first push) before running `git log BEFORE..AFTER`"
+  - "If commit count matters, log a warning when `github.event.commits | length == 20` to detect truncation"
+docs:
+  - url: "https://docs.github.com/en/webhooks/webhook-events-and-payloads#push"
+    label: "GitHub Docs: Push webhook payload (20 commit limit)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push"
+    label: "GitHub Docs: push event trigger"

package/errors/yaml-syntax/runs-on-env-context-unavailable.yml

@@ -0,0 +1,82 @@
+id: yaml-syntax-043
+title: "env Context Not Available in runs-on Expression — Job Waits for Non-Existent Runner"
+category: yaml-syntax
+severity: error
+tags:
+  - runs-on
+  - env-context
+  - context-availability
+  - runner-selection
+  - expression
+patterns:
+  - regex: 'runs-on\s*:.*\$\{\{.*env\.'
+    flags: 'i'
+error_messages:
+  - "No runner matching the specified labels was found"
+  - "Context access might be invalid: env"
+  - "Evaluates to empty string in runs-on"
+root_cause: |
+  The `env` context is not available in `jobs.<job_id>.runs-on` expressions. GitHub
+  Actions documents an explicit context availability table, and `env` is excluded from
+  the `runs-on` field. Only the `github`, `needs`, `strategy`, `matrix`, `vars`, and
+  `inputs` contexts are available for `runs-on` expressions.
+
+  When a developer writes `runs-on: ${{ env.RUNNER_LABEL }}`, the expression evaluates
+  to an empty string (since `env` is not accessible at that evaluation point). GitHub
+  Actions may emit the warning "Context access might be invalid: env" during workflow
+  parsing. The job then queues waiting for a runner matching an empty or literal label,
+  which never matches, and the job hangs until it times out.
+
+  This is a common mistake when setting a custom self-hosted runner label as a
+  workflow-level or job-level `env:` variable and trying to reference it in `runs-on`
+  for DRY configuration.
+fix: |
+  Use the `vars` context (repository, organization, or environment variables) instead of
+  `env` for dynamic runner label selection. Repository variables can be set in the
+  repository's Settings > Secrets and variables > Variables and referenced as
+  `${{ vars.RUNNER_LABEL }}`. The `vars` context IS available in `runs-on` expressions.
+
+  Alternatively, use `inputs` context for `workflow_dispatch` triggered workflows to
+  allow callers to specify the runner label.
+fix_code:
+  - language: yaml
+    label: "Wrong: env context is not available in runs-on"
+    code: |
+      env:
+        RUNNER_LABEL: self-hosted-prod  # This env var cannot be used in runs-on
+
+      jobs:
+        deploy:
+          # ERROR: env context unavailable — expression evaluates to empty string
+          runs-on: ${{ env.RUNNER_LABEL }}
+  - language: yaml
+    label: "Correct: use vars context (repository/org variable)"
+    code: |
+      # Set RUNNER_LABEL in Settings > Secrets and variables > Variables (repo or org level)
+      jobs:
+        deploy:
+          runs-on: ${{ vars.RUNNER_LABEL || 'ubuntu-latest' }}
+  - language: yaml
+    label: "Correct: use inputs for workflow_dispatch dynamic runner selection"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            runner:
+              description: 'Runner label'
+              default: 'ubuntu-latest'
+              type: string
+
+      jobs:
+        deploy:
+          runs-on: ${{ inputs.runner }}
+prevention:
+  - "Check GitHub's context availability table before using any context in `runs-on` — `env` is NOT available there"
+  - "Use `vars.*` (repository or org variables) not `env.*` for dynamic runner label configuration"
+  - "Add `|| 'ubuntu-latest'` as a fallback in `runs-on` expressions to avoid jobs that queue indefinitely"
+  - "If the job hangs immediately after queuing with no runner assignment, check `runs-on` expressions for invalid context usage"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#context-availability"
+    label: "GitHub Docs: Context availability table (runs-on allowed contexts)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on"
+    label: "GitHub Docs: jobs.<job_id>.runs-on expressions"

package/package.json

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