@htekdev/actions-debugger 1.0.46 → 1.0.47

package/errors/concurrency-timing/concurrency-timing-028.yml

@@ -0,0 +1,97 @@
+id: concurrency-timing-028
+title: "Matrix job outputs use last-writer-wins — only the final completing matrix instance's value is visible to downstream jobs"
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - matrix
+  - outputs
+  - last-writer-wins
+  - job-outputs
+  - needs
+  - aggregation
+patterns:
+  - regex: 'jobs\.\w+\.outputs\.\w+'
+    flags: "i"
+  - regex: 'matrix.*output.*empty|matrix.*output.*missing|output.*only.*one.*matrix'
+    flags: "i"
+error_messages:
+  - "Job output contains only one matrix item's value despite all matrix jobs completing successfully"
+  - "Downstream job receives empty string from needs.<job>.outputs.<name> after matrix build"
+root_cause: |
+  When a matrix strategy job writes to GITHUB_OUTPUT, all parallel matrix instances share
+  the same output key namespace keyed at the logical job ID level in the workflow DAG.
+  Multiple matrix runners mapping to one job ID race to write the same output keys. The
+  last matrix runner to flush its output to the Actions service wins — all prior values for
+  that key are silently overwritten.
+
+  GitHub Docs state explicitly: "The value of the output is the last value set by the
+  expression that evaluates the output." There is no merge, append, or aggregation of
+  outputs across matrix instances.
+
+  Common manifestations:
+  - A release matrix collecting artifact paths — the downstream job sees only one path
+  - A test matrix emitting pass/fail status per OS — only the last-completing OS result survives
+  - A build matrix producing version or hash strings — final output value is non-deterministic
+    and varies by runner scheduling order, making the issue intermittent and hard to reproduce
+
+  This is an intentional platform constraint. The job outputs map is a flat key-value store
+  keyed at the job level, not the matrix-instance level. It cannot store per-instance values.
+fix: |
+  Aggregate matrix results via uniquely-named artifacts rather than job outputs.
+
+  Strategy: each matrix instance uploads its result as a named artifact that includes the
+  matrix dimension in the artifact name (required by actions/upload-artifact@v4 anyway, which
+  rejects duplicate names). The fan-in dependent job downloads all artifacts and processes
+  them together.
+
+  For simple pass/fail aggregation, rely on the default needs: behavior — a job with
+  needs: [build] only starts when ALL matrix instances of build have completed successfully.
+  No custom output collection is needed for overall-success gating.
+fix_code:
+  - language: yaml
+    label: "Aggregate matrix results via uniquely-named artifacts (recommended pattern)"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              os: [ubuntu-latest, windows-latest, macos-latest]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Build and capture result
+              run: echo "artifact-for-${{ matrix.os }}" > result.txt
+
+            - name: Upload per-matrix artifact
+              uses: actions/upload-artifact@v4
+              with:
+                # Matrix dimension in name prevents v4 duplicate-name error
+                name: build-result-${{ matrix.os }}
+                path: result.txt
+
+        release:
+          needs: build    # Waits for ALL matrix instances to succeed
+          runs-on: ubuntu-latest
+          steps:
+            - name: Download all matrix results
+              uses: actions/download-artifact@v4
+              with:
+                pattern: build-result-*
+                merge-multiple: true
+                path: results/
+
+            - name: Process aggregated results
+              run: ls results/ && cat results/result.txt
+prevention:
+  - "Never rely on GITHUB_OUTPUT in matrix jobs to pass per-instance values to downstream jobs"
+  - "Always include the matrix dimension in artifact names when uploading from matrix jobs"
+  - "Use needs: [job] to gate on all matrix instances succeeding — no custom output collection needed for pass/fail"
+  - "Add a workflow comment documenting that the fan-in pattern is required for multi-value matrix aggregation"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs"
+    label: "GitHub Docs: Passing information between jobs"
+  - url: "https://github.com/orgs/community/discussions/26286"
+    label: "GitHub Community #26286: Matrix job outputs — last writer wins"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idoutputs"
+    label: "GitHub Docs: jobs.<job_id>.outputs"

package/errors/concurrency-timing/concurrency-timing-029.yml

@@ -0,0 +1,92 @@
+id: concurrency-timing-029
+title: "cancel-in-progress: true does not release a deployment environment lock — subsequent runs wait indefinitely"
+category: concurrency-timing
+severity: error
+tags:
+  - concurrency
+  - cancel-in-progress
+  - deployment-environment
+  - environment-lock
+  - queue-stall
+  - protection-rules
+patterns:
+  - regex: 'waiting.*deployment.*environment|environment.*lock.*not.*released'
+    flags: "i"
+  - regex: 'deployment.*stuck.*waiting|cancel.*in.*progress.*environment.*stall'
+    flags: "i"
+error_messages:
+  - "Deployment stuck in 'Waiting for deployment' state after previous run was cancelled"
+  - "Job has been waiting for a deployment to complete for over N minutes"
+root_cause: |
+  GitHub Actions deployment environments use a distributed lock to ensure only one workflow
+  run deploys to an environment at a time. When a job is cancelled while holding or waiting
+  for an environment lock, the lock release is not guaranteed to be atomic with the cancellation.
+
+  The race condition sequence:
+  1. Run A acquires the environment lock and begins deploying
+  2. Run B starts, enters "Waiting for deployment" state (environment locked by A)
+  3. Run C triggers with cancel-in-progress: true — Run B (the waiting run) is cancelled
+  4. Run A completes and releases its lock
+  5. Run C's deploy job is now queued but sees the environment still showing a pending entry
+     from the cancelled Run B, causing it to wait indefinitely
+
+  A separate scenario: Run A itself is cancelled mid-deploy. The environment can enter
+  a "deployment in progress" limbo state where no active run owns the lock but the
+  environment page still shows a pending deployment. New runs queue successfully but
+  hang waiting for a lock that will never be released automatically.
+
+  This is exacerbated on active repos where pushes arrive faster than deploy jobs complete,
+  causing continuous queue stalls on the environment.
+fix: |
+  Separate the concurrency group into two distinct layers: one for build/test jobs
+  (safe to cancel freely) and one for deploy jobs (must serialize to completion).
+
+  Build jobs use cancel-in-progress: true — wasteful test runs are discarded when
+  a newer commit arrives. Deploy jobs use cancel-in-progress: false — they run to
+  completion serially, preventing mid-deploy cancellations that create lock limbo.
+
+  Set timeout-minutes on all deploy jobs so stuck environment waits self-resolve with
+  a clear failure rather than hanging for the job's default 6-hour timeout.
+
+  To manually recover a stalled environment: navigate to Settings → Environments →
+  select the stalled environment → cancel any pending deployment entries in the UI.
+fix_code:
+  - language: yaml
+    label: "Separate concurrency groups — cancel builds freely, serialize deploys safely"
+    code: |
+      jobs:
+        build:
+          # Cancel in-progress builds freely — no environment lock at stake
+          concurrency:
+            group: build-${{ github.ref }}
+            cancel-in-progress: true
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "build and test steps"
+
+        deploy:
+          needs: build
+          environment: production
+          # NEVER cancel in-progress deploy jobs — let them finish to avoid lock limbo
+          concurrency:
+            group: deploy-production
+            cancel-in-progress: false
+          timeout-minutes: 30    # Self-heal on stuck environment wait (default is 6h)
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "deploy steps here"
+prevention:
+  - "Never use cancel-in-progress: true on jobs that target a deployment environment"
+  - "Always set timeout-minutes on deploy jobs — the default 6-hour timeout makes stalls very painful"
+  - "Use separate concurrency groups for build (cancel-friendly) vs deploy (serialize) stages"
+  - "Monitor the Environments page for stale 'Deployment pending' entries after CI incidents"
+  - "Consider dedicated environment concurrency groups (e.g., deploy-production vs deploy-staging) to prevent cross-environment interference"
+docs:
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment"
+    label: "GitHub Docs: Managing environments for deployment"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#concurrency"
+    label: "GitHub Docs: Workflow concurrency"
+  - url: "https://github.com/orgs/community/discussions/14490"
+    label: "GitHub Community #14490: cancel-in-progress and deployment environment lock"

package/errors/triggers/triggers-034.yml

@@ -0,0 +1,87 @@
+id: triggers-034
+title: "New workflow file added in a PR branch does not trigger — workflows only activate after merging to the default branch"
+category: triggers
+severity: limitation
+tags:
+  - triggers
+  - new-workflow
+  - pr-branch
+  - default-branch
+  - known-limitation
+  - onboarding
+patterns:
+  - regex: 'workflow.*not.*trigger.*pull.request|new.*workflow.*file.*no.*run'
+    flags: "i"
+  - regex: '\.github.workflows.*pr.*not.*running|workflow.*added.*branch.*not.*firing'
+    flags: "i"
+error_messages:
+  - "New workflow file added in PR branch produces no workflow runs — the Actions tab shows nothing for the PR"
+  - "Workflow YAML exists on PR branch but no jobs are queued for push or pull_request events"
+root_cause: |
+  GitHub Actions only executes workflow files that exist on the repository's default
+  branch (usually main or master). When a new workflow YAML file is added inside a
+  pull request branch, GitHub does NOT execute that workflow for any event on that
+  branch — not for the push that added the file, not for subsequent pushes to the branch,
+  and not for the pull_request event generated when the PR was opened.
+
+  This is an intentional security boundary. Executing arbitrary workflow files from
+  unreviewed feature branches would allow any contributor to inject CI code that runs
+  with write permissions before a maintainer has reviewed it.
+
+  GitHub's documentation states: "A workflow is triggered by an event that occurs in the
+  repository where the workflow file lives." The key constraint is that "lives" means on
+  the default branch — not just anywhere in the repository's file tree.
+
+  Consequences:
+  - A PR that adds the first CI workflow for a repo produces zero CI runs
+  - A PR adding a new required status check workflow blocks itself forever (the check
+    never posts because the workflow doesn't exist on the default branch)
+  - New workflow features cannot be validated via CI during the PR review itself
+fix: |
+  To test a new workflow file before merging:
+  1. Temporarily push just the workflow file directly to the default branch (main/master)
+  2. Manually trigger it via workflow_dispatch from the Actions tab to verify it runs correctly
+  3. Then open (or reopen) the feature PR — the workflow now exists on the default branch
+     and will run against the PR
+
+  For local testing before any push: use nektos/act to run the workflow locally against
+  your branch checkout. This validates the YAML and execution logic without needing the
+  file on the default branch.
+
+  For required status checks: never add a branch protection required status check for a
+  workflow that does not yet exist on the default branch — the check will never post a
+  result and the PR will be permanently blocked with no path to merge.
+fix_code:
+  - language: yaml
+    label: "Always include workflow_dispatch to enable manual testing immediately after the first merge"
+    code: |
+      # New workflow — add workflow_dispatch so it is testable the moment it lands on main
+      name: CI
+
+      on:
+        push:
+          branches: [main]
+        pull_request:
+          branches: [main]
+        workflow_dispatch:    # Allows manual trigger from the Actions tab once merged
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run tests
+              run: echo "workflow is now active on default branch"
+prevention:
+  - "Merge a minimal 'smoke test' version of the workflow to the default branch first to activate it, then expand in the feature PR"
+  - "Include workflow_dispatch in all new workflows to enable immediate manual testing after the first merge"
+  - "Use nektos/act for local workflow testing before pushing — validates logic without needing the file on main"
+  - "Never add a required status check for a workflow that does not yet exist on the default branch"
+  - "Document in PR description that new workflows require a prior bootstrap merge to main before CI shows results"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow"
+    label: "GitHub Docs: Triggering a workflow"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#understanding-the-risk-of-script-injections"
+    label: "GitHub Docs: Security hardening — script injection risks"
+  - url: "https://github.com/nektos/act"
+    label: "nektos/act — Run GitHub Actions workflows locally"

package/errors/triggers/triggers-035.yml

@@ -0,0 +1,114 @@
+id: triggers-035
+title: "push: paths: filter silently prevents workflow from running on tag pushes — tags don't modify files"
+category: triggers
+severity: silent-failure
+tags:
+  - push
+  - paths-filter
+  - tags
+  - silent-skip
+  - tag-push
+  - release
+patterns:
+  - regex: 'push.*tags.*paths.*not.*trigger|tag.*push.*paths.*filter.*skip'
+    flags: "i"
+  - regex: 'release.*workflow.*not.*run.*tag|on\.push.*paths.*tags.*silent'
+    flags: "i"
+error_messages:
+  - "Release workflow does not trigger on tag push when push: paths: filter is present"
+  - "Tag v1.0.0 pushed but no workflow run created — paths filter silently blocking trigger"
+root_cause: |
+  When a GitHub Actions push trigger includes both tags: and paths: conditions, GitHub
+  evaluates BOTH conditions using AND logic — the event must match the tag pattern AND
+  at least one file in the push must match the paths pattern. A tag push (e.g., v1.0.0)
+  creates a new ref pointing to an existing commit without modifying any file contents.
+  Because no files are changed, the paths: filter never matches, and the workflow
+  silently does not run.
+
+  Example trigger block that silently fails on all tag pushes:
+
+    on:
+      push:
+        branches: [main]
+        tags: ['v*']
+        paths: ['src/**', 'package.json']   # blocks ALL tag triggers — tags change no files
+
+  YAML does not support duplicate map keys, so two separate on: push: blocks are not
+  possible in the same workflow file. The paths: filter applies globally to every push
+  event evaluated by that trigger block, including tag pushes.
+
+  This is commonly introduced when developers add a paths: filter to an existing release
+  workflow to avoid running expensive builds on documentation commits, inadvertently
+  also filtering out all tag-triggered release runs. The workflow appears to work on
+  branch pushes (which do change files) while silently never running on tag pushes.
+fix: |
+  Option 1 (recommended): Replace push: tags: with the release event. The release event
+  fires when a GitHub Release is published from a tag and has no paths filter concept.
+  This also provides richer release metadata (release notes, asset URLs) via github.event.
+
+  Option 2: Remove paths: from the trigger and use an if: condition on jobs to skip
+  non-relevant branch pushes. The job runs for all tag pushes unconditionally, and
+  runs for branch pushes only when the if: condition evaluates to true based on
+  changed file data or event type.
+
+  Option 3: Use paths-ignore: instead of paths: with an inverted pattern. This approach
+  still silently blocks tag pushes (same AND-logic issue), so it should only be combined
+  with Option 1 or 2.
+fix_code:
+  - language: yaml
+    label: "Replace push: tags: with release event — no paths filter interference"
+    code: |
+      on:
+        push:
+          branches: [main]
+          paths:
+            - 'src/**'
+            - 'package.json'
+        # Use release event for tag-based release workflows
+        # Fires on Release published — no paths filter concept applies
+        release:
+          types: [published]
+
+      jobs:
+        build-and-release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "runs on branch push matching paths AND on release publish"
+  - language: yaml
+    label: "Remove paths: and guard branch pushes with if: condition instead"
+    code: |
+      on:
+        push:
+          branches: [main]
+          tags: ['v*.*.*']
+          # No paths: filter — use if: condition on job to skip irrelevant branch pushes
+
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          # Always run on tag pushes; on branch pushes only if relevant files changed
+          if: startsWith(github.ref, 'refs/tags/')
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "only runs on tag pushes"
+
+        ci:
+          runs-on: ubuntu-latest
+          # Separate job for branch-push CI with file-change guard
+          if: "!startsWith(github.ref, 'refs/tags/')"
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "only runs on branch pushes"
+prevention:
+  - "Never mix tags: and paths: in the same push trigger block — paths filter applies to tag pushes too"
+  - "Use the release event instead of push: tags: for release workflows to avoid paths filter confusion"
+  - "After adding a paths: filter to any workflow, test by pushing a tag to verify release triggering still works"
+  - "Add a comment near any paths: filter warning that it will also suppress tag-push triggers in the same block"
+docs:
+  - 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 and filters"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#release"
+    label: "GitHub Docs: release event trigger"
+  - url: "https://github.com/orgs/community/discussions/25597"
+    label: "GitHub Community #25597: paths filter prevents tag-triggered workflow runs"

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

@@ -0,0 +1,114 @@
+id: yaml-syntax-035
+title: "Unquoted YAML value starting with ${{ expression }} causes parse error — { triggers flow mapping syntax"
+category: yaml-syntax
+severity: error
+tags:
+  - yaml
+  - expressions
+  - quoting
+  - parse-error
+  - flow-mapping
+  - workflow-syntax
+patterns:
+  - regex: 'mapping values are not allowed|did not find expected key'
+    flags: "i"
+  - regex: 'invalid workflow file.*yaml|yaml.*parse.*error.*expression'
+    flags: "i"
+error_messages:
+  - "Invalid workflow file: .github/workflows/workflow.yml#L12: mapping values are not allowed in this context"
+  - "You have an error in your yaml syntax on line X — expected a scalar value but found a mapping"
+root_cause: |
+  The YAML specification defines { as the start of a flow mapping (an inline key-value
+  dictionary). GitHub Actions expressions begin with ${{ — which contains { as the second
+  character. When a YAML scalar value starts with ${{ without surrounding quotes, most
+  YAML parsers interpret the opening { as the beginning of a flow mapping and produce a
+  parse error.
+
+  The YAML rule: any scalar value that would be ambiguous with YAML structure characters
+  (including { [ : > |) must be quoted. An unquoted value starting with ${{ violates
+  this rule.
+
+  Affected contexts:
+  - env: block values:      MY_VAR: ${{ secrets.TOKEN }}     ← parse error
+  - with: block inputs:     version: ${{ inputs.version }}   ← parse error
+  - name: step names:       name: ${{ matrix.os }} build     ← parse error in some parsers
+  - run: inline shell is safe — run: is a block scalar, expressions inside are not YAML values
+
+  The if: condition is a special case. GitHub Actions parses if: fields with implicit
+  expression wrapping, so if: github.ref == 'refs/heads/main' works without ${{ }}.
+  However, if: ${{ condition }} also works when quoted. Unquoted if: ${{ ... }} may
+  work in permissive parsers but is not spec-compliant.
+
+  actionlint and yamllint both flag unquoted expressions as errors. GitHub's own
+  workflow syntax checker may silently accept some cases while rejecting others,
+  making the error inconsistent across different fields.
+fix: |
+  Quote any YAML value that starts with ${{ using either single or double quotes.
+  Double quotes are standard; single quotes work equally well and may be preferred
+  when the expression contains double quote characters.
+
+  For multiline shell commands (run: | blocks), expressions inside the block scalar
+  do not need quoting — they are not parsed as YAML values.
+
+  For if: conditions, omit the ${{ }} wrapper entirely — GitHub Actions implicitly
+  wraps if: values in expression evaluation. Use: if: github.ref == 'refs/heads/main'
+  not if: ${{ github.ref == 'refs/heads/main' }}.
+fix_code:
+  - language: yaml
+    label: "Quote YAML values starting with ${{ to prevent YAML parse errors"
+    code: |
+      # Incorrect — unquoted values starting with ${{ cause YAML parse errors
+      jobs:
+        bad:
+          runs-on: ubuntu-latest
+          env:
+            MY_VAR: ${{ secrets.MY_SECRET }}          # parse error
+
+      # Correct — double-quoted (standard)
+      jobs:
+        good-double:
+          runs-on: ubuntu-latest
+          env:
+            MY_VAR: "${{ secrets.MY_SECRET }}"        # safe
+          steps:
+            - uses: actions/setup-node@v4
+              with:
+                node-version: "${{ inputs.node-version }}"
+
+      # Also correct — single-quoted
+      jobs:
+        good-single:
+          runs-on: ubuntu-latest
+          env:
+            MY_VAR: '${{ secrets.MY_SECRET }}'        # safe
+
+      # run: block scalar — no quoting needed inside |
+      jobs:
+        run-block:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Show SHA
+              run: |
+                echo ${{ github.sha }}                 # safe — inside block scalar
+
+      # if: — use bare expression without ${{ }} wrapper
+      jobs:
+        guarded:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Step only on main
+              if: github.ref == 'refs/heads/main'     # preferred — no ${{ }} needed
+              run: echo "on main"
+prevention:
+  - "Quote all YAML values that begin with ${{ — use double or single quotes consistently"
+  - "Install actionlint as a pre-commit hook to catch unquoted expression errors before push"
+  - "Use block scalar (|) for multi-line run: steps — no expression quoting needed inside block scalars"
+  - "For if: conditions, write bare expressions without the ${{ }} wrapper"
+  - "Enable GitHub's built-in YAML syntax check — push to a test branch and review the Actions tab immediately"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions"
+    label: "GitHub Docs: Workflow syntax for GitHub Actions"
+  - url: "https://rhysd.github.io/actionlint/"
+    label: "actionlint — static checker for GitHub Actions workflow files"
+  - url: "https://yaml.org/spec/1.2.2/#flow-mappings"
+    label: "YAML 1.2 spec: Flow mappings"

package/package.json

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