@htekdev/actions-debugger 1.0.45 → 1.0.47

package/errors/caching-artifacts/caching-artifacts-034.yml

@@ -0,0 +1,70 @@
+id: caching-artifacts-034
+title: "Cache entries created in a PR branch are not accessible from other PR branches or the default branch"
+category: caching-artifacts
+severity: limitation
+tags:
+  - cache
+  - branch-scope
+  - pull-request
+  - isolation
+  - cache-miss
+  - known-limitation
+patterns:
+  - regex: 'cache.*miss.*pull.request|cache.*not.*found.*branch|cache.*not.*accessible.*pr'
+    flags: "i"
+  - regex: 'cache.*scope.*branch|branch.specific.*cache.*miss|pr.*branch.*no.*cache'
+    flags: "i"
+error_messages:
+  - "Cache not found for input keys"
+root_cause: |
+  GitHub Actions cache entries are strictly scoped to the branch that created them. The
+  cache lookup order during a restore operation is:
+
+  1. Exact key match on the CURRENT branch
+  2. restore-keys prefix match on the CURRENT branch
+  3. restore-keys prefix match on the BASE branch (for PRs) or the DEFAULT branch
+
+  Consequences of this scoping:
+  - A cache saved on PR branch A is NOT readable from PR branch B
+  - A cache saved on a PR branch is NOT readable from the default branch's push workflow
+  - Each new PR starts with a cold cache until it produces its own branch-scoped entry
+  - The base branch cache is only available as a fallback during a PR workflow restore
+
+  This is an intentional security isolation boundary — one PR cannot read potentially
+  sensitive build artifacts cached by another PR. There is no configuration option to
+  enable cross-PR cache sharing.
+
+  Teams migrating from shared CI caches (Jenkins, GitLab with shared runner caches) are
+  frequently surprised by persistent cache misses across parallel PRs on active repos.
+fix: |
+  Structure cache keys and restore-keys to maximize fallback hits from the default branch.
+  The strategy: save a well-keyed cache on the default branch after each merge (readable
+  by all PRs as a fallback), and include base-branch and OS-only restore-key prefixes so
+  new PR runs warm up quickly via partial matches.
+
+  For dependency caches, a lockfile-hash-keyed entry on main ensures new PRs get a
+  near-hit on first run via restore-keys, rather than a completely cold cache.
+fix_code:
+  - language: yaml
+    label: "Cache key strategy that maximizes default-branch fallback for all PRs"
+    code: |
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          # Primary: exact branch + lockfile hash (hit on repeat runs of same PR)
+          key: ${{ runner.os }}-npm-${{ github.ref_name }}-${{ hashFiles('**/package-lock.json') }}
+          # Fallbacks: base branch (for PRs) → default branch → OS-only
+          restore-keys: |
+            ${{ runner.os }}-npm-${{ github.base_ref }}-
+            ${{ runner.os }}-npm-
+prevention:
+  - "Add restore-keys with base branch and OS-only prefixes so PRs fall back to main's cache"
+  - "Ensure the default branch workflow saves a fresh cache after each merge so PRs have a warm fallback"
+  - "Be aware that parallel PRs each maintain their own independent branch-scoped cache"
+  - "For monorepos, include the workspace or package path in the cache key to prevent cross-PR key collisions"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache"
+    label: "GitHub Docs: Cache access restrictions by branch"
+  - url: "https://github.com/orgs/community/discussions/10539"
+    label: "GitHub Community: Cache access is restricted to the same branch and base branches"

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

@@ -0,0 +1,87 @@
+id: known-unsolved-036
+title: "Scheduled workflows auto-disabled after 60 days of repository inactivity"
+category: known-unsolved
+severity: limitation
+tags:
+  - schedule
+  - cron
+  - inactivity
+  - disabled
+  - known-limitation
+  - maintenance
+patterns:
+  - regex: 'This scheduled workflow is disabled|scheduled workflow.*disabled.*no.*activity'
+    flags: "i"
+  - regex: 'schedule.*60.day.*inactiv|60.day.*no.*activity.*workflow'
+    flags: "i"
+error_messages:
+  - "This scheduled workflow is disabled because there has been no repository activity in the past 60 days"
+root_cause: |
+  GitHub automatically disables on: schedule workflows in repositories that have had no
+  activity (pushes, pull requests, merges) for 60 days. This is a platform resource
+  management decision to reduce compute on dormant repositories.
+
+  When triggered, the Actions tab displays a banner:
+  "This scheduled workflow is disabled because there has been no repository activity
+  in the past 60 days."
+
+  GitHub sends a notification email before disabling, but many maintainers miss it.
+
+  Common affected scenarios:
+  - Maintenance repos (dependency update jobs, reporting pipelines) with infrequent code changes
+  - Scheduled audit or monitoring workflows in stable, rarely-pushed codebases
+  - Open source repos that go quiet between releases
+  - Returning after extended leave to find weeks or months of scheduled runs silently missed
+
+  There is no workflow-level setting to prevent automatic disabling. The only remedies
+  are to manually re-enable via the GitHub UI or maintain repository activity artificially.
+fix: |
+  To re-enable a disabled scheduled workflow:
+  1. Navigate to the repository Actions tab
+  2. Select the disabled workflow in the left sidebar
+  3. Click the "Enable workflow" button shown in the banner
+
+  To prevent future auto-disabling, add a keep-alive workflow that creates an empty
+  commit on a schedule shorter than 60 days. Using stefanzweifel/git-auto-commit-action
+  with --allow-empty avoids modifying tracked files while still generating commit activity
+  that resets the 60-day counter.
+
+  There is no REST API endpoint to re-enable disabled scheduled workflows — it must be
+  done via the GitHub UI or by pushing a new commit to the repository.
+fix_code:
+  - language: yaml
+    label: "Keep-alive workflow — runs monthly to prevent schedule auto-disable"
+    code: |
+      # .github/workflows/keep-alive.yml
+      name: Keep Alive
+
+      on:
+        schedule:
+          - cron: '0 0 1 * *'    # First of each month — well within 60-day window
+        workflow_dispatch:
+
+      jobs:
+        keep-alive:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: write
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Maintain repository activity
+              uses: stefanzweifel/git-auto-commit-action@v5
+              with:
+                commit_message: 'chore: keep-alive [skip ci]'
+                commit_options: '--allow-empty'
+prevention:
+  - "Monitor the Actions tab for the 60-day inactivity warning banner"
+  - "Add a keep-alive workflow to all repos with important scheduled jobs but infrequent commits"
+  - "Subscribe to GitHub notification emails so the pre-disable warning is not missed"
+  - "Document this limitation in the repo CONTRIBUTING guide for future maintainers"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule"
+    label: "GitHub Docs: schedule trigger"
+  - url: "https://github.com/orgs/community/discussions/5614"
+    label: "GitHub Community #5614: Scheduled workflow disabled after 60 days of inactivity"
+  - url: "https://github.com/stefanzweifel/git-auto-commit-action"
+    label: "stefanzweifel/git-auto-commit-action — keep-alive commit pattern"

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

@@ -0,0 +1,93 @@
+id: silent-failures-050
+title: "continue-on-error: true on a failing step silently prevents if: failure() downstream steps from running"
+category: silent-failures
+severity: silent-failure
+tags:
+  - continue-on-error
+  - if-condition
+  - failure-check
+  - step-outcome
+  - silent-skip
+  - cleanup
+patterns:
+  - regex: 'continue.on.error.*if.*failure|if.*failure.*not.*running.*continue.on.error'
+    flags: "i"
+  - regex: 'cleanup.*step.*skipped.*continue.on.error|failure.*handler.*not.*triggered'
+    flags: "i"
+error_messages:
+  - "Downstream step with if: failure() silently skipped when preceding step uses continue-on-error: true"
+root_cause: |
+  When a step fails AND has continue-on-error: true, GitHub Actions marks that step's
+  conclusion as success (the error was absorbed) while preserving its outcome as failure.
+  Because the step conclusion is success, the job's overall result remains success.
+
+  Any downstream step or job conditioned on if: failure() evaluates the job's overall
+  status, not individual step outcomes. Since the job is still succeeding (the failure was
+  continued past), if: failure() evaluates to false — and those downstream steps are
+  silently skipped with no error or warning.
+
+  The pattern developers expect to work (but doesn't):
+
+    steps:
+      - name: Run tests
+        run: npm test
+        continue-on-error: true
+      - name: Upload failure report   # NEVER runs — job outcome is still 'success'
+        if: failure()
+
+  Silently broken patterns:
+  - Failure notification steps after continue-on-error test or lint steps
+  - Cleanup steps conditioned on job failure after a continued-on-error build
+  - Report upload or artifact save steps expected to fire when tests fail
+  - Alerting steps (Slack, PagerDuty) conditioned on failure() after a tolerated failure
+fix: |
+  Reference the specific failing step's outcome directly using steps.<id>.outcome
+  instead of the job-level failure() function. Give the step-with-continue-on-error an
+  explicit id: field, then condition the downstream step on
+  steps.<step-id>.outcome == 'failure'.
+
+  This correctly captures the step-level failure even when the job overall is succeeding.
+fix_code:
+  - language: yaml
+    label: "Wrong: if: failure() silently never fires after a continue-on-error step"
+    code: |
+      steps:
+        - name: Run tests
+          run: npm test
+          continue-on-error: true
+          # Job outcome stays 'success' — if: failure() below never executes
+
+        - name: Upload test failure report
+          if: failure()
+          uses: actions/upload-artifact@v4
+          with:
+            name: test-report
+            path: test-results/
+  - language: yaml
+    label: "Correct: check the specific step outcome to catch the continued failure"
+    code: |
+      steps:
+        - name: Run tests
+          id: run-tests           # Explicit ID required to reference outcome below
+          run: npm test
+          continue-on-error: true
+
+        - name: Upload test failure report
+          # Fires when tests failed — works correctly even though the job is still 'success'
+          if: steps.run-tests.outcome == 'failure'
+          uses: actions/upload-artifact@v4
+          with:
+            name: test-report
+            path: test-results/
+prevention:
+  - "Never rely on if: failure() to detect failures from steps that use continue-on-error: true"
+  - "Assign explicit id: to any step with continue-on-error that needs downstream conditional checks"
+  - "Use steps.<id>.outcome == 'failure' to condition steps on a specific earlier step's result"
+  - "Test failure-handler steps explicitly by temporarily forcing the upstream step to fail without continue-on-error"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-conditions-to-control-job-execution"
+    label: "GitHub Docs: Using conditions to control job execution"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#steps-context"
+    label: "GitHub Docs: steps context — outcome vs conclusion"
+  - url: "https://github.com/orgs/community/discussions/25420"
+    label: "GitHub Community: continue-on-error and if: failure() interaction explained"

package/errors/triggers/triggers-033.yml

@@ -0,0 +1,100 @@
+id: triggers-033
+title: "Commits, PRs, and releases created using GITHUB_TOKEN do not trigger new workflow runs"
+category: triggers
+severity: limitation
+tags:
+  - GITHUB_TOKEN
+  - loopback-prevention
+  - push-event
+  - pull-request
+  - no-trigger
+  - known-limitation
+patterns:
+  - regex: 'GITHUB_TOKEN.*push.*not.*trigger|workflow.*not.*triggered.*after.*commit'
+    flags: "i"
+  - regex: 'auto.commit.*no.*workflow|push.*token.*not.*firing.*CI'
+    flags: "i"
+error_messages:
+  - "Workflow not triggered after automated push using GITHUB_TOKEN"
+root_cause: |
+  GitHub Actions intentionally prevents new workflow runs from being triggered by events
+  performed with the built-in GITHUB_TOKEN. This loopback prevention exists to stop
+  accidental or malicious infinite workflow loops — for example, a push workflow that
+  commits back to the repo and re-triggers itself in perpetuity.
+
+  Affected operations when performed with GITHUB_TOKEN:
+  - Pushing a commit to a branch (no push event fired; CI does not run on the new SHA)
+  - Creating a pull request via REST API (no pull_request event fired; PR checks do not start)
+  - Publishing a release (no release event fired)
+  - Merging a PR programmatically (no push or pull_request closed event fired)
+
+  Common surprise scenarios:
+  - Auto-version-bump workflows that commit package.json and expect CI to run on the result
+  - Automated changelog commits that should trigger a docs publish pipeline
+  - Bots that open PRs using GITHUB_TOKEN expecting branch protection checks to start
+  - Tag-from-workflow jobs expecting the resulting tag push to start a release pipeline
+fix: |
+  To trigger new workflow runs from operations performed inside a workflow, use a Personal
+  Access Token (PAT) or a GitHub App installation token instead of GITHUB_TOKEN. Events
+  created with these tokens are not subject to the loopback prevention rule.
+
+  For organizational workflows, GitHub App tokens are the recommended approach — they
+  do not rely on a personal user's credentials and can be scoped to minimum permissions.
+
+  If triggering new runs is NOT needed, add [skip ci] to the commit message to make the
+  intent explicit and prevent accidental CI consumption if a PAT is used later.
+fix_code:
+  - language: yaml
+    label: "PAT-based checkout so the resulting push triggers downstream CI"
+    code: |
+      jobs:
+        version-bump:
+          runs-on: ubuntu-latest
+          steps:
+            # Check out with PAT — any subsequent push WILL trigger a new push workflow run
+            - uses: actions/checkout@v4
+              with:
+                token: ${{ secrets.MY_PAT }}
+
+            - name: Bump version
+              run: npm version patch --no-git-tag-version
+
+            - name: Commit and push version bump
+              uses: stefanzweifel/git-auto-commit-action@v5
+              with:
+                commit_message: 'chore: bump version'
+  - language: yaml
+    label: "GitHub App token so an auto-created PR triggers branch protection checks"
+    code: |
+      jobs:
+        create-pr:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Get GitHub App token
+              id: app-token
+              uses: actions/create-github-app-token@v1
+              with:
+                app-id: ${{ secrets.APP_ID }}
+                private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+            - uses: actions/checkout@v4
+              with:
+                token: ${{ steps.app-token.outputs.token }}
+
+            - name: Create PR — App token causes PR checks to be triggered
+              uses: peter-evans/create-pull-request@v6
+              with:
+                token: ${{ steps.app-token.outputs.token }}
+                title: 'chore: automated update'
+prevention:
+  - "Use a PAT or GitHub App token when downstream workflow runs must be triggered by a commit or PR"
+  - "Add [skip ci] to auto-commit messages when downstream CI triggering is explicitly NOT needed"
+  - "Document in workflow comments why PAT or App token is used instead of GITHUB_TOKEN"
+  - "When debugging missing CI runs after automated commits, check whether GITHUB_TOKEN loopback prevention applies"
+docs:
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow"
+    label: "GitHub Docs: Automatic token authentication — events triggered by GITHUB_TOKEN"
+  - url: "https://github.com/orgs/community/discussions/27072"
+    label: "GitHub Community: Push with GITHUB_TOKEN does not trigger new workflow runs"
+  - url: "https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow"
+    label: "GitHub Docs: Using a GitHub App token in Actions workflows"

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.45",
+  "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",