@htekdev/actions-debugger 1.0.55 → 1.0.57

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

@@ -0,0 +1,120 @@
+id: silent-failures-057
+title: "needs.<job>.outputs empty when upstream job failed — if: always() downstream job silently receives empty strings"
+category: silent-failures
+severity: silent-failure
+tags:
+  - needs
+  - job-outputs
+  - always
+  - failure
+  - silent-failure
+  - job-dependencies
+  - error-handling
+patterns:
+  - regex: 'needs\.\w+\.outputs\.\w+'
+    flags: 'i'
+  - regex: 'if.*always.*needs.*result.*failure'
+    flags: 'i'
+error_messages: []
+root_cause: |
+  GitHub Actions job outputs are only populated when the upstream job completes successfully
+  (exit code 0). If an upstream job fails, its outputs are never set in the workflow context
+  — even if the job partially executed and wrote to $GITHUB_OUTPUT before the failure.
+
+  When a downstream job uses `if: always()` or `if: needs.upstream.result == 'failure'`
+  to run after a failed upstream job, all `needs.<upstream>.outputs.*` values resolve to
+  empty strings. No warning is emitted in the logs. The downstream job runs without any
+  indication that it received empty output values instead of the expected data.
+
+  This silently causes:
+  - Notification steps sending messages with blank context (empty SHA, branch, artifact path)
+  - Conditional steps skipping because a non-empty string check evaluates to false
+  - Upload or deploy steps using empty or incorrectly-derived paths
+  - Downstream matrix jobs running with no dimension values
+
+  The pattern is valid YAML — `needs.upstream.outputs.my_value` passes schema validation.
+  The failure only manifests at runtime after the upstream job has failed, and the symptoms
+  look unrelated to the empty output (e.g., "artifact not found" rather than "output was empty").
+fix: |
+  Option 1 (recommended): Set outputs as early as possible in the upstream job, before any
+  step that might fail. Use a dedicated first step to write context values to $GITHUB_OUTPUT
+  before running builds or tests that could fail.
+
+  Option 2: Add `|| 'fallback'` expressions to all `needs.*.outputs.*` references in
+  if:always() downstream jobs to make empty values visible:
+    env:
+      ARTIFACT_PATH: ${{ needs.build.outputs.artifact_path || 'unknown' }}
+
+  Option 3: In notification/cleanup jobs, use `github.*` context values directly rather
+  than relying on upstream job outputs for data that is always available:
+    github.sha, github.ref_name, github.actor, github.run_id
+
+  Option 4: Use a `result` check before accessing outputs and provide explicit fallbacks
+  when result is not 'success':
+    ${{ needs.build.result == 'success' && needs.build.outputs.artifact || 'build-failed' }}
+fix_code:
+  - language: yaml
+    label: "Set outputs in a first step before any step that might fail"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            artifact_path: ${{ steps.init.outputs.artifact_path }}
+            commit_sha: ${{ steps.init.outputs.commit_sha }}
+          steps:
+            # Set outputs FIRST before any step that might fail
+            - name: Initialize outputs
+              id: init
+              run: |
+                echo "artifact_path=dist/" >> $GITHUB_OUTPUT
+                echo "commit_sha=${{ github.sha }}" >> $GITHUB_OUTPUT
+
+            - uses: actions/checkout@v4
+
+            - name: Build (may fail)
+              run: npm run build
+
+        notify:
+          needs: build
+          if: always()
+          runs-on: ubuntu-latest
+          steps:
+            - name: Send build notification
+              run: |
+                RESULT="${{ needs.build.result }}"
+                # Use || fallback since outputs are empty when build failed
+                ARTIFACT="${{ needs.build.outputs.artifact_path || 'N/A' }}"
+                SHA="${{ needs.build.outputs.commit_sha || github.sha }}"
+                echo "Build: $RESULT | Artifact: $ARTIFACT | SHA: $SHA"
+  - language: yaml
+    label: "Use github context directly in failure-handling jobs instead of upstream outputs"
+    code: |
+      jobs:
+        notify-on-failure:
+          needs: [build, test]
+          if: failure()
+          runs-on: ubuntu-latest
+          steps:
+            - name: Notify failure
+              run: |
+                # Use github context — always available regardless of upstream failure
+                echo "Repository: ${{ github.repository }}"
+                echo "Branch: ${{ github.ref_name }}"
+                echo "Commit: ${{ github.sha }}"
+                echo "Actor: ${{ github.actor }}"
+                echo "Run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+prevention:
+  - "Write all critical values to GITHUB_OUTPUT in the very first step of a job, before any step that might fail"
+  - "Add || 'fallback' to every needs.*.outputs.* expression in if:always() or if:failure() downstream jobs"
+  - "Use github.* context values for data always available (sha, ref_name, actor, run_id) rather than upstream outputs"
+  - "Test failure paths by adding a workflow_dispatch that intentionally fails the upstream job and verify downstream output"
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idoutputs"
+    label: "GitHub Docs — Job outputs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#needs-context"
+    label: "GitHub Docs — needs context"
+  - url: "https://github.com/orgs/community/discussions/18163"
+    label: "GitHub Community — needs outputs empty when job failed"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idif"
+    label: "GitHub Docs — if conditions with always()"

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

@@ -0,0 +1,126 @@
+id: silent-failures-058
+title: "workflow_dispatch type:choice inputs bypass validation via REST API — arbitrary strings accepted silently"
+category: silent-failures
+severity: silent-failure
+tags:
+  - workflow_dispatch
+  - inputs
+  - choice
+  - rest-api
+  - validation
+  - type-checking
+patterns:
+  - regex: 'type:\s*choice'
+    flags: 'i'
+  - regex: 'workflow.*dispatch.*inputs.*choice'
+    flags: 'i'
+error_messages:
+  - "type: choice"
+root_cause: |
+  The workflow_dispatch event supports an input type of 'choice' which presents
+  a dropdown menu in the GitHub UI, restricting the user to a predefined list of
+  valid values. However, this validation is enforced only in the GitHub web UI —
+  it is NOT enforced by the GitHub Actions API.
+
+  When a workflow is triggered via the REST API (POST /repos/{owner}/{repo}/actions/
+  workflows/{workflow_id}/dispatches), any string value can be supplied for a
+  choice-type input, including values not in the defined options list. The workflow
+  accepts and runs with the unsanitized value without error or warning.
+
+  This means:
+  - CI/CD scripts calling workflow_dispatch via REST API can accidentally pass
+    the wrong environment name (typos, case differences, wrong string)
+  - Automation systems that construct the dispatch payload dynamically may pass
+    a value that was valid at construction time but is no longer a valid choice
+  - Malicious actors with repository write access can trigger unexpected code paths
+    by dispatching with unexpected values
+
+  Steps using 'if: inputs.environment == "production"' may silently skip or
+  silently run depending on whether the API-supplied string matches exactly.
+  No error is raised — the workflow just behaves unexpectedly.
+
+  Example: inputs.environment options are ['dev', 'staging', 'production'] but
+  API call passes 'prod' — all condition checks against 'production' silently
+  fail, causing the deployment step to be skipped with no indication of why.
+fix: |
+  Explicitly validate choice-type inputs at the start of the workflow using a
+  validation step that fails fast with a clear error message when an invalid
+  value is supplied.
+
+  For critical path decisions (environment selection, deployment targets), use
+  a validation step before any consequential operations:
+
+    - name: Validate environment input
+      run: |
+        case "${{ inputs.environment }}" in
+          dev|staging|production) ;;
+          *) echo "Invalid environment: ${{ inputs.environment }}" && exit 1 ;;
+        esac
+
+  This approach works regardless of how the workflow was triggered (UI or API)
+  and produces a clear failure message instead of a silent wrong-path execution.
+fix_code:
+  - language: yaml
+    label: "Validate choice input before using it — fails fast with clear error"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              description: 'Target environment'
+              type: choice
+              required: true
+              options:
+                - dev
+                - staging
+                - production
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Validate environment input
+              run: |
+                valid_envs="dev staging production"
+                if ! echo "$valid_envs" | grep -qw "${{ inputs.environment }}"; then
+                  echo "ERROR: Invalid environment '${{ inputs.environment }}'"
+                  echo "Valid options: $valid_envs"
+                  exit 1
+                fi
+
+            - name: Deploy to ${{ inputs.environment }}
+              run: echo "Deploying to ${{ inputs.environment }}"
+  - language: yaml
+    label: "Use environment-scoped deployment for automatic protection"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              description: 'Target environment'
+              type: choice
+              required: true
+              options:
+                - dev
+                - staging
+                - production
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          environment: ${{ inputs.environment }}  # Invalid names cause job failure
+          steps:
+            - name: Deploy
+              run: echo "Deploying to ${{ inputs.environment }}"
+prevention:
+  - "Never rely solely on type:choice validation — always add an explicit validation step for inputs that affect deployment targets or security-sensitive code paths"
+  - "Use environment: ${{ inputs.environment }} on jobs to leverage GitHub's environment protection rules as a secondary validation layer"
+  - "Document that API dispatch bypasses choice validation in your workflow's comments so future maintainers know validation is needed"
+  - "In automation scripts that call workflow_dispatch via API, validate the environment string against the allowed list before making the API call"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch"
+    label: "GitHub Docs — workflow_dispatch inputs"
+  - url: "https://docs.github.com/en/rest/actions/workflows#create-a-workflow-dispatch-event"
+    label: "GitHub REST API — Create a workflow dispatch event"
+  - url: "https://stackoverflow.com/questions/69578241/github-actions-workflow-dispatch-with-choices"
+    label: "Stack Overflow — workflow_dispatch with choice inputs (highly voted)"

package/errors/triggers/triggers-040.yml

@@ -0,0 +1,104 @@
+id: triggers-040
+title: "Missing 'on: merge_group' trigger — required status checks fail in merge queue"
+category: triggers
+severity: error
+tags:
+  - merge-queue
+  - merge_group
+  - required-status-checks
+  - branch-protection
+  - ci-failure
+  - triggers
+patterns:
+  - regex: 'merge_group'
+    flags: i
+  - regex: 'Required status checks were not passing.*merge.queue'
+    flags: i
+error_messages:
+  - "Required status check 'ci/test' was not reported — PR ejected from merge queue"
+  - "This branch requires linear history. The merge queue could not merge this pull request."
+root_cause: |
+  GitHub's merge queue (available since May 2023 GA) uses a dedicated event called
+  merge_group to trigger workflows. This is distinct from the pull_request event.
+
+  When a pull request enters the merge queue, GitHub creates a temporary merge branch
+  and fires the merge_group event. Workflows that only declare on: pull_request (or
+  other events) do not trigger on merge_group and therefore never create any status
+  check runs for the queued PR.
+
+  Branch protection rules that require specific status checks see no check result for
+  the merge group run and treat the absence as failure, ejecting the PR from the queue
+  with a message that the required checks were not passing.
+
+  The merge queue was added to GitHub Actions in May 2023 (GitHub Changelog). Existing
+  workflows created before that date have no merge_group trigger and must be updated
+  manually. Projects that enable merge queue on an existing repo will silently find
+  that all PRs are blocked from being merged via the queue.
+fix: |
+  Add merge_group: to the on: trigger block alongside pull_request (and push, if used).
+  The merge_group event accepts no filter options — it fires whenever any PR enters
+  the merge queue for a protected branch.
+
+  If your workflow uses branch filters under on.pull_request.branches, those filters
+  do NOT apply to merge_group — the event always fires regardless of branch name.
+  This is intentional: the merge queue uses temporary synthetic branches.
+fix_code:
+  - language: yaml
+    label: "Problem: workflow only triggers on pull_request, not in merge queue"
+    code: |
+      # BEFORE: only runs on pull_request — never fires in merge queue
+      on:
+        pull_request:
+          branches: [main]
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+  - language: yaml
+    label: "Fix: add merge_group trigger so CI runs in the merge queue"
+    code: |
+      # AFTER: runs on both pull_request and when entering the merge queue
+      on:
+        pull_request:
+          branches: [main]
+        merge_group:        # Required for merge queue — no filter options available
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+  - language: yaml
+    label: "With push trigger (common three-trigger pattern)"
+    code: |
+      on:
+        push:
+          branches: [main]
+        pull_request:
+          branches: [main]
+        merge_group:        # Always needed if merge queue is enabled on the repo
+
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm ci
+            - run: npm test
+            - run: npm run lint
+prevention:
+  - "Any time you enable merge queue on a branch, audit all required-check workflows and add 'merge_group:' to each"
+  - "The merge_group event accepts no filter keys — do not try to add 'branches:' or 'types:' under it"
+  - "Test merge queue behavior by adding a PR to the queue and checking the Actions tab for the merge group run"
+  - "Add a comment near the merge_group trigger explaining its purpose for teammates unfamiliar with merge queues"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#merge_group"
+    label: "GitHub Docs: merge_group event"
+  - url: "https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue"
+    label: "GitHub Docs: Managing a merge queue"
+  - url: "https://github.blog/changelog/2023-05-12-github-actions-merge-queue-is-generally-available/"
+    label: "GitHub Changelog: Merge queue GA (May 2023)"

package/errors/triggers/triggers-041.yml

@@ -0,0 +1,105 @@
+id: triggers-041
+title: "on.schedule workflow only runs from default branch — schedule changes in feature branches never fire"
+category: triggers
+severity: limitation
+tags:
+  - schedule
+  - cron
+  - default-branch
+  - triggers
+  - known-limitation
+  - testing
+patterns:
+  - regex: 'schedule.*not.*trigger'
+    flags: 'i'
+  - regex: 'cron.*not.*running.*branch'
+    flags: 'i'
+  - regex: 'workflow.*not.*present.*default.*branch'
+    flags: 'i'
+error_messages:
+  - "This workflow has a workflow_dispatch event trigger, however a workflow_dispatch event workflow run cannot be created as this workflow is not present in the default branch."
+root_cause: |
+  GitHub Actions `on.schedule` workflows only execute from the repository's default branch
+  (typically `main` or `master`). No matter what branch the workflow file is pushed to, the
+  schedule trigger always runs the version of the workflow file on the default branch.
+
+  This creates a silent testing trap: developers modify a cron-based workflow in a feature
+  branch, push it, and wait for the scheduled time. The schedule fires correctly — but runs
+  the OLD workflow definition from the default branch, not the feature branch changes. The
+  developer sees no behavior change and cannot validate their modifications until after merging.
+
+  There is no GitHub UI indication that a scheduled workflow is "pending for a branch". All
+  scheduled runs appear under the default branch in the Actions tab regardless of which branch
+  triggered or modified them.
+
+  This limitation applies exclusively to `on.schedule`. Other triggers (`on.push`,
+  `on.pull_request`, `on.workflow_dispatch`) work correctly from any branch that contains
+  the workflow file.
+fix: |
+  There is no way to run `on.schedule` from a feature branch. Use these testing alternatives:
+
+  Option 1 (recommended): Add `on.workflow_dispatch` to the same workflow alongside
+  `on.schedule`. Use the GitHub UI or CLI to manually trigger runs from your feature branch
+  to validate changes before merging.
+
+  Option 2: Add `on.push` with a specific branch filter during development. Push triggers
+  fire from any branch and will use the feature branch's workflow definition.
+
+  Option 3: Use `act` (nektos/act) locally to simulate scheduled runs before pushing.
+
+  Option 4: Merge to a short-lived integration/staging branch that serves as a temporary
+  "default" for validation, then merge to main.
+
+  After validation, merge to the default branch — the schedule will automatically use the
+  updated workflow definition from that point forward.
+fix_code:
+  - language: yaml
+    label: "Add workflow_dispatch alongside schedule to enable branch-based testing"
+    code: |
+      on:
+        # Production: runs on schedule from default branch only
+        schedule:
+          - cron: '0 6 * * 1'   # Every Monday at 6 AM UTC
+
+        # Development: add this to test changes from any branch manually
+        workflow_dispatch:
+
+      jobs:
+        scheduled-job:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run scheduled task
+              run: ./scripts/weekly-task.sh
+  - language: yaml
+    label: "Add on.push temporarily during development to fire from feature branch"
+    code: |
+      on:
+        schedule:
+          - cron: '0 6 * * 1'
+
+        # TEMPORARY: Remove before merging — used to test schedule logic from branch
+        push:
+          branches: ['feature/update-schedule-workflow']
+
+      jobs:
+        scheduled-job:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run scheduled task
+              run: ./scripts/weekly-task.sh
+prevention:
+  - "Always add workflow_dispatch to workflows that primarily use on.schedule — it enables branch-level testing at any time"
+  - "Use act (nektos/act) locally to simulate scheduled workflow runs during development"
+  - "Add a comment in the workflow file noting that schedule: only fires from the default branch"
+  - "Treat schedule-only workflows as default-branch-only code — validate in staging branches before merging"
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule"
+    label: "GitHub Docs — schedule event"
+  - url: "https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch"
+    label: "GitHub Docs — workflow_dispatch event (for manual testing)"
+  - url: "https://github.com/nektos/act"
+    label: "nektos/act — Run Actions locally"
+  - url: "https://github.com/orgs/community/discussions/21536"
+    label: "GitHub Community — Scheduled workflow only runs on default branch"

package/errors/triggers/triggers-042.yml

@@ -0,0 +1,110 @@
+id: triggers-042
+title: "workflow_run trigger only activates when the listener workflow file exists on the default branch"
+category: triggers
+severity: silent-failure
+tags:
+  - workflow_run
+  - default-branch
+  - trigger
+  - silent-failure
+  - feature-branch
+  - testing
+patterns:
+  - regex: 'on:\s*[\r\n]+\s*workflow_run'
+    flags: 'is'
+  - regex: 'workflow_run.*workflows.*completed'
+    flags: 'is'
+error_messages: []
+root_cause: |
+  GitHub only reads the `on: workflow_run:` trigger definition from workflow files
+  that exist on the **default branch** of the repository. If a workflow file
+  containing `on: workflow_run:` exists only on a feature branch, pull request branch,
+  or any non-default branch, the trigger is silently ignored — no error is reported,
+  the workflow file is valid, and GitHub simply never fires the workflow.
+
+  This means that changes to a `workflow_run` listener workflow cannot be exercised
+  on a branch before merging to the default branch. A brand-new `workflow_run` listener
+  added on a feature branch will not activate even when the triggering workflow
+  (listed under `workflows:`) completes successfully.
+
+  This behavior is consistent with other event-driven triggers that GitHub reads only
+  from the default branch:
+  - `on: schedule` — cron schedule (documented, see entry triggers-041)
+  - `on: workflow_dispatch` — manual trigger (known-unsolved entry covers UI visibility)
+  - `on: workflow_run` — this entry
+
+  The distinction matters most for `workflow_run` because developers often add a
+  `workflow_run` listener to automate post-CI steps (deploy, notifications, releases)
+  and naturally develop and test the listener on a branch before merging it.
+
+  Note: The `branches:` filter inside `on: workflow_run:` controls WHICH branches the
+  triggering workflow must run on — this is separate from where the listener workflow
+  itself must reside (always the default branch).
+fix: |
+  Merge the workflow file containing `on: workflow_run:` to the default branch before
+  expecting it to activate. To test the workflow logic before merging:
+
+  1. Add a temporary `on: workflow_dispatch:` trigger alongside `on: workflow_run:`.
+     This allows manual test runs on any branch after the file lands on the default branch.
+  2. Use `act` locally to simulate `workflow_run` events before pushing.
+  3. Test using a throw-away default branch in a fork during development.
+
+  Once the file is on the default branch, the `workflow_run` trigger activates
+  immediately for all future triggering workflow completions.
+fix_code:
+  - language: yaml
+    label: "Add workflow_dispatch alongside workflow_run for pre-merge testing"
+    code: |
+      name: Post-CI Deploy
+
+      on:
+        # Temporary: enables manual test runs after this file merges to default branch
+        workflow_dispatch:
+
+        # Primary trigger: only active after this file is on the default branch
+        workflow_run:
+          workflows: ["CI"]       # Must match the exact workflow name: field value
+          types: [completed]
+          branches: [main]        # Only triggers when CI ran on these branches
+
+      jobs:
+        deploy:
+          # Only deploy when CI actually passed
+          if: ${{ github.event.workflow_run.conclusion == 'success' || github.event_name == 'workflow_dispatch' }}
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "Deploying..."
+
+  - language: yaml
+    label: "Minimal workflow_run listener (file must be on default branch)"
+    code: |
+      name: Notify on CI Complete
+
+      on:
+        workflow_run:
+          workflows: ["Build and Test"]   # Exact name from the other workflow's 'name:' field
+          types: [completed]
+
+      jobs:
+        notify:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Report conclusion
+              run: |
+                echo "Triggered by: ${{ github.event.workflow_run.name }}"
+                echo "Conclusion:   ${{ github.event.workflow_run.conclusion }}"
+                echo "Head branch:  ${{ github.event.workflow_run.head_branch }}"
+prevention:
+  - "Merge workflow files with on: workflow_run: to the default branch before expecting them to fire — there is no way to test this trigger on a feature branch"
+  - "Add on: workflow_dispatch: temporarily for manual testing after the file lands on the default branch"
+  - "Use act (https://github.com/nektos/act) locally to simulate workflow_run events during development"
+  - "Document in team runbooks that workflow_run, schedule, and workflow_dispatch triggers require the workflow file on the default branch"
+  - "Verify the workflows: list uses the exact value of the triggering workflow's name: field — a mismatch causes the same silent non-firing behavior"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run"
+    label: "GitHub Docs — workflow_run trigger"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#triggering-a-workflow-from-a-workflow"
+    label: "GitHub Docs — Triggering a workflow from a workflow"
+  - url: "https://github.com/nektos/act"
+    label: "act — Run GitHub Actions locally for testing"