@htekdev/actions-debugger 1.0.56 → 1.0.57

package/errors/triggers/triggers-043.yml

@@ -0,0 +1,125 @@
+id: triggers-043
+title: "on.push with both branches and paths filters uses AND logic — push must match BOTH to trigger"
+category: triggers
+severity: silent-failure
+tags:
+  - on.push
+  - branches
+  - paths
+  - filter
+  - and-logic
+  - trigger
+  - paths-ignore
+patterns:
+  - regex: 'on:\s*\n\s*push:\s*\n(?:\s+.*\n)*\s+branches:'
+    flags: 'i'
+  - regex: 'push:.*branches.*paths|branches.*paths.*push'
+    flags: 'si'
+error_messages:
+  - "on:\n  push:\n    branches:"
+  - "on:\n  push:\n    paths:"
+root_cause: |
+  When a push trigger specifies BOTH a branches filter AND a paths filter, GitHub
+  Actions evaluates them using AND logic: the push event must match a listed branch
+  AND must include changes to a listed path. If either condition is not satisfied,
+  the workflow does not trigger — silently, with no log output or explanation.
+
+  Developers frequently expect OR logic: "trigger when pushing to main, OR when
+  any file in src/ changes." In reality, the behavior is: "trigger only when
+  pushing to main AND a file in src/ changed."
+
+  This means:
+  - A push to 'main' that only modifies 'README.md' does NOT trigger a workflow
+    configured with branches: [main] and paths: ['src/**']
+  - A push to a feature branch that modifies 'src/app.ts' does NOT trigger the
+    same workflow because the branch filter is not satisfied
+  - The workflow only runs when both conditions are simultaneously true
+
+  The same AND logic applies to other filter combinations:
+  - branches + tags: AND (a ref must match a branch pattern AND a tag pattern —
+    which is always false since a push cannot be both a branch and tag push)
+  - branches + paths-ignore: push must match a listed branch AND must NOT touch
+    any ignored path
+  - tags + paths: push must match a tag pattern AND include changes to listed paths
+
+  A particularly confusing case: using both on.push.branches and on.push.tags in
+  the same push trigger block creates an unsatisfiable AND condition (a push cannot
+  simultaneously target a branch AND create a tag). To trigger on either, use
+  two separate on: entries or separate workflow files.
+fix: |
+  If you want OR logic (trigger on main branch OR on changes to src/), you have
+  two options:
+
+  Option 1 — Use only one filter and handle the other in job-level if: conditions:
+    Push with paths filter only, then use: if: github.ref == 'refs/heads/main'
+    on the job to restrict execution to main.
+
+  Option 2 — Accept that both conditions must be true (the correct model for
+  "only run expensive tests when the right branch AND relevant files change").
+
+  For truly independent OR triggers, use separate workflow files.
+fix_code:
+  - language: yaml
+    label: "AND logic (default) — trigger only when branch AND path both match"
+    code: |
+      on:
+        push:
+          branches:
+            - main
+            - 'release/**'
+          paths:
+            - 'src/**'
+            - 'package.json'
+      # This workflow runs ONLY when:
+      # - Push is to 'main' or a 'release/*' branch
+      # AND
+      # - The push includes changes to src/ or package.json
+      # A push to main that only changes README.md will NOT trigger this workflow.
+  - language: yaml
+    label: "Separate workflow files for OR logic between independent trigger conditions"
+    code: |
+      # File 1: .github/workflows/deploy-main.yml
+      # Triggers on any push to main (regardless of changed paths)
+      on:
+        push:
+          branches:
+            - main
+
+      # File 2: .github/workflows/test-src.yml
+      # Triggers on any push that changes src/ (regardless of branch)
+      on:
+        push:
+          paths:
+            - 'src/**'
+            - 'tests/**'
+  - language: yaml
+    label: "Paths filter only — restrict by path in job if: conditions"
+    code: |
+      on:
+        push:
+          paths:
+            - 'src/**'
+            - 'package.json'
+            - 'package-lock.json'
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          # Additional branch restriction handled in job condition
+          if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release/')
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+prevention:
+  - "Read the GitHub docs note: 'If both branches and paths filters are used, the workflow will only run when both filters are satisfied'"
+  - "When debugging a workflow that doesn't trigger, temporarily remove one filter at a time to isolate whether the branch OR path filter is blocking the trigger"
+  - "Add a comment above combined branch+paths filters explicitly stating 'AND logic — both must match' to prevent future maintainers from misunderstanding"
+  - "Use actionlint or GitHub's workflow syntax checker which surfaces filter logic warnings"
+  - "Prefer paths-ignore over paths when you want 'run on everything except these files' — it's less likely to cause accidental AND-logic surprises"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#using-filters"
+    label: "GitHub Docs — Using filters with push and pull_request events"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push"
+    label: "GitHub Docs — push event filters (branches, tags, paths)"
+  - url: "https://stackoverflow.com/questions/63822219/github-actions-workflow-not-triggered-with-branch-and-path-filter"
+    label: "Stack Overflow — Workflow not triggered with branch and path filter (highly voted)"

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

@@ -0,0 +1,135 @@
+id: yaml-syntax-040
+title: "YAML anchors and aliases (&anchor / *alias) not supported in GitHub Actions workflow files"
+category: yaml-syntax
+severity: error
+tags:
+  - yaml-anchors
+  - yaml-aliases
+  - yaml-syntax
+  - workflow-validation
+  - reuse
+  - composite-action
+patterns:
+  - regex: 'mapping values are not allowed in this context'
+    flags: 'i'
+  - regex: 'could not find expected.*anchor'
+    flags: 'i'
+  - regex: 'Invalid workflow file'
+    flags: 'i'
+error_messages:
+  - "Invalid workflow file: .github/workflows/ci.yml"
+  - "mapping values are not allowed in this context"
+  - "could not find expected ':'"
+root_cause: |
+  GitHub Actions uses a YAML parser that does NOT support YAML anchors (&anchor_name)
+  and aliases (*anchor_name). These are standard YAML 1.1 features commonly used in
+  Docker Compose, Kubernetes manifests, and other DevOps tooling to avoid repetition.
+
+  Developers migrating from those tools often try patterns like:
+
+    .common-steps: &common-steps
+      - uses: actions/checkout@v4
+      - run: npm ci
+
+    jobs:
+      build:
+        steps: *common-steps
+      test:
+        steps: *common-steps
+
+  GitHub's workflow validator rejects these with cryptic parse errors such as
+  "mapping values are not allowed in this context" or simply "Invalid workflow file"
+  without identifying the anchor as the cause. In some parser versions, the anchor
+  definition is silently ignored while the alias (*common-steps) causes a hard failure
+  when evaluated.
+
+  The reason: GitHub validates workflow files against a strict JSON schema and uses a
+  restricted YAML subset. Anchors and merge keys (<<: *anchor) are explicitly outside
+  the supported grammar, regardless of whether they are valid YAML 1.1 per the spec.
+fix: |
+  Use GitHub Actions' native reuse mechanisms instead of YAML anchors:
+
+  1. Composite actions (.github/actions/<name>/action.yml): package shared steps into
+     a local action and reference it with `uses: ./.github/actions/<name>` from any job.
+
+  2. Reusable workflows (on.workflow_call): extract shared job sequences into a separate
+     workflow file called with `uses: ./.github/workflows/<file>.yml@<ref>`.
+
+  3. Shared shell scripts: commit scripts to the repository and call them with `run:`.
+     This avoids repeating multi-line run blocks without requiring action packaging.
+
+  4. Repository-level actions (public): publish shared logic as a public action and
+     reference it by `owner/repo@tag`.
+fix_code:
+  - language: yaml
+    label: "Composite action for shared setup steps — .github/actions/setup/action.yml"
+    code: |
+      # .github/actions/setup/action.yml
+      name: Project Setup
+      description: Install dependencies and configure environment
+      inputs:
+        node-version:
+          description: Node.js version to use
+          default: '20'
+      runs:
+        using: composite
+        steps:
+          - uses: actions/checkout@v4
+          - uses: actions/setup-node@v4
+            with:
+              node-version: ${{ inputs.node-version }}
+              cache: npm
+          - run: npm ci
+            shell: bash
+  - language: yaml
+    label: "Calling the composite action from multiple jobs — replaces *alias pattern"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: ./.github/actions/setup
+              with:
+                node-version: '20'
+            - run: npm run build
+
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: ./.github/actions/setup
+              with:
+                node-version: '20'
+            - run: npm test
+  - language: yaml
+    label: "Reusable workflow for shared job sequences"
+    code: |
+      # .github/workflows/shared-ci.yml
+      on:
+        workflow_call:
+          inputs:
+            environment:
+              type: string
+              required: true
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci && npm test
+              env:
+                APP_ENV: ${{ inputs.environment }}
+prevention:
+  - "Do not use YAML anchors (&) or aliases (*) or merge keys (<<:) in GitHub Actions workflow files — they are not supported"
+  - "Use composite actions (.github/actions/<name>/action.yml) for shared step sequences across jobs"
+  - "Use reusable workflows (on.workflow_call) for shared job sequences across workflow files"
+  - "Use shared shell scripts committed to the repository for repeated run blocks"
+  - "Run actionlint — it explicitly flags anchor/alias syntax as unsupported in Actions workflows"
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action"
+    label: "GitHub Docs — Creating a composite action"
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows"
+    label: "GitHub Docs — Reusing workflows"
+  - url: "https://github.com/rhysd/actionlint/blob/main/docs/checks.md"
+    label: "actionlint — Workflow file linting checks"
+  - url: "https://github.com/orgs/community/discussions/16638"
+    label: "GitHub Community — YAML anchors not supported in Actions workflows"

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

@@ -0,0 +1,147 @@
+id: yaml-syntax-041
+title: "env context unavailable at job-level if: conditions — evaluates empty or triggers 'Context access might be invalid' warning"
+category: yaml-syntax
+severity: error
+tags:
+  - env-context
+  - job-conditions
+  - if-condition
+  - context-availability
+  - expression
+  - workflow-validation
+patterns:
+  - regex: 'Context access might be invalid.*env'
+    flags: 'i'
+  - regex: 'Unexpected value.*env\.'
+    flags: 'i'
+  - regex: 'jobs\.[a-z_-]+\.if.*env\.[A-Z_]+'
+    flags: 'i'
+error_messages:
+  - "Context access might be invalid: env"
+  - "The workflow is not valid. .github/workflows/ci.yml: Unexpected value 'env'"
+root_cause: |
+  The `env` context in GitHub Actions is NOT available at all expression locations.
+  Its availability is scoped to specific parts of the workflow file.
+
+  `env` context IS available at:
+  - Step-level `if:` conditions (steps[*].if)
+  - Step `run:` scripts (as environment variables, not expressions)
+  - Step `with:` input values
+
+  `env` context is NOT available at:
+  - Job-level `if:` conditions (jobs.<job-id>.if)
+  - Workflow-level `env:` values (cannot reference other env vars defined in the same block)
+
+  A common mistake pattern:
+    env:
+      DEPLOY_ENV: production
+
+    jobs:
+      deploy:
+        if: env.DEPLOY_ENV == 'production'   # FAILS — env not available at job level
+        runs-on: ubuntu-latest
+
+  GitHub's expression evaluator may report "Context access might be invalid: env" as
+  a workflow validation warning, OR silently evaluate env.DEPLOY_ENV as an empty string
+  causing `if:` to evaluate to false — the job is skipped with no error message, only
+  a "skipped" status in the Actions UI.
+
+  The silent skip variant is especially deceptive: the workflow validates without error,
+  the job always shows as "skipped", and the developer assumes a logic error rather than
+  a context availability limitation.
+fix: |
+  At job-level `if:` conditions, use context types that ARE available:
+
+  1. vars context (repository/environment/org variables set in GitHub Settings):
+       jobs:
+         deploy:
+           if: vars.DEPLOY_ENV == 'production'
+
+  2. inputs context (workflow_dispatch or workflow_call inputs):
+       jobs:
+         deploy:
+           if: inputs.environment == 'production'
+
+  3. github context properties (branch, event type, actor, etc.):
+       jobs:
+         deploy:
+           if: github.ref == 'refs/heads/main'
+
+  4. needs.<job>.outputs (pass values from a prior job):
+       jobs:
+         setup:
+           outputs:
+             target_env: ${{ steps.detect.outputs.env }}
+         deploy:
+           needs: setup
+           if: needs.setup.outputs.target_env == 'production'
+
+  5. Move the condition to a step-level if: where env IS available:
+       jobs:
+         deploy:
+           runs-on: ubuntu-latest
+           steps:
+             - if: env.DEPLOY_ENV == 'production'
+               run: ./scripts/deploy.sh
+fix_code:
+  - language: yaml
+    label: "Use vars context at job-level if: (set variable in GitHub Settings)"
+    code: |
+      # Set DEPLOY_ENV in GitHub Settings → Secrets and Variables → Variables → Repository variables
+      jobs:
+        deploy:
+          # vars context IS available at job-level if:
+          if: vars.DEPLOY_ENV == 'production'
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./scripts/deploy.sh
+  - language: yaml
+    label: "Move env condition to step-level if: where env context is available"
+    code: |
+      env:
+        DEPLOY_ENV: production
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          # No job-level if: — condition is evaluated at the step level instead
+          steps:
+            - uses: actions/checkout@v4
+            - name: Deploy to production only
+              # env IS available at step-level if:
+              if: env.DEPLOY_ENV == 'production'
+              run: ./scripts/deploy.sh
+  - language: yaml
+    label: "Use workflow_dispatch input and inputs context at job level"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              type: choice
+              options: [staging, production]
+              required: true
+
+      jobs:
+        deploy:
+          # inputs context IS available at job-level if:
+          if: inputs.environment == 'production'
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./scripts/deploy.sh
+prevention:
+  - "Use vars, inputs, github, or needs.<job>.outputs contexts in job-level if: conditions — never env"
+  - "Reserve env context for step-level if: conditions and run: scripts where it is available"
+  - "Run actionlint — it warns about invalid context usage at each expression location, including env at job level"
+  - "GitHub workflow validation may only warn (not error) on invalid context access — always test conditions with a real workflow run before relying on them"
+  - "Consult the GitHub Docs context availability table to verify which contexts are valid at each expression location"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#context-availability"
+    label: "GitHub Docs — Context availability by expression location"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables"
+    label: "GitHub Docs — Storing information in variables (vars context)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/using-conditions-to-control-job-execution"
+    label: "GitHub Docs — Using conditions to control job execution"
+  - url: "https://github.com/orgs/community/discussions/29068"
+    label: "GitHub Community — env context not available in job-level if conditions"

package/package.json

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