@htekdev/actions-debugger 1.0.56 → 1.0.57

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

@@ -0,0 +1,106 @@
+id: runner-environment-116
+title: "actions/setup-python with cache: pip fails when no standard requirements file exists in the repository"
+category: runner-environment
+severity: error
+tags:
+  - setup-python
+  - pip
+  - caching
+  - requirements
+  - dependency-file
+  - cache-dependency-path
+patterns:
+  - regex: 'No file found with the provided path.*requirements'
+    flags: 'i'
+  - regex: 'No dependencies file path found for pip'
+    flags: 'i'
+  - regex: 'Couldn''t find a dependency file for pip'
+    flags: 'i'
+  - regex: 'Error: No file found with the provided path'
+    flags: 'i'
+error_messages:
+  - "Error: No file found with the provided path: requirements.txt"
+  - "No dependencies file path found for pip"
+  - "Couldn't find a dependency file for pip"
+  - "Error: No file found with the provided path: **/requirements.txt"
+root_cause: |
+  When `actions/setup-python` is configured with `cache: 'pip'`, it searches the
+  repository for a standard Python dependency file to use as the cache hash key.
+  The action looks for these files by default (in order):
+
+  - `requirements.txt`
+  - `requirements/*.txt`
+  - `Pipfile.lock`
+  - `poetry.lock`
+  - `pyproject.toml` (only if it contains a `[project]` or `[tool.poetry]` section)
+  - `setup.cfg` (only if it contains `[options]` with `install_requires`)
+
+  If none of these files are present, the action fails with an error during the
+  cache configuration phase. This commonly affects repositories that:
+
+  - Use a custom requirements filename (e.g., `dev-requirements.txt`, `requirements-dev.txt`)
+  - Store requirements in a non-standard path (e.g., `ci/requirements.txt`, `tests/requirements.txt`)
+  - Use only `setup.py` for dependency declaration (not recognized by default)
+  - Generate requirements dynamically at build time
+  - Are library repos with no explicit requirements file (dependencies in `pyproject.toml`
+    but without a recognized table)
+
+  The error appears either immediately at setup time or during the post-step cache save
+  phase, depending on the setup-python version.
+fix: |
+  Provide the `cache-dependency-path` input to explicitly point to your dependency
+  file(s). This input accepts glob patterns and newline-separated paths.
+
+  If your repository has no dependency files at all (e.g., it generates them
+  dynamically), remove `cache: 'pip'` and implement pip caching manually using
+  `actions/cache@v4`, using a hash of whatever inputs determine your dependency set
+  (e.g., a Makefile, Dockerfile, or script).
+fix_code:
+  - language: yaml
+    label: "Specify non-standard requirements file path"
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+          cache-dependency-path: ci/requirements.txt   # Non-standard path
+
+  - language: yaml
+    label: "Multiple dependency files with glob pattern"
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+          cache-dependency-path: |
+            requirements.txt
+            requirements-dev.txt
+            tests/requirements.txt
+
+  - language: yaml
+    label: "Manual pip caching when no dependency file exists"
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          # Omit cache: pip — handle caching manually
+
+      - name: Cache pip packages
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: pip-${{ runner.os }}-${{ hashFiles('setup.py', 'Makefile') }}
+          restore-keys: |
+            pip-${{ runner.os }}-
+prevention:
+  - "Always set cache-dependency-path when your requirements file is not named requirements.txt or in the root directory"
+  - "Standard filenames recognized automatically: requirements.txt, Pipfile.lock, poetry.lock, pyproject.toml (with [project] table), setup.cfg (with install_requires)"
+  - "If using poetry, set cache: 'poetry' instead of cache: 'pip' — it detects poetry.lock automatically"
+  - "Consider adding a requirements.txt generated from pyproject.toml or poetry.lock to your repo for compatibility with setup-python caching"
+docs:
+  - url: "https://github.com/actions/setup-python#caching-packages-dependencies"
+    label: "actions/setup-python — Caching packages documentation"
+  - url: "https://github.com/actions/setup-python/blob/main/docs/advanced-usage.md#caching-packages"
+    label: "actions/setup-python — Advanced caching usage"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows"
+    label: "GitHub Docs — Caching dependencies to speed up workflows"

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

@@ -0,0 +1,109 @@
+id: runner-environment-117
+title: "aws-actions/configure-aws-credentials@v4 requires explicit aws-region — silent failure after version bump from v1/v2"
+category: runner-environment
+severity: error
+tags:
+  - aws
+  - configure-aws-credentials
+  - aws-region
+  - oidc
+  - version-upgrade
+  - breaking-change
+patterns:
+  - regex: 'Must provide region information'
+    flags: 'i'
+  - regex: 'Input required and not supplied:\s*aws-region'
+    flags: 'i'
+  - regex: 'Region is not set|No region provided|aws.region.*not.*set'
+    flags: 'i'
+error_messages:
+  - "Must provide region information"
+  - "Input required and not supplied: aws-region"
+  - "Region is not set"
+  - "No region provided"
+root_cause: |
+  aws-actions/configure-aws-credentials@v4 (and v2+) made aws-region a required
+  input for all authentication methods. In @v1, aws-region was optional and could
+  be derived from the AWS_DEFAULT_REGION environment variable already present on
+  the runner or set in a prior step.
+
+  When Dependabot, Renovate, or a manual version bump updates configure-aws-credentials
+  from @v1 to @v4, workflows that relied on region auto-detection or inherited
+  environment variables begin failing with "Must provide region information" or
+  "Input required and not supplied: aws-region".
+
+  Additional breaking changes between v1 and v4 that affect real workflows:
+
+  1. aws-region is now required (was optional in v1 when AWS_DEFAULT_REGION was set)
+  2. mask-aws-account-id is now always true and cannot be disabled — workflows
+     logging the account ID for debugging will see '***' in all log output
+  3. OIDC token audience: v4 defaults to 'sts.amazonaws.com'; older IAM OIDC
+     trust policies configured for a different audience must be updated
+  4. Node.js runtime: updated from Node 16 to Node 20, which may cause issues
+     on very old self-hosted runners (Node 20 requires glibc 2.17+)
+  5. role-session-name auto-generation format changed — if downstream IAM policies
+     or CloudTrail queries match on session name patterns, they may stop matching
+fix: |
+  Add an explicit aws-region input to every configure-aws-credentials step.
+
+  For OIDC-based auth, also verify your IAM trust policy's Condition block is
+  compatible with the @v4 defaults (audience: sts.amazonaws.com, subject claim
+  format: repo:OWNER/REPO:ref:refs/heads/BRANCH).
+
+  Store the region in a repository or organization variable (vars.AWS_REGION)
+  to avoid hardcoding the same region string across multiple workflow files.
+fix_code:
+  - language: yaml
+    label: "configure-aws-credentials@v4 with required aws-region (OIDC)"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write   # Required for OIDC
+            contents: read
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Configure AWS credentials
+              uses: aws-actions/configure-aws-credentials@v4
+              with:
+                aws-region: us-east-1            # Required in v4 (was optional in v1)
+                role-to-assume: ${{ vars.AWS_ROLE_ARN }}
+                role-session-name: GitHubActionsSession
+
+            - name: Deploy
+              run: aws s3 sync dist/ s3://${{ vars.S3_BUCKET }}/
+  - language: yaml
+    label: "configure-aws-credentials@v4 with static key auth"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Configure AWS credentials (static keys)
+              uses: aws-actions/configure-aws-credentials@v4
+              with:
+                aws-region: ${{ vars.AWS_REGION }}   # Use variable, not hardcoded
+                aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
+                aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+
+            - name: Deploy
+              run: aws s3 sync dist/ s3://${{ vars.S3_BUCKET }}/
+prevention:
+  - "Always specify aws-region explicitly in every configure-aws-credentials step — never rely on AWS_DEFAULT_REGION"
+  - "Store the AWS region in a repository variable (vars.AWS_REGION) to keep it consistent and easy to change"
+  - "When Dependabot bumps configure-aws-credentials to a new major version, review the release notes and test in a non-production environment first"
+  - "After bumping to v4, validate your IAM OIDC trust policy: the audience should be 'sts.amazonaws.com' and the subject claim format should match repo:OWNER/REPO:ref:refs/..."
+  - "Use actionlint locally to catch missing required inputs before committing workflow files"
+docs:
+  - url: "https://github.com/aws-actions/configure-aws-credentials"
+    label: "aws-actions/configure-aws-credentials — README and migration guide"
+  - url: "https://github.com/aws-actions/configure-aws-credentials/releases"
+    label: "aws-actions/configure-aws-credentials — Release notes (v4 breaking changes)"
+  - url: "https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html"
+    label: "AWS Docs — Creating OpenID Connect identity providers"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services"
+    label: "GitHub Docs — Configuring OIDC in Amazon Web Services"

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-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"