@htekdev/actions-debugger 1.0.22 → 1.0.24

package/errors/silent-failures/windows-powershell-github-output-bash-syntax.yml

@@ -0,0 +1,118 @@
+id: silent-failures-034
+title: "Windows PowerShell GITHUB_OUTPUT and GITHUB_ENV Require $env: Prefix, Not Bash-Style $VARIABLE Syntax"
+category: silent-failures
+severity: silent-failure
+tags:
+  - windows
+  - powershell
+  - GITHUB_OUTPUT
+  - GITHUB_ENV
+  - environment-variables
+  - shell-syntax
+patterns:
+  - regex: "echo\\s+[\"']?[A-Z_]+=.*>>\\s+\\$GITHUB_OUTPUT"
+    flags: "i"
+  - regex: "echo\\s+[\"']?[A-Z_]+=.*>>\\s+\\$GITHUB_ENV"
+    flags: "i"
+  - regex: "shell:\\s*(pwsh|powershell)"
+    flags: "i"
+error_messages:
+  - "echo \"KEY=value\" >> $GITHUB_OUTPUT"
+  - "echo \"KEY=value\" >> $GITHUB_ENV"
+  - "Val1: "
+  - "Val2: "
+root_cause: |
+  When a workflow step uses shell: pwsh (PowerShell Core, the default on Windows
+  runners) or shell: powershell (legacy Windows PowerShell), the bash-style
+  variable syntax $GITHUB_OUTPUT and $GITHUB_ENV does NOT work.
+
+  In PowerShell, $GITHUB_OUTPUT is treated as a PowerShell variable (undefined
+  and therefore null). The >> append operator writes nothing to a null path.
+  The step exits 0 (success) with no error or warning. All downstream jobs
+  that reference step outputs or environment variables receive empty strings.
+
+  The correct PowerShell syntax uses $env:GITHUB_OUTPUT to access the OS
+  environment variable, not $GITHUB_OUTPUT (a PS variable).
+
+  Shell-specific syntax comparison:
+  - bash / sh:     echo "KEY=val" >> $GITHUB_OUTPUT
+  - pwsh (PS 7+):  "KEY=val" >> $env:GITHUB_OUTPUT
+  - powershell:    "KEY=val" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+  - cmd:           echo KEY=val >> %GITHUB_OUTPUT%
+
+  This is a common mistake when:
+  - Migrating workflows from Linux to Windows runners
+  - Copying bash examples from documentation into PowerShell steps
+  - Writing cross-platform workflows without specifying shell: per step
+fix: |
+  Replace $GITHUB_OUTPUT with $env:GITHUB_OUTPUT and $GITHUB_ENV with
+  $env:GITHUB_ENV in all PowerShell steps.
+
+  Alternatively, add shell: bash to every run: step that uses bash-style
+  syntax — Git Bash is available on all Windows GitHub-hosted runners and
+  supports the standard $GITHUB_OUTPUT syntax.
+
+  For old Windows PowerShell (shell: powershell), use Out-File with
+  explicit UTF-8 encoding to avoid BOM issues.
+fix_code:
+  - language: yaml
+    label: "Broken — bash syntax in PowerShell step silently produces no output"
+    code: |
+      - name: Set output (broken on PowerShell)
+        shell: pwsh
+        run: |
+          # WRONG: $GITHUB_OUTPUT is a null PS variable — no output is set
+          echo "BUILD_VERSION=1.2.3" >> $GITHUB_OUTPUT
+
+  - language: yaml
+    label: "Fixed — correct $env: prefix for PowerShell Core (pwsh)"
+    code: |
+      - name: Set output (PowerShell Core)
+        id: version
+        shell: pwsh
+        run: |
+          # CORRECT: $env:GITHUB_OUTPUT accesses the OS environment variable
+          "BUILD_VERSION=1.2.3" >> $env:GITHUB_OUTPUT
+
+      - name: Use output
+        run: echo "Version is ${{ steps.version.outputs.BUILD_VERSION }}"
+        shell: pwsh
+
+  - language: yaml
+    label: "Old Windows PowerShell (shell: powershell) — explicit UTF-8 required"
+    code: |
+      - name: Set output (legacy Windows PowerShell)
+        shell: powershell
+        run: |
+          "BUILD_VERSION=1.2.3" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+
+  - language: yaml
+    label: "Cross-platform — use shell: bash to keep bash-style syntax on Windows"
+    code: |
+      - name: Set output (bash on Windows runner)
+        shell: bash
+        run: |
+          # shell: bash uses Git Bash on Windows — $GITHUB_OUTPUT works fine
+          echo "BUILD_VERSION=1.2.3" >> $GITHUB_OUTPUT
+
+  - language: yaml
+    label: "CMD shell syntax"
+    code: |
+      - name: Set output (CMD)
+        shell: cmd
+        run: echo BUILD_VERSION=1.2.3 >> %GITHUB_OUTPUT%
+prevention:
+  - "Use shell: bash for all run: steps that use bash-style $GITHUB_OUTPUT or $GITHUB_ENV syntax, even on Windows runners."
+  - "In team workflow templates, document the shell-specific syntax for GITHUB_OUTPUT and GITHUB_ENV."
+  - "Add actionlint to CI — it can detect shell/syntax mismatches in workflow files."
+  - "Add an explicit post-step validation that reads back expected outputs to confirm they were written correctly."
+  - "Prefer shell: bash globally (via defaults: run: shell: bash) when your workflows target cross-platform and use bash syntax."
+docs:
+  - url: "https://stackoverflow.com/questions/74443940/value-not-set-using-github-output"
+    label: "Stack Overflow: Value not set using $GITHUB_OUTPUT on Windows PowerShell (Score: 22, 17K views)"
+  - url: "https://stackoverflow.com/questions/66733076/github-actions-set-environment-variable-for-windows-build-with-powershell"
+    label: "Stack Overflow: Set environment variable for Windows build with PowerShell (Score: 16, 11K views)"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-output-parameter"
+    label: "GitHub Docs: Setting an output parameter (includes PowerShell examples)"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#defaultsrun"
+    label: "GitHub Docs: defaults.run.shell — set default shell for all run steps"

package/errors/triggers/fork-pr-first-time-contributor-approval-required.yml

@@ -0,0 +1,142 @@
+id: triggers-022
+title: "Fork PR Workflows Paused — First-Time Contributor Requires Approval"
+category: triggers
+severity: warning
+tags:
+  - fork
+  - pull_request
+  - first-time-contributor
+  - approval
+  - secrets
+  - outside-collaborator
+patterns:
+  - regex: "This run (?:was triggered by a (?:first-time contributor|new GitHub user)|requires approval)"
+    flags: "i"
+  - regex: "Workflow run requires approval"
+    flags: "i"
+  - regex: "requires approval from a maintainer"
+    flags: "i"
+  - regex: "waiting for approval"
+    flags: "i"
+error_messages:
+  - "This run was triggered by a first-time contributor and requires approval from a maintainer with write access."
+  - "Workflow run requires approval"
+  - "This run requires approval from a maintainer with write access."
+root_cause: |
+  GitHub requires manual approval before running workflows triggered by pull
+  requests from forked repositories when the contributor meets certain criteria.
+  This is a security measure to prevent untrusted code from accessing repository
+  secrets or running CI at the organization's expense.
+
+  GitHub's fork PR approval policy (configurable per repo, org, or enterprise)
+  determines when approval is required. The default for public repos is:
+  "Require approval for first-time contributors who are new to GitHub" — meaning
+  contributors who have never contributed to any public GitHub repo need approval
+  on their first PR. For private repos, the default is to require approval from
+  all outside collaborators.
+
+  When approval is required, the workflow run is shown in the Actions tab with
+  a yellow banner reading "This run was triggered by a first-time contributor
+  and requires approval from a maintainer with write access." The workflow does
+  not start until a maintainer with write access clicks "Approve and run."
+
+  Workflows awaiting approval for more than 30 days are automatically deleted.
+  Importantly, if no maintainer approves the run, CI results will never appear
+  on the pull request — blocking any required status checks from passing and
+  preventing the PR from being merged.
+
+  Three root causes are commonly conflated:
+  1. First-time contributor to GitHub (no prior public repo contributions).
+  2. First-time contributor to this specific repository (even if experienced on GitHub).
+  3. Outside collaborator (not a member of the org that owns the repo).
+
+  The approval gate is per-workflow-run, not per-PR. If a contributor pushes
+  additional commits to an already-approved PR, each new push triggers a new
+  run that must be re-approved.
+fix: |
+  Option 1 — Approve manually (per-run action):
+    Go to the repository's Actions tab → find the pending workflow run with the
+    yellow approval banner → click "Approve and run". Repeat for each new commit
+    push by the same contributor.
+
+  Option 2 — Change the approval policy (repo setting):
+    Go to Settings → Actions → General → Fork pull request workflows.
+    Change from "Require approval for first-time contributors who are new to GitHub"
+    to "Require approval for first-time contributors" (blocks all new contributors
+    to THIS repo, not all of GitHub) or "Not required" (disables the gate entirely).
+    Note: "Not required" means secrets are accessible to fork PR workflows —
+    only use this for private repos or repos with no sensitive secrets.
+
+  Option 3 — Use pull_request_target for secret-free PR workflows:
+    If you only need access to repository secrets in a separate, controlled job,
+    use pull_request_target instead of pull_request. The pull_request_target
+    event runs in the context of the base repo and has access to secrets, but
+    you should NEVER check out the PR's code and run it — only read PR metadata.
+
+  Option 4 — Approve all runs for a contributor via REST API:
+    POST /repos/{owner}/{repo}/actions/runs/{run_id}/approve
+    Use this to batch-approve pending runs from a trusted contributor programmatically.
+fix_code:
+  - language: yaml
+    label: "Change approval policy — require approval for first-time contributors to THIS repo only"
+    code: |
+      # In GitHub UI: Settings → Actions → General → Fork pull request workflows
+      # Select: "Require approval for first-time contributors"
+      # This is the balanced option — trusts repeat contributors, gates new ones.
+
+      # For automation workflows that need to run on all fork PRs without approval,
+      # use pull_request_target (read-only PR metadata only — NEVER run PR code):
+      on:
+        pull_request_target:
+          types: [opened, synchronize]
+
+      jobs:
+        label:
+          runs-on: ubuntu-latest
+          permissions:
+            pull-requests: write
+          steps:
+            - name: Label first-time contributor
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  const pr = context.payload.pull_request;
+                  if (pr.author_association === 'FIRST_TIME_CONTRIBUTOR') {
+                    await github.rest.issues.addLabels({
+                      owner: context.repo.owner,
+                      repo: context.repo.repo,
+                      issue_number: pr.number,
+                      labels: ['first-time-contributor']
+                    });
+                  }
+  - language: yaml
+    label: "Separate workflow — gate secrets behind explicit approval check"
+    code: |
+      # Use pull_request for the CI job (no secrets, runs on fork code safely)
+      # Use pull_request_target with environment protection for secret-requiring jobs
+      on:
+        pull_request:
+          branches: [main]
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+            # No secrets needed — runs without approval gate
+prevention:
+  - "Document in CONTRIBUTING.md that first-time contributors' CI runs require maintainer approval before they start — set expectations early."
+  - "Set the approval policy to 'Require approval for first-time contributors' (not 'new to GitHub') to minimize repeated approvals for experienced contributors who are new to your repo."
+  - "Use separate workflow files for CI (no secrets, runs on pull_request) and deployment/release (needs secrets, runs on merge to main) — this reduces how often the approval gate is hit."
+  - "For open-source projects with many external PRs, consider a bot that auto-approves workflow runs from contributors who have already passed a one-time review (e.g., using the approve-run REST API after manually approving the first PR)."
+  - "Never use pull_request_target to run code from the fork — only use it for read-only operations on PR metadata. Mixing it with code execution from the fork is a security vulnerability."
+docs:
+  - url: "https://docs.github.com/en/actions/how-tos/manage-workflow-runs/approve-runs-from-forks"
+    label: "GitHub Docs: Approving workflow runs from forks"
+  - url: "https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#configuring-required-approval-for-workflows-from-public-forks"
+    label: "GitHub Docs: Configuring required approval for workflows from public forks"
+  - url: "https://github.blog/changelog/2022-11-14-github-actions-require-approval-for-running-workflows-from-private-forks/"
+    label: "GitHub Changelog: Require approval for workflows from private forks (Nov 2022)"
+  - url: "https://github.com/orgs/community/discussions/14334"
+    label: "GitHub Community Discussion #14334: Fork PR approval pain points"

package/errors/triggers/on-push-branches-glob-star-no-slash-match.yml

@@ -0,0 +1,78 @@
+id: "triggers-023"
+title: "Single-star branch filter does not match branch names containing slashes"
+category: "triggers"
+severity: "silent-failure"
+tags:
+  - "branches-filter"
+  - "glob"
+  - "on-push"
+  - "slash"
+  - "feature-branch"
+  - "workflow-not-triggering"
+patterns:
+  - regex: "branches:\\s*\\n\\s+-\\s+'\\*'\\s*$"
+    flags: "im"
+  - regex: "branches:\\s*\\[\\s*['\"]\\*['\"]\\s*\\]"
+    flags: "i"
+error_messages:
+  - "Workflow does not trigger on feature/my-branch despite branches: ['*']"
+root_cause: |
+  GitHub Actions uses Unix glob patterns for branch and tag filters. The single `*`
+  wildcard matches any character EXCEPT the forward slash `/`. This means:
+
+    branches: ['*']         matches: main, develop, hotfix-123
+    branches: ['*']  does NOT match: feature/my-feature, release/v1.2.0
+
+  To match any branch name including those with slashes, you must use `**` (double
+  star), which matches any character including `/`.
+
+  No error is thrown when the filter excludes a branch — the workflow simply does not
+  appear in the Actions tab for pushes to `feature/*`-style branches. Developers who
+  expect `*` to mean "all branches" (as in many other CI systems) are silently surprised
+  when feature branch pushes produce no workflow runs.
+
+  This follows the same glob semantics documented in GitHub's filter pattern cheat sheet
+  but is one of the most common "workflow not triggering" reports in GitHub Community.
+fix: |
+  Replace single `*` with `**` in your branches filter to match all branch names
+  including those containing slashes. For selective matching, use prefix patterns
+  like 'feature/**' or 'release/**'.
+fix_code:
+  - language: yaml
+    label: "Before: single star silently excludes feature/* branches"
+    code: |
+      on:
+        push:
+          branches:
+            - '*'    # ❌ does NOT match feature/my-feature or release/v1.0.0
+
+  - language: yaml
+    label: "After: double star matches all branches including those with slashes"
+    code: |
+      on:
+        push:
+          branches:
+            - '**'   # ✅ matches any branch name including feature/my-feature
+
+  - language: yaml
+    label: "Practical example: main plus all feature and release branches"
+    code: |
+      on:
+        push:
+          branches:
+            - main
+            - 'feature/**'    # ✅ feature/foo, feature/bar/baz, etc.
+            - 'release/**'    # ✅ release/v1.0, release/v1.0.1, etc.
+            - 'hotfix/**'     # ✅ hotfix/critical-fix, etc.
+prevention:
+  - "Use '**' when you mean 'any branch' and reserve '*' for single-segment names only."
+  - "Test your branch filter by pushing to a feature/test branch in a non-production context and verifying a workflow run appears."
+  - "Consult the GitHub filter pattern cheat sheet before using glob characters in branches, tags, or paths filters."
+  - "Use 'branches-ignore' with an empty list and 'branches: [**]' to explicitly document intent to run on all branches."
+docs:
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet"
+    label: "GitHub Docs — Filter pattern cheat sheet"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushbranchesbranchesignore"
+    label: "GitHub Docs — on.push.branches filter"
+  - url: "https://github.com/orgs/community/discussions/147369"
+    label: "GitHub Community #147369 — Workflow not triggering on expected branches"

package/errors/triggers/pull-request-target-env-protection-default-branch-eval.yml

@@ -0,0 +1,117 @@
+id: triggers-021
+title: "pull_request_target Environment Branch Protection Now Evaluates Against Default Branch (Nov 2025 Breaking Change)"
+category: triggers
+severity: error
+tags:
+  - pull_request_target
+  - environment
+  - branch-protection
+  - deployment
+  - breaking-change
+  - default-branch
+  - evaluation-ref
+patterns:
+  - regex: "Branch 'refs/pull/\\d+/merge' is not allowed to deploy to .+ due to environment protection rules"
+    flags: "i"
+  - regex: "pull_request_target.*environment.*protection"
+    flags: "im"
+  - regex: "is not allowed to deploy to .+ due to environment protection rules"
+    flags: "i"
+error_messages:
+  - "Branch 'refs/pull/904/merge' is not allowed to deploy to prod due to environment protection rules."
+  - "Branch 'refs/pull/123/merge' is not allowed to deploy to staging due to environment protection rules."
+root_cause: |
+  In November 2025, GitHub changed how environment branch protection rules are evaluated
+  for `pull_request_target` workflows. Before the change:
+  - The evaluation ref could be the PR head SHA or the merge ref, depending on
+    how the workflow was written.
+  After the change (effective ~December 2025):
+  - `pull_request_target` workflows ALWAYS run from the **default branch** as the
+    workflow source reference (`GITHUB_REF`/`GITHUB_SHA`).
+  - Environment branch protection rules are now evaluated against the **execution
+    reference** (the default branch) rather than the PR head.
+
+  **Who is affected:**
+  Workflows using `pull_request_target` with environment deployments that have
+  branch protection rules configured to allow only specific branch patterns.
+
+  For example, if an environment's branch restriction allows `main` only, a
+  `pull_request_target` workflow that previously passed (because it matched some
+  derived ref) may now fail if GitHub evaluates a different ref. Conversely,
+  workflows that previously respected PR-branch restrictions may now bypass them
+  because the default branch is used instead.
+
+  This change was made for security: it ensures `pull_request_target` cannot be
+  used to circumvent branch-based deployment restrictions via crafted PR refs.
+
+  The `environment-protection-rules-silent-block` entry (triggers-006) covers the
+  general case of environment rules blocking deployment. This entry specifically
+  documents the November 2025 behavioral change and its migration path.
+fix: |
+  Update your environment branch protection rules to match the execution reference
+  used after the behavioral change:
+
+  1. **If deployments are now incorrectly blocked:** Add the default branch (e.g.,
+     `main`) to the environment's allowed branch patterns, since `pull_request_target`
+     now executes in the default branch context.
+
+  2. **If PR-based branch restrictions are no longer enforced:** Switch from
+     `pull_request_target` to `pull_request` (if the elevated-permissions use case
+     can be removed), which uses the PR head ref and respects branch-filter rules
+     as expected.
+
+  3. **For cross-repo PR deployments that legitimately need `pull_request_target`:**
+     Use required reviewers on the environment to gate deployments instead of
+     (or in addition to) branch restrictions — required reviewers are not affected
+     by this ref-evaluation change.
+fix_code:
+  - language: yaml
+    label: "Use pull_request instead of pull_request_target when elevated secrets not needed"
+    code: |
+      # Before (uses pull_request_target — broad access, affected by Nov 2025 change):
+      # on:
+      #   pull_request_target:
+      #     types: [opened, synchronize]
+
+      # After (use pull_request — runs in PR head context, branch filters work as expected):
+      on:
+        pull_request:
+          types: [opened, synchronize]
+          branches:
+            - main
+
+      jobs:
+        deploy-preview:
+          runs-on: ubuntu-latest
+          environment: staging
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "Deploy preview for ${{ github.head_ref }}"
+  - language: yaml
+    label: "Add required reviewers to the environment instead of relying on branch filters alone"
+    code: |
+      # In GitHub repo Settings → Environments → staging → Protection rules:
+      # ✅ Required reviewers: add team "platform-team"
+      # (branch restrictions can be kept or relaxed — human approval is the gate)
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          environment: staging         # requires approval from platform-team
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+prevention:
+  - "Prefer `pull_request` over `pull_request_target` unless your workflow specifically needs write permissions or secrets from the base repo for fork PR handling."
+  - "Use required reviewers in environments rather than relying solely on branch name patterns for deployment gating."
+  - "After enabling `pull_request_target`, validate that environment protection rules still behave as expected by reviewing which ref GitHub uses as the evaluation context."
+  - "Monitor the GitHub Actions changelog for behavioral changes to security-sensitive event types like `pull_request_target`."
+docs:
+  - url: "https://github.blog/changelog/2025-11-07-actions-pull_request_target-and-environment-branch-protections-changes/"
+    label: "GitHub Changelog: pull_request_target and environment branch protections changes (Nov 2025)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_target"
+    label: "GitHub Docs: pull_request_target event"
+  - 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://github.com/orgs/community/discussions/181616"
+    label: "Community Discussion: pull_request_target environment branch protection evaluation"

package/errors/triggers/required-status-check-renamed-never-passes.yml

@@ -0,0 +1,87 @@
+id: triggers-020
+title: "Renamed Workflow or Job Leaves Stale Required Status Check Permanently Blocking Merges"
+category: triggers
+severity: error
+tags:
+  - branch-protection
+  - required-status-checks
+  - workflow-rename
+  - merge-blocked
+  - repository-settings
+patterns:
+  - regex: "Expected.*Waiting for status to be reported"
+    flags: "i"
+  - regex: "Required status check.*has not passed"
+    flags: "i"
+error_messages:
+  - "Required status checks have not passed for this pull request"
+  - "Expected — Waiting for status to be reported"
+  - "Required status check has not passed"
+root_cause: |
+  GitHub branch protection rules reference required status checks by their EXACT string
+  name: `<Workflow Name> / <job-id>` (e.g., `CI / build`). When a workflow file's
+  `name:` field is changed, a job ID is renamed, or a third-party check context string
+  changes, the new check runs and passes — but the branch protection rule still
+  references the old string.
+
+  The old check name is stuck at "Expected — Waiting for status to be reported"
+  permanently because no workflow run ever reports that exact string again. Every PR
+  targeting the protected branch is blocked from merging regardless of CI status.
+
+  Common triggers:
+  - Renaming the top-level `name:` of a workflow file
+  - Renaming a job ID (`jobs.<id>`)
+  - Migrating from one CI system to another
+  - Using a third-party action that changed its check context string
+  - Refactoring a monorepo with multiple workflow files that share a check name
+
+  This affects all open PRs immediately when the workflow is renamed — there is no
+  grace period or deprecation.
+fix: |
+  1. Go to Settings → Branches → Branch protection rules → Edit for the affected branch.
+  2. Under "Require status checks to pass before merging", remove the stale check name.
+  3. Start typing the NEW check name and select it from the autocomplete dropdown.
+     The format is: "Workflow Name / job-id" (exactly as shown in the PR checks UI).
+  4. Save the branch protection rule.
+
+  To find the exact new check name without guessing:
+    gh api repos/{owner}/{repo}/commits/{ref}/check-runs --jq '.check_runs[].name'
+
+  If multiple branches are protected with the same stale rule, repeat for each.
+fix_code:
+  - language: yaml
+    label: "Find current check names via GitHub CLI"
+    code: |
+      # List all check names currently reported for the default branch
+      gh api "repos/{owner}/{repo}/commits/main/check-runs" \
+        --jq '.check_runs[] | "\(.name) — \(.status)/\(.conclusion)"'
+
+      # Or for a specific open PR's head SHA:
+      gh api "repos/{owner}/{repo}/commits/{sha}/check-runs" \
+        --jq '.check_runs[].name'
+  - language: yaml
+    label: "Prevention: document required check names in workflow comments"
+    code: |
+      # Branch protection references this check as: "CI / build"
+      # If you rename this workflow or job, update Settings > Branches > Protection rules
+      name: CI   # <-- changing this breaks the required check "CI / build"
+      on: [push, pull_request]
+
+      jobs:
+        build:   # <-- changing this ID also breaks "CI / build"
+          runs-on: ubuntu-latest
+          steps:
+            - run: make build
+prevention:
+  - "Before renaming a workflow or job, check Settings → Branches to see if any protection rules reference the current check name."
+  - "Add a comment in the workflow file listing the exact required status check string so renames are noticed."
+  - "After any workflow rename, immediately update branch protection rules and verify with an open PR."
+  - "Use the GitHub CLI command above to audit current check names after any CI refactor."
+  - "In monorepos, standardize workflow names and job IDs to minimize rename frequency."
+docs:
+  - url: "https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-status-checks-before-merging"
+    label: "GitHub Docs: Required status checks"
+  - url: "https://docs.github.com/en/rest/checks/runs#list-check-runs-for-a-git-reference"
+    label: "REST API: List check runs for a git reference"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#name"
+    label: "Workflow syntax: name field"

package/errors/triggers/schedule-cron-self-hosted-runner-not-triggered.yml

@@ -0,0 +1,107 @@
+id: triggers-024
+title: "Scheduled Cron Workflow Does Not Trigger on Self-Hosted Runner"
+category: triggers
+severity: error
+tags:
+  - cron
+  - schedule
+  - self-hosted-runner
+  - trigger
+  - offline
+patterns:
+  - regex: "cron.*self.hosted"
+    flags: "i"
+  - regex: "schedule.*self.hosted"
+    flags: "i"
+error_messages:
+  - "No trigger for scheduled cron task in Github actions on a self-hosted runner"
+root_cause: |
+  Scheduled (on: schedule) workflows are queued by GitHub hosted-runner dispatch
+  infrastructure. When the job targets a self-hosted runner (runs-on: [self-hosted, ...]),
+  the schedule dispatcher attempts to assign the job to a registered self-hosted runner.
+
+  The workflow silently never runs when:
+  1. The self-hosted runner is offline or disconnected at the moment the schedule fires.
+  2. The runner is busy with another job and no other runner with the required label is idle.
+  3. The runner binary is outdated or the registration token has expired, causing the runner
+     to appear registered but fail to accept new jobs.
+  4. The repository has been inactive for 60+ days (GitHub disables scheduled workflows
+     on inactive repositories automatically).
+
+  Unlike GitHub-hosted runners, where a fresh VM is provisioned on demand for every job,
+  self-hosted runners must be online and idle at exactly the moment the schedule fires.
+  If no eligible runner is available, the queued job is eventually abandoned with no retry
+  and no error visible in the Actions UI. The run simply does not appear.
+  Reported in actions/runner#4210 (21 reactions, open since Jan 2026).
+fix: |
+  Option 1 (recommended): Run the scheduled trigger on a GitHub-hosted runner.
+  Use ubuntu-latest for the schedule job and dispatch the real work to self-hosted
+  via workflow_dispatch or a separate triggered workflow.
+
+  Option 2: Use an external scheduler with workflow_dispatch.
+  Remove the on: schedule trigger. Use an external cron (cron job, cloud function, GitHub App)
+  to call the GitHub REST API dispatches endpoint on a schedule. The workflow is triggered
+  by workflow_dispatch instead, which does not require the runner to be available at a
+  fixed clock time.
+
+  Option 3: Ensure runner availability with a persistent service.
+  Run the self-hosted runner as a systemd service with Restart=always so it is online
+  when schedules fire. This reduces but does not eliminate the risk.
+fix_code:
+  - language: yaml
+    label: "Option 1: Schedule on GitHub-hosted, dispatch to self-hosted"
+    code: |
+      on:
+        schedule:
+          - cron: '0 2 * * *'
+        workflow_dispatch: {}
+
+      jobs:
+        # Lightweight orchestrator runs on GitHub-hosted (always available at schedule time)
+        trigger:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Trigger self-hosted workflow
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  await github.rest.actions.createWorkflowDispatch({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    workflow_id: 'heavy-work.yml',
+                    ref: 'main'
+                  });
+  - language: yaml
+    label: "Option 2: Receive dispatch from external cron scheduler"
+    code: |
+      # External scheduler calls:
+      # curl -X POST \
+      #   -H "Authorization: Bearer $GH_TOKEN" \
+      #   https://api.github.com/repos/OWNER/REPO/actions/workflows/nightly.yml/dispatches \
+      #   -d '{"ref":"main"}'
+      #
+      # Your workflow:
+      on:
+        workflow_dispatch: {}   # Triggered externally; no GitHub-side scheduling dependency
+
+      jobs:
+        nightly:
+          runs-on: [self-hosted, linux, x64]
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./scripts/nightly.sh
+prevention:
+  - "Run self-hosted runners as a persistent systemd service (Restart=always, RestartSec=10) to minimize offline windows."
+  - "Add workflow_dispatch: alongside schedule: so missed runs can be manually re-triggered from the Actions UI."
+  - "Monitor runner registration status via GET /repos/{owner}/{repo}/actions/runners and alert on offline runners."
+  - "Keep repositories active with at least one push or workflow run to prevent scheduled workflow disablement after 60 days of inactivity."
+  - "Consider using ephemeral runners with autoscaling (ARC) so runners are always provisioned on demand."
+docs:
+  - url: "https://github.com/actions/runner/issues/4210"
+    label: "actions/runner#4210 — Cron not triggering on self-hosted runner (Jan 2026)"
+  - url: "https://github.com/orgs/community/discussions/185024"
+    label: "Community discussion: self-hosted runner not triggering scheduled cron"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule"
+    label: "schedule event documentation"
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/disabling-and-enabling-a-workflow"
+    label: "Workflow disabled after 60 days of repo inactivity"