@htekdev/actions-debugger 1.0.0 → 1.0.2

package/errors/silent-failures/github-token-no-trigger.yml

@@ -1,57 +1,57 @@
-id: silent-failures-002
-title: "GITHUB_TOKEN Cannot Trigger Downstream Workflows"
-category: silent-failures
-severity: silent-failure
-tags:
-  - github-token
-  - triggers
-  - downstream
-  - workflow-chain
-  - authentication
-patterns:
-  - regex: "events triggered by the GITHUB_TOKEN.*will not create a new workflow run"
-    flags: "i"
-  - regex: "github-actions\\[bot\\]"
-    flags: "i"
-  - regex: "GITHUB_TOKEN"
-    flags: "i"
-error_messages:
-  - "Events triggered by the GITHUB_TOKEN will not create a new workflow run."
-root_cause: |
-  Commits, tags, and releases created with the repository `GITHUB_TOKEN` are intentionally
-  prevented from triggering most downstream workflows. This is a platform safety feature to
-  stop accidental recursion and workflow loops.
-
-  The upstream workflow appears to succeed, but the dependent workflow never starts, which
-  makes this feel like a silent trigger failure.
-fix: |
-  Use a GitHub App installation token or a PAT when you intentionally need one workflow to
-  trigger another via `push`, `create`, or `release`. Keep `GITHUB_TOKEN` for normal repo
-  automation that should not fan out into new workflow runs.
-fix_code:
-  - language: yaml
-    label: "Use a non-GITHUB_TOKEN credential for recursive automation"
-    code: |
-      jobs:
-        release:
-          runs-on: ubuntu-latest
-          steps:
-            - uses: actions/checkout@v4
-            - name: Create tag with a PAT
-              env:
-                GH_TOKEN: ${{ secrets.RELEASE_PAT }}
-              run: |
-                git tag v${{ github.run_number }}
-                git push https://x-access-token:${GH_TOKEN}@github.com/${{ github.repository }}.git --tags
-prevention:
-  - "Assume `GITHUB_TOKEN` will not fan out into downstream workflow runs unless you are using `workflow_dispatch` or `repository_dispatch`."
-  - "Document which automations require a GitHub App token or PAT."
-  - "Avoid recursive workflow designs that depend on implicit `push` triggers from `github-actions[bot]`."
-docs:
-  - url: "https://docs.github.com/en/actions/security-guides/automatic-token-authentication"
-    label: "Automatic token authentication"
-  - url: "https://docs.github.com/en/actions/reference/events-that-trigger-workflows"
-    label: "Events that trigger workflows"
-source:
-  article: "https://htek.dev/articles/github-actions-debugging-guide"
-  section: "GITHUB_TOKEN downstream trigger limitations"
+id: silent-failures-002
+title: "GITHUB_TOKEN Cannot Trigger Downstream Workflows"
+category: silent-failures
+severity: silent-failure
+tags:
+  - github-token
+  - triggers
+  - downstream
+  - workflow-chain
+  - authentication
+patterns:
+  - regex: "events triggered by the GITHUB_TOKEN.*will not create a new workflow run"
+    flags: "i"
+  - regex: "github-actions\\[bot\\]"
+    flags: "i"
+  - regex: "GITHUB_TOKEN"
+    flags: "i"
+error_messages:
+  - "Events triggered by the GITHUB_TOKEN will not create a new workflow run."
+root_cause: |
+  Commits, tags, and releases created with the repository `GITHUB_TOKEN` are intentionally
+  prevented from triggering most downstream workflows. This is a platform safety feature to
+  stop accidental recursion and workflow loops.
+
+  The upstream workflow appears to succeed, but the dependent workflow never starts, which
+  makes this feel like a silent trigger failure.
+fix: |
+  Use a GitHub App installation token or a PAT when you intentionally need one workflow to
+  trigger another via `push`, `create`, or `release`. Keep `GITHUB_TOKEN` for normal repo
+  automation that should not fan out into new workflow runs.
+fix_code:
+  - language: yaml
+    label: "Use a non-GITHUB_TOKEN credential for recursive automation"
+    code: |
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Create tag with a PAT
+              env:
+                GH_TOKEN: ${{ secrets.RELEASE_PAT }}
+              run: |
+                git tag v${{ github.run_number }}
+                git push https://x-access-token:${GH_TOKEN}@github.com/${{ github.repository }}.git --tags
+prevention:
+  - "Assume `GITHUB_TOKEN` will not fan out into downstream workflow runs unless you are using `workflow_dispatch` or `repository_dispatch`."
+  - "Document which automations require a GitHub App token or PAT."
+  - "Avoid recursive workflow designs that depend on implicit `push` triggers from `github-actions[bot]`."
+docs:
+  - url: "https://docs.github.com/en/actions/security-guides/automatic-token-authentication"
+    label: "Automatic token authentication"
+  - url: "https://docs.github.com/en/actions/reference/events-that-trigger-workflows"
+    label: "Events that trigger workflows"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "GITHUB_TOKEN downstream trigger limitations"

package/errors/silent-failures/reusable-workflow-env-secrets-empty.yml

@@ -0,0 +1,90 @@
+id: silent-failures-003
+title: "Reusable Workflow Environment-Scoped Secrets Resolve as Empty String"
+category: silent-failures
+severity: silent-failure
+tags:
+  - reusable-workflows
+  - secrets
+  - environments
+  - workflow-call
+  - secrets-inherit
+patterns:
+  - regex: "MY_SECRET length: 0"
+    flags: "i"
+  - regex: "secrets\\.[A-Z_]+\\s*:\\s*$"
+    flags: "m"
+error_messages:
+  - "MY_SECRET length: 0"
+  - "EMPTY"
+root_cause: |
+  When a reusable workflow (called via `workflow_call`) declares `environment: ${{ inputs.environment_name }}`
+  on its job, the GitHub Actions documentation states that environment-scoped secrets should resolve from
+  that environment. In practice, secrets resolve to empty string unless the caller adds `secrets: inherit`.
+
+  The `secrets: inherit` flag passes all of the caller's accessible secrets to the reusable workflow,
+  including environment-scoped secrets. Without it, the called workflow's secret resolution context is
+  narrowly scoped to explicitly mapped secrets — and environment-scoped secrets are not injected even when
+  the job correctly declares the environment name.
+
+  This is especially dangerous in matrix-based CI/CD pipelines where different matrix entries target
+  different environments (e.g., per-tenant deployments). The reusable workflow appears to run normally but
+  every secret it tries to use is silently empty. The failure can be masked for days if downstream systems
+  tolerate empty credentials during a grace period (e.g., pods using in-cluster Kubernetes Secrets).
+fix: |
+  Add `secrets: inherit` to the caller's job definition. This enables the reusable workflow to resolve
+  environment-scoped secrets from the environment declared on its job:
+
+  Alternatively, explicitly enumerate each secret you need to pass via the `secrets:` mapping block.
+  The explicit form is more secure for cross-repository reusable workflows.
+fix_code:
+  - language: yaml
+    label: "Add secrets: inherit so environment-scoped secrets resolve in the reusable workflow"
+    code: |
+      # Caller workflow
+      jobs:
+        deploy:
+          uses: ./.github/workflows/deploy.yml
+          with:
+            target_environment: production
+          secrets: inherit   # required — without this, env-scoped secrets are empty
+
+      # Reusable workflow (.github/workflows/deploy.yml) — no changes needed
+      on:
+        workflow_call:
+          inputs:
+            target_environment:
+              required: true
+              type: string
+      jobs:
+        worker:
+          runs-on: ubuntu-latest
+          environment: ${{ inputs.target_environment }}
+          steps:
+            - name: Use secret
+              env:
+                API_KEY: ${{ secrets.API_KEY }}
+              run: |
+                echo "API_KEY length: ${#API_KEY}"
+  - language: yaml
+    label: "Explicit secrets mapping (more secure for cross-repo reusable workflows)"
+    code: |
+      jobs:
+        deploy:
+          uses: org/infra/.github/workflows/deploy.yml@main
+          with:
+            target_environment: production
+          secrets:
+            API_KEY: ${{ secrets.API_KEY }}
+            DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
+prevention:
+  - "Always add `secrets: inherit` when a reusable workflow needs environment-scoped secrets."
+  - "Verify secret resolution by printing the secret length: `echo \"length ${#MY_SECRET}\"` — never print the value."
+  - "In matrix deployments targeting different environments, confirm each matrix item resolves its secrets before shipping."
+  - "Consider explicit secrets mapping for cross-repository workflows to avoid accidentally leaking unrelated secrets."
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows#passing-secrets-to-called-workflows"
+    label: "Passing secrets to called workflows"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-environments-for-deployment"
+    label: "Using environments for deployment"
+  - url: "https://github.com/actions/runner/issues/4453"
+    label: "actions/runner#4453 — Environment-scoped secrets unreachable without secrets: inherit"

package/errors/silent-failures/scheduled-workflow-disabled.yml

@@ -1,59 +1,59 @@
-id: silent-failures-001
-title: "Scheduled Workflows Silently Disabled After 60 Days"
-category: silent-failures
-severity: silent-failure
-tags:
-  - schedule
-  - cron
-  - inactivity
-  - disabled
-  - automation
-patterns:
-  - regex: "This scheduled workflow is disabled because there hasn't been activity in this repository for at least 60 days"
-    flags: "i"
-  - regex: "schedule.*workflow.*disabled"
-    flags: "i"
-error_messages:
-  - "This scheduled workflow is disabled because there hasn't been activity in this repository for at least 60 days"
-root_cause: |
-  In public repositories, GitHub automatically disables scheduled workflows after about
-  60 days with no repository activity. Nothing in the workflow YAML is technically wrong,
-  but the cron job stops firing until someone re-enables it or new activity occurs.
-
-  This feels like a silent failure because the expected schedule disappears rather than
-  producing a normal failed run.
-fix: |
-  Re-enable the workflow in the Actions UI and keep the repository active. If the schedule
-  must stay alive in a low-activity repository, add a keepalive workflow that periodically
-  creates harmless activity.
-fix_code:
-  - language: yaml
-    label: "Keep scheduled workflows active"
-    code: |
-      name: Keepalive
-
-      on:
-        schedule:
-          - cron: '0 6 * * 1'
-        workflow_dispatch:
-
-      jobs:
-        keepalive:
-          runs-on: ubuntu-latest
-          steps:
-            - uses: gautamkrishnar/keepalive-workflow@v2
-              with:
-                committer_username: github-actions[bot]
-                committer_email: 41898282+github-actions[bot]@users.noreply.github.com
-prevention:
-  - "Check the Actions tab periodically for disabled scheduled workflows in low-activity repositories."
-  - "Pair important cron automations with `workflow_dispatch` for manual recovery."
-  - "Use a keepalive strategy for public repos that rely on unattended schedules."
-docs:
-  - url: "https://docs.github.com/en/actions/reference/events-that-trigger-workflows#schedule"
-    label: "schedule event"
-  - url: "https://docs.github.com/en/actions/managing-workflow-runs/disabling-and-enabling-a-workflow"
-    label: "Disable and enable a workflow"
-source:
-  article: "https://htek.dev/articles/github-actions-debugging-guide"
-  section: "Scheduled workflows disabled after inactivity"
+id: silent-failures-001
+title: "Scheduled Workflows Silently Disabled After 60 Days"
+category: silent-failures
+severity: silent-failure
+tags:
+  - schedule
+  - cron
+  - inactivity
+  - disabled
+  - automation
+patterns:
+  - regex: "This scheduled workflow is disabled because there hasn't been activity in this repository for at least 60 days"
+    flags: "i"
+  - regex: "schedule.*workflow.*disabled"
+    flags: "i"
+error_messages:
+  - "This scheduled workflow is disabled because there hasn't been activity in this repository for at least 60 days"
+root_cause: |
+  In public repositories, GitHub automatically disables scheduled workflows after about
+  60 days with no repository activity. Nothing in the workflow YAML is technically wrong,
+  but the cron job stops firing until someone re-enables it or new activity occurs.
+
+  This feels like a silent failure because the expected schedule disappears rather than
+  producing a normal failed run.
+fix: |
+  Re-enable the workflow in the Actions UI and keep the repository active. If the schedule
+  must stay alive in a low-activity repository, add a keepalive workflow that periodically
+  creates harmless activity.
+fix_code:
+  - language: yaml
+    label: "Keep scheduled workflows active"
+    code: |
+      name: Keepalive
+
+      on:
+        schedule:
+          - cron: '0 6 * * 1'
+        workflow_dispatch:
+
+      jobs:
+        keepalive:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: gautamkrishnar/keepalive-workflow@v2
+              with:
+                committer_username: github-actions[bot]
+                committer_email: 41898282+github-actions[bot]@users.noreply.github.com
+prevention:
+  - "Check the Actions tab periodically for disabled scheduled workflows in low-activity repositories."
+  - "Pair important cron automations with `workflow_dispatch` for manual recovery."
+  - "Use a keepalive strategy for public repos that rely on unattended schedules."
+docs:
+  - url: "https://docs.github.com/en/actions/reference/events-that-trigger-workflows#schedule"
+    label: "schedule event"
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs/disabling-and-enabling-a-workflow"
+    label: "Disable and enable a workflow"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Scheduled workflows disabled after inactivity"

package/errors/silent-failures/sparse-checkout-sticky-cone-mode.yml

@@ -0,0 +1,120 @@
+id: silent-failures-008
+title: "Sparse Checkout Persists to Subsequent Checkout Steps (Sticky Cone Mode)"
+category: silent-failures
+severity: silent-failure
+tags:
+  - checkout
+  - sparse-checkout
+  - cone-mode
+  - composite-actions
+  - file-missing
+patterns:
+  - regex: "sparse.*checkout.*persist"
+    flags: "i"
+  - regex: "core\\.sparseCheckout.*true"
+    flags: "i"
+  - regex: "sparse-checkout.*not disabled"
+    flags: "i"
+error_messages:
+  - "Run actions/checkout@v4"
+  - "Expected full checkout but only sparse tree present"
+root_cause: |
+  When `actions/checkout` is called with `sparse-checkout:` options, it sets the git
+  repository's `core.sparseCheckout = true` config. A subsequent call to `actions/checkout`
+  in the same job — even WITHOUT specifying sparse-checkout — re-uses the existing git
+  repository and inherits the sticky `core.sparseCheckout = true` setting.
+
+  Result: the second checkout appears to succeed (no error), but the working directory
+  still contains only the sparse subset from the first checkout. Files outside the
+  original sparse pattern are silently absent.
+
+  This most commonly occurs in two scenarios:
+  1. A workflow calls `actions/checkout` with sparse-checkout for a fast initial clone,
+     then calls `actions/checkout` again (different ref, different path spec) expecting
+     a full checkout.
+  2. A workflow uses sparse-checkout, then calls a composite action that internally runs
+     its own `actions/checkout`. The composite action's checkout inherits the sparse
+     setting from the parent workflow's checkout.
+
+  Root cause: a bug in `actions/checkout` — the `disableSparseCheckout()` method does not
+  explicitly set `core.sparseCheckout false` when `sparse-checkout` input is absent. A
+  fix PR (#2034) exists in the repo but has not been merged as of 2026.
+fix: |
+  **Option 1 (recommended): Explicitly reset sparse-checkout between checkouts**
+  Add a `git sparse-checkout disable` step between the sparse and full checkouts. This
+  clears the sticky `core.sparseCheckout` flag and ensures subsequent checkouts are full.
+
+  **Option 2: Use separate `path:` directories**
+  Checkout into a unique subdirectory with the `path:` input to prevent git config
+  sharing. Each `path:` gets its own `.git` config.
+
+  **Option 3: Use `sparse-checkout-cone-mode: false` carefully**
+  When in non-cone mode, review that patterns don't accidentally match more or fewer
+  files than expected. Non-cone mode with incorrect patterns is its own source of
+  silent failures.
+fix_code:
+  - language: yaml
+    label: "Reset sparse-checkout before a subsequent full checkout"
+    code: |
+      steps:
+        # First checkout: sparse (fast clone for config files only)
+        - uses: actions/checkout@v4
+          with:
+            sparse-checkout: |
+              .github
+              config/
+
+        - name: Reset sparse-checkout so next checkout is full
+          shell: bash
+          run: git sparse-checkout disable
+
+        # Second checkout (in composite action or next step): now gets full tree
+        - uses: actions/checkout@v4
+          with:
+            ref: ${{ github.sha }}
+  - language: yaml
+    label: "Use separate path: directories to avoid shared git config"
+    code: |
+      steps:
+        # Sparse checkout into 'config-only/' subdirectory
+        - uses: actions/checkout@v4
+          with:
+            path: config-only
+            sparse-checkout: |
+              config/
+
+        # Full checkout into 'full-repo/' — completely separate git repo config
+        - uses: actions/checkout@v4
+          with:
+            path: full-repo
+  - language: yaml
+    label: "Composite action defensive reset (add to composite action's beginning)"
+    code: |
+      # In your composite action's action.yml — reset sparse before own checkout
+      runs:
+        using: composite
+        steps:
+          - name: Reset any inherited sparse-checkout
+            shell: bash
+            run: |
+              if git rev-parse --git-dir > /dev/null 2>&1; then
+                git sparse-checkout disable 2>/dev/null || true
+              fi
+
+          - uses: actions/checkout@v4
+            with:
+              ref: ${{ inputs.ref }}
+prevention:
+  - "Never assume a subsequent `actions/checkout` step gets a full tree if any earlier step used sparse-checkout."
+  - "Add `git sparse-checkout disable` as an explicit step between sparse and full checkouts in the same job."
+  - "When writing composite actions that call `actions/checkout`, add a defensive `git sparse-checkout disable` before your checkout step."
+  - "Use the `path:` input to isolate checkouts that need different content into separate directories."
+docs:
+  - url: "https://github.com/actions/checkout/issues/1498"
+    label: "actions/checkout#1498: Sparse checkout persists in composite action"
+  - url: "https://github.com/actions/checkout/pull/2034"
+    label: "actions/checkout#2034: Fix — disable sparse-checkout on subsequent checkout (open PR)"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsuses"
+    label: "Workflow syntax: steps.uses"
+  - url: "https://github.com/actions/checkout#usage"
+    label: "actions/checkout: Usage and sparse-checkout options"

package/errors/triggers/cron-schedule-late.yml

@@ -1,59 +1,59 @@
-id: triggers-003
-title: "Cron Schedule Running Late or Not Running"
-category: triggers
-severity: warning
-tags:
-  - cron
-  - schedule
-  - delay
-  - forks
-  - best-effort
-patterns:
-  - regex: "schedule"
-    flags: "i"
-  - regex: "Delayed"
-    flags: "i"
-  - regex: "This event will only trigger a workflow run if the workflow file exists on the default branch"
-    flags: "i"
-error_messages:
-  - "Scheduled workflows can be delayed during periods of high loads of GitHub Actions workflow runs."
-root_cause: |
-  GitHub Actions cron is best-effort, not real-time scheduling. During peak usage windows,
-  scheduled workflows can start 15 to 45 minutes late. In forks, scheduled workflows are also
-  disabled by default, so a copied workflow may never run until someone explicitly enables it.
-
-  The YAML can be correct and the repository can still see timing drift because the platform
-  does not guarantee precise minute-by-minute execution.
-fix: |
-  Treat cron timing as approximate. Schedule important automations away from the top of the
-  hour, add tolerance for startup drift, and provide a `workflow_dispatch` fallback for jobs
-  that sometimes need manual recovery.
-fix_code:
-  - language: yaml
-    label: "Add jitter-friendly scheduling and manual fallback"
-    code: |
-      name: Nightly maintenance
-
-      on:
-        schedule:
-          - cron: '17 3 * * *'
-        workflow_dispatch:
-
-      jobs:
-        maintain:
-          runs-on: ubuntu-latest
-          steps:
-            - uses: actions/checkout@v4
-            - run: ./scripts/maintenance.sh
-prevention:
-  - "Avoid scheduling critical jobs exactly at minute 0 because that is a common contention window."
-  - "Use external monitoring if a schedule must be near-real-time."
-  - "Enable scheduled workflows manually after creating a fork or after long inactivity."
-docs:
-  - url: "https://docs.github.com/en/actions/reference/events-that-trigger-workflows#schedule"
-    label: "schedule event"
-  - url: "https://docs.github.com/en/actions/managing-workflow-runs/disabling-and-enabling-a-workflow"
-    label: "Disable and enable a workflow"
-source:
-  article: "https://htek.dev/articles/github-actions-debugging-guide"
-  section: "Cron schedules running late"
+id: triggers-003
+title: "Cron Schedule Running Late or Not Running"
+category: triggers
+severity: warning
+tags:
+  - cron
+  - schedule
+  - delay
+  - forks
+  - best-effort
+patterns:
+  - regex: "schedule"
+    flags: "i"
+  - regex: "Delayed"
+    flags: "i"
+  - regex: "This event will only trigger a workflow run if the workflow file exists on the default branch"
+    flags: "i"
+error_messages:
+  - "Scheduled workflows can be delayed during periods of high loads of GitHub Actions workflow runs."
+root_cause: |
+  GitHub Actions cron is best-effort, not real-time scheduling. During peak usage windows,
+  scheduled workflows can start 15 to 45 minutes late. In forks, scheduled workflows are also
+  disabled by default, so a copied workflow may never run until someone explicitly enables it.
+
+  The YAML can be correct and the repository can still see timing drift because the platform
+  does not guarantee precise minute-by-minute execution.
+fix: |
+  Treat cron timing as approximate. Schedule important automations away from the top of the
+  hour, add tolerance for startup drift, and provide a `workflow_dispatch` fallback for jobs
+  that sometimes need manual recovery.
+fix_code:
+  - language: yaml
+    label: "Add jitter-friendly scheduling and manual fallback"
+    code: |
+      name: Nightly maintenance
+
+      on:
+        schedule:
+          - cron: '17 3 * * *'
+        workflow_dispatch:
+
+      jobs:
+        maintain:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./scripts/maintenance.sh
+prevention:
+  - "Avoid scheduling critical jobs exactly at minute 0 because that is a common contention window."
+  - "Use external monitoring if a schedule must be near-real-time."
+  - "Enable scheduled workflows manually after creating a fork or after long inactivity."
+docs:
+  - url: "https://docs.github.com/en/actions/reference/events-that-trigger-workflows#schedule"
+    label: "schedule event"
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs/disabling-and-enabling-a-workflow"
+    label: "Disable and enable a workflow"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Cron schedules running late"