@htekdev/actions-debugger 1.0.46 → 1.0.48

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/permissions-auth/permissions-auth-036.yml

@@ -0,0 +1,96 @@
+id: permissions-auth-036
+title: 'GITHUB_TOKEN cannot push commits to branches protected by "Require signed commits" — token identity cannot sign'
+category: permissions-auth
+severity: error
+tags:
+  - github-token
+  - signed-commits
+  - branch-protection
+  - gpg
+  - push
+  - protected-branch
+patterns:
+  - regex: 'GH006.*Protected branch.*signed|Commits must have verified signatures'
+    flags: 'i'
+  - regex: 'Changes must be signed|protected branch.*signed.*commits'
+    flags: 'i'
+error_messages:
+  - 'remote: error: GH006: Protected branch update failed for refs/heads/main.'
+  - 'remote: error: Commits must have verified signatures.'
+  - 'remote: error: Changes must be signed.'
+root_cause: |
+  GitHub's "Require signed commits" branch protection rule requires every pushed commit
+  to carry a verified GPG or SSH signature. The GITHUB_TOKEN is a short-lived bearer token
+  scoped to a workflow run — it has no associated GPG or SSH signing key and cannot produce
+  verified commit signatures.
+
+  This means any workflow that creates commits and pushes them using GITHUB_TOKEN will fail
+  on branches protected by "Require signed commits", regardless of the token's permission
+  level. Having contents: write permission is necessary but not sufficient: the signature
+  requirement is enforced by a separate push hook after permission checks pass.
+
+  Common workflow patterns that hit this:
+  - Auto-commit actions (stefanzweifel/auto-commit-action, EndBug/add-and-commit) that
+    commit generated files (changelogs, coverage badges, built assets) back to main
+  - Release workflows that bump version numbers in committed files before tagging
+  - Automated dependency update workflows that commit lockfile changes
+  - Documentation generation workflows that commit generated API docs or OpenAPI specs
+
+  The GH006 error appears in the push step's output but the job may not fail loudly if
+  the step's exit code is not checked carefully. In some auto-commit actions, the failure
+  surfaces as an unexpected empty push with no error surfaced to the workflow summary.
+fix: |
+  Option 1 — Create a pull request instead of direct push (recommended): Use
+  peter-evans/create-pull-request or similar to push the auto-generated commit to a
+  feature branch, then open a PR. Feature branches are not subject to the main branch's
+  "Require signed commits" protection.
+
+  Option 2 — GitHub App with bypass: Create a GitHub App and add it to the branch
+  protection "Allow specific actors to bypass required pull request reviews and required
+  status checks" bypass list. Generate tokens for the App in the workflow and push with
+  the App token. The App's bot commits can bypass the signed-commits requirement if
+  explicitly listed as a bypass actor.
+
+  Option 3 — Signed commits via GitHub App SSH key: Configure a GitHub App with an
+  SSH signing key. Use the App installation token and the App's SSH key for commit
+  signing via GIT_COMMITTER_EMAIL and gpg.format = ssh configuration.
+
+  The GITHUB_TOKEN itself cannot be configured for commit signing — this is a platform
+  limitation with no in-token workaround.
+fix_code:
+  - language: yaml
+    label: 'Create a pull request instead of pushing directly — avoids signed commits requirement on main'
+    code: |
+      jobs:
+        update-generated:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: write
+            pull-requests: write
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Regenerate files
+              run: make generate
+
+            - name: Create pull request for generated output
+              uses: peter-evans/create-pull-request@v7
+              with:
+                commit-message: 'chore: regenerate auto-generated files'
+                branch: automated/regenerate-output
+                title: 'chore: automated file regeneration'
+                body: 'Automated regeneration triggered by CI. Merge after review.'
+                # Commit targets the feature branch, not main — signed-commits rule on
+                # main does not apply to the automated/ branch
+prevention:
+  - 'Before enabling "Require signed commits" on a branch, audit all workflows that push commits using GITHUB_TOKEN to that branch'
+  - 'Use the create-pull-request pattern for auto-generated commits rather than pushing directly to protected branches'
+  - 'Document in workflow files that GITHUB_TOKEN cannot push to branches with signed-commits protection'
+  - 'If a GitHub App bypass is used, rotate the App private key regularly and scope permissions to the minimum required'
+docs:
+  - url: 'https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-signed-commits'
+    label: 'GitHub Docs: Require signed commits branch protection'
+  - url: 'https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification'
+    label: 'GitHub Docs: About commit signature verification'
+  - url: 'https://github.com/orgs/community/discussions/13836'
+    label: 'GitHub Community #13836: GITHUB_TOKEN cannot push to branch requiring signed commits'

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

@@ -0,0 +1,100 @@
+id: runner-environment-103
+title: "actions/setup-go cache skipped with 'no file matched go.sum' when go.sum is absent or not at workspace root"
+category: runner-environment
+severity: warning
+tags:
+  - setup-go
+  - go
+  - cache
+  - go-sum
+  - monorepo
+  - cache-miss
+  - cache-dependency-path
+patterns:
+  - regex: 'No file.*matched.*go\.sum|go\.sum.*not.*found.*cache'
+    flags: 'i'
+  - regex: 'setup-go.*cache.*skip|Unable to find.*go\.sum'
+    flags: 'i'
+error_messages:
+  - 'Warning: No file in /home/runner/work/repo/repo matched to [**/go.sum, !**/vendor/**], make sure you have checked out the target repository'
+  - 'go.sum not found, module cache will not be saved'
+  - 'Cache miss — no go.sum file located at expected path'
+root_cause: |
+  actions/setup-go uses go.sum as the cache key hash source. When cache: true (the default
+  since setup-go@v4), the action runs hashFiles('**/go.sum') to compute the cache key.
+  If no go.sum file is found anywhere in the workspace, the action emits a warning and
+  silently skips saving and restoring the module cache entirely — the job continues with
+  exit 0 but all Go dependencies are downloaded from scratch on every run.
+
+  Common root causes:
+
+  1. New project: go mod tidy has not been run — go.sum does not yet exist in the repo.
+
+  2. Monorepo layout: Go modules live under subdirectories (e.g., services/api/go.sum).
+     The default glob **/go.sum should find nested files, but when combined with the
+     !**/vendor/** exclusion or when the repo structure is non-standard, detection can fail.
+
+  3. Go workspace (go.work): modules are organized under subdirectories managed by a
+     go.work file; individual go.sum files may be present but not at the expected root.
+
+  4. Ordering issue: actions/setup-go runs before actions/checkout, so go.sum is not
+     yet in the workspace when the cache key is computed.
+
+  5. go.sum is listed in .gitignore (non-standard but seen in internal tooling repos
+     that regenerate dependencies on every run).
+
+  The missing-cache warning is only visible in the setup-go step's log output and does
+  not fail the workflow. On large Go projects, silent cache bypass wastes 60-120+ seconds
+  downloading modules from proxy.golang.org on every CI run.
+fix: |
+  For monorepo or nested module layouts, explicitly set cache-dependency-path to the
+  location of the go.sum file(s). A glob pattern can match multiple modules if needed.
+
+  For new projects: run go mod tidy locally and commit go.sum before pushing.
+
+  For go.work workspaces: list each module's go.sum explicitly in cache-dependency-path
+  to ensure all modules participate in the cache key.
+
+  Always confirm actions/checkout runs before actions/setup-go in the steps list.
+fix_code:
+  - language: yaml
+    label: 'Set cache-dependency-path for a nested module in a monorepo'
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+
+        - uses: actions/setup-go@v5
+          with:
+            go-version: '1.22'
+            cache: true
+            # Explicit path overrides default glob — required when go.sum is not at repo root
+            cache-dependency-path: services/api/go.sum
+
+  - language: yaml
+    label: 'Multiple modules in a go.work workspace — list all go.sum paths'
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+
+        - uses: actions/setup-go@v5
+          with:
+            go-version: '1.22'
+            cache: true
+            # Multi-line value: each module go.sum contributes to the aggregate cache key
+            cache-dependency-path: |
+              services/api/go.sum
+              services/worker/go.sum
+              pkg/shared/go.sum
+prevention:
+  - 'Always run go mod tidy before the first commit to ensure go.sum exists in the repository'
+  - 'In monorepos, explicitly set cache-dependency-path rather than relying on the default **/go.sum glob'
+  - 'Check the setup-go step output for "No file matched" warnings — caching may be silently disabled without failing the job'
+  - 'Ensure actions/checkout runs before actions/setup-go so go.sum is present when the cache key is computed'
+  - 'Never add go.sum to .gitignore — it is required for reproducible builds and module cache keying'
+docs:
+  - url: 'https://github.com/actions/setup-go#caching-dependency-files-and-build-outputs'
+    label: 'actions/setup-go: Caching dependency files and build outputs'
+  - url: 'https://github.com/actions/setup-go/issues/289'
+    label: 'setup-go #289: Cache fails when go.sum not at repository root'
+  - url: 'https://docs.github.com/en/actions/use-cases-and-examples/building-and-testing/building-and-testing-go'
+    label: 'GitHub Docs: Building and testing Go'

package/errors/silent-failures/silent-failures-051.yml

@@ -0,0 +1,107 @@
+id: silent-failures-051
+title: 'environment.url expression evaluates to empty string when referencing steps.*.outputs — resolved before steps run'
+category: silent-failures
+severity: silent-failure
+tags:
+  - environment
+  - deployment-url
+  - step-outputs
+  - expression-evaluation
+  - dynamic-url
+  - deployment-widget
+patterns:
+  - regex: 'environment.*url.*steps\.\w+\.outputs\.\w+'
+    flags: 'i'
+  - regex: 'deployment.*url.*empty|environment.*url.*not.*set|page_url.*empty'
+    flags: 'i'
+error_messages:
+  - 'Deployment environment shows no URL in GitHub UI despite environment.url referencing a step output'
+  - 'Deployment URL is empty string — steps.deploy.outputs.url is non-empty in the step logs'
+root_cause: |
+  The jobs.<id>.environment.url field is evaluated at job scheduling time — before ANY steps
+  in the job have run and before any step outputs exist. Expressions that reference
+  steps.*.outputs.* from the same job silently resolve to empty string. GitHub does not
+  emit a warning or error when this occurs.
+
+  This is a fundamental evaluation ordering constraint: the environment block (both name and
+  url) is part of the workflow plan GitHub evaluates once when the job is queued. The job
+  has not yet started, so step outputs are undefined and resolve to empty.
+
+  Contexts SAFE to use in environment.url (available at scheduling time):
+  - github.* — static for the run
+  - vars.* — repository/org/environment variables
+  - inputs.* — workflow_dispatch or workflow_call inputs
+  - needs.<prior-job>.outputs.* — outputs from already-completed upstream jobs
+  - env.* declared at the job level
+
+  Contexts that silently resolve to empty in environment.url:
+  - steps.*.outputs.* — step has not run yet
+  - steps.*.conclusion / steps.*.outcome — step has not run yet
+  - Any runtime-computed value from within the same job
+
+  Common scenario: a deploy step creates a preview URL (e.g., Vercel preview, Heroku review
+  app, AWS CloudFormation output), writes it to GITHUB_OUTPUT, and the developer tries to
+  surface it via environment.url so it appears in the GitHub deployment widget on the PR.
+  The widget shows no URL, and no error is ever raised.
+fix: |
+  Route the dynamic deployment URL through job outputs of the deploy job, then reference
+  needs.deploy.outputs.<name> in a dependent job's environment.url. The needs context IS
+  available at scheduling time for downstream jobs because the upstream job has already
+  completed.
+
+  For cases where the URL can be computed entirely from pre-execution contexts (github.ref_name,
+  inputs.*, vars.*), use a static URL expression directly in environment.url without
+  any step output dependency.
+fix_code:
+  - language: yaml
+    label: 'Two-job pattern — expose deployment URL as job output, reference via needs in downstream job'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          outputs:
+            # Promote step output to job output — available to downstream jobs via needs
+            app_url: ${{ steps.deploy.outputs.url }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Deploy
+              id: deploy
+              run: |
+                DEPLOY_URL="https://preview-${{ github.run_id }}.example.com"
+                echo "url=${DEPLOY_URL}" >> $GITHUB_OUTPUT
+
+        link-deployment:
+          needs: deploy
+          runs-on: ubuntu-latest
+          environment:
+            name: preview
+            # needs.deploy.outputs.* resolves correctly — deploy job already completed
+            url: ${{ needs.deploy.outputs.app_url }}
+          steps:
+            - run: echo "Linked deployment to ${{ needs.deploy.outputs.app_url }}"
+
+  - language: yaml
+    label: 'Static URL pattern using pre-execution context (no step output dependency)'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          environment:
+            name: preview
+            # github.ref_name is available at scheduling time — always resolves correctly
+            url: 'https://preview-${{ github.ref_name }}.example.com'
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "deploying..."
+prevention:
+  - 'Never reference steps.*.outputs.* directly in environment.url — promote to a job output and reference via needs in a downstream job instead'
+  - 'Test environment.url by checking the deployment widget on a pull request — an empty URL indicates the expression evaluated to empty string at scheduling time'
+  - 'Document the two-job deploy-then-link pattern in team workflow templates to prevent rediscovery'
+  - 'If the URL requires a step output, always add an outputs: block to the job and reference it via needs.<job>.outputs.<name> in a downstream job'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment'
+    label: 'GitHub Docs: jobs.<job_id>.environment syntax'
+  - 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/9366'
+    label: 'GitHub Community #9366: Dynamic environment URL from step output resolves to empty'

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

@@ -0,0 +1,73 @@
+id: triggers-036
+title: 'branches-ignore filter does not suppress tag pushes — tags always fire unless tags-ignore is also specified'
+category: triggers
+severity: silent-failure
+tags:
+  - push
+  - branches-ignore
+  - tags
+  - tag-push
+  - filter
+  - trigger-bypass
+patterns:
+  - regex: 'on.*push.*branches-ignore|branches-ignore.*\*\*'
+    flags: 'i'
+  - regex: 'tag.*push.*trigger.*unexpected|branches-ignore.*tags.*still.*fire'
+    flags: 'i'
+error_messages:
+  - "Workflow triggered by tag push despite branches-ignore: ['**'] — expected no branch pushes to trigger"
+  - 'v1.2.3 tag push fires a workflow that should only run on branch pushes'
+root_cause: |
+  GitHub Actions push event filters (branches:, branches-ignore:, paths:, paths-ignore:) apply
+  only to branch-ref pushes. Tag pushes target a refs/tags/* ref, not a refs/heads/* ref, and
+  are entirely unaffected by branch filters.
+
+  When a workflow declares on: push with branches-ignore: but no tags: or tags-ignore: filter,
+  all tag pushes trigger the workflow unconditionally regardless of the branch filter.
+
+  A critical misunderstanding: adding branches-ignore: ['**'] looks like it "disables all push
+  triggers" but it only disables branch pushes. Tag pushes still fire unconditionally.
+
+  GitHub documentation states that push event filters are independent per ref type: branch
+  filters only affect refs/heads/* pushes, and tag filters only affect refs/tags/* pushes.
+  They do not compose across ref types — setting one does not implicitly filter the other.
+
+  Consequence: release tag pushes (v1.2.3) trigger CI and CD workflows not designed for them,
+  potentially running expensive test suites or deploying artifacts on every version tag.
+  This is among the top-voted GitHub Community questions about push event triggers and
+  appears repeatedly in Stack Overflow answers on the [github-actions] tag.
+fix: |
+  Add an explicit tags-ignore: ['**'] filter to prevent all tag pushes from triggering the
+  workflow. Alternatively, use an explicit branches: allowlist — but note that branch
+  allowlists also do not suppress tag pushes; tags-ignore: is always required separately.
+
+  For workflows intended ONLY for tags (release workflows), remove branches filters entirely
+  and add tags: with the desired semver glob pattern.
+fix_code:
+  - language: yaml
+    label: 'Add tags-ignore to explicitly suppress all tag pushes alongside branches-ignore'
+    code: |
+      on:
+        push:
+          branches-ignore:
+            - 'dependabot/**'
+          tags-ignore:
+            - '**'    # Required — branches-ignore does NOT suppress tag pushes
+  - language: yaml
+    label: 'Release workflow — run only on semver tags, no branch triggers'
+    code: |
+      on:
+        push:
+          tags:
+            - 'v[0-9]+.[0-9]+.[0-9]+'    # Only fires on semver tags like v1.2.3
+          # No branches filter — exclusive tag-only trigger
+prevention:
+  - "When adding branches or branches-ignore filters, always decide explicitly whether tag pushes should be included or excluded — then set tags: or tags-ignore: accordingly"
+  - 'Use actionlint to validate push trigger filter combinations before committing'
+  - 'Document the intent in workflow comments: "This workflow runs on branch pushes only. Tag pushes excluded via tags-ignore."'
+  - 'Audit release tag workflows to confirm they use tags: filters rather than relying on implicit gaps in branch filters'
+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 — filter pattern cheat sheet'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpushbranchestagsbranches-ignoretags-ignore'
+    label: 'GitHub Docs: on.push branches/tags filter syntax'

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