@htekdev/actions-debugger 1.0.13 → 1.0.15

package/errors/known-unsolved/composite-action-step-timeout-minutes-ignored.yml

@@ -0,0 +1,146 @@
+id: known-unsolved-017
+title: "timeout-minutes Is Silently Ignored on Steps Inside Composite Actions"
+category: known-unsolved
+severity: limitation
+tags:
+  - timeout-minutes
+  - composite-action
+  - limitation
+  - step-timeout
+  - composite
+  - hung-step
+  - action-yml
+patterns:
+  - regex: "timeout.?minutes.*composite|using.*composite.*timeout"
+    flags: "i"
+  - regex: "Unexpected value 'timeout-minutes'"
+    flags: "i"
+error_messages:
+  - "Unexpected value 'timeout-minutes'"
+root_cause: |
+  GitHub Actions supports `timeout-minutes` at the job level and at individual step level
+  inside regular workflow files. However, `timeout-minutes` is NOT enforced on steps
+  inside composite actions (action.yml files using `runs.using: composite`).
+
+  Adding `timeout-minutes` to a step within a composite action's `steps:` block is
+  accepted by the YAML parser without error, but the timeout is silently NOT applied
+  at runtime. A hung step inside a composite action will run until the parent job's
+  overall `timeout-minutes` is exhausted — up to 6 hours on GitHub-hosted runners by
+  default.
+
+  This creates a dangerous gap:
+  - Network-dependent steps (downloads, API calls, package installs) inside a composite
+    action can hang indefinitely if the network is slow or unresponsive
+  - `actions/cache` intermittently stalls; wrapping it in a composite action with a
+    step `timeout-minutes: 5` provides NO protection
+  - Composite action authors cannot provide defensive step timeouts — users of the
+    composite action must rely entirely on the calling job's `timeout-minutes`
+  - Since the step timeout appears to be set (the YAML is valid), developers believe
+    they have a guard when they actually have none
+
+  The limitation has been tracked and discussed in the community since 2021
+  (actions/runner#1979) and remains unresolved as of 2026.
+
+  Source: actions/runner#1979 — "We would like to see timeout-minutes supported on
+  steps in composite actions. Occasionally actions like actions/cache bug out and run
+  for the default timeout time (6 hours) which causes unnecessary costs."
+fix: |
+  Since step-level timeouts cannot be enforced inside composite actions, use these
+  workarounds:
+
+  1. **Shell-level timeout**: Wrap commands in `timeout <seconds>` (bash) or `Start-Sleep`
+     + `Start-Job` with timeout (PowerShell) to kill hung processes from within the script.
+  2. **Job-level `timeout-minutes`**: Set a conservative timeout on the calling job as a
+     safety net — it limits the composite action's maximum runtime.
+  3. **Step-level timeout in the calling workflow**: When calling a composite action as
+     a step in a workflow file, `timeout-minutes` IS supported at the step level in the
+     workflow (not inside the composite itself). This provides a per-call timeout.
+  4. **Split into multiple reusable actions**: Replace a large composite action with
+     multiple smaller ones, each invoked as a separate workflow step — where step-level
+     `timeout-minutes` IS enforced.
+fix_code:
+  - language: yaml
+    label: "WRONG — timeout-minutes inside composite action step is silently ignored"
+    code: |
+      # action.yml — composite action
+      name: "Setup with Timeout"
+      runs:
+        using: composite
+        steps:
+          - name: Download dependencies
+            timeout-minutes: 5   # ← SILENTLY IGNORED — not enforced at runtime
+            shell: bash
+            run: curl -o deps.tar.gz "${{ inputs.deps-url }}"
+
+  - language: yaml
+    label: "Workaround: shell-level timeout inside composite action"
+    code: |
+      # action.yml — composite action
+      name: "Setup with Shell Timeout"
+      runs:
+        using: composite
+        steps:
+          - name: Download dependencies with shell timeout
+            shell: bash
+            run: |
+              # timeout-minutes on this step would be ignored — use shell timeout instead
+              timeout 300 curl -o deps.tar.gz "${{ inputs.deps-url }}" || {
+                echo "::error::Download timed out after 5 minutes"
+                exit 1
+              }
+
+          - name: Cache restore with timeout guard
+            shell: bash
+            run: |
+              timeout 120 ./restore-cache.sh || {
+                echo "::warning::Cache restore timed out — continuing without cache"
+              }
+
+  - language: yaml
+    label: "Workaround: step-level timeout in the calling WORKFLOW (not inside composite)"
+    code: |
+      # workflow.yml — timeout-minutes at step level in workflow DOES work
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: 30   # Job-level safety net
+          steps:
+            - uses: actions/checkout@v4
+
+            # timeout-minutes here is at the WORKFLOW step level — this IS enforced
+            - name: Run composite action
+              uses: ./.github/actions/my-composite-action
+              timeout-minutes: 10   # Works: this is a workflow step, not inside the composite
+
+            - run: npm run build
+
+  - language: yaml
+    label: "Workaround: split composite into multiple actions — each gets timeout"
+    code: |
+      # workflow.yml — multiple smaller actions instead of one large composite
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            # Each step in the workflow gets enforceable timeout-minutes
+            - uses: ./.github/actions/setup-node
+              timeout-minutes: 5    # Enforced — workflow step level
+
+            - uses: ./.github/actions/restore-cache
+              timeout-minutes: 3    # Enforced
+
+            - uses: ./.github/actions/install-deps
+              timeout-minutes: 10   # Enforced
+prevention:
+  - "Never rely on `timeout-minutes` inside composite action `steps:` — the field is accepted but silently ignored."
+  - "Use `timeout <seconds>` (bash) or PowerShell job timeouts as shell-level guards for long-running composite steps."
+  - "Apply `timeout-minutes` at the step level in the CALLING WORKFLOW (not inside the composite) for per-invocation limits."
+  - "Always set a job-level `timeout-minutes` on any job that calls composite actions, as a safety net against runaway steps."
+  - "Composite action authors should document the expected maximum runtime so callers can set appropriate job-level timeouts."
+docs:
+  - url: "https://github.com/actions/runner/issues/1979"
+    label: "actions/runner#1979 — timeout-minutes not enforced in composite action steps (open since 2021)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepstimeout-minutes"
+    label: "GitHub Docs: steps[*].timeout-minutes (workflow-level steps — works)"
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#runs-for-composite-actions"
+    label: "GitHub Docs: Metadata syntax for composite actions"

package/errors/known-unsolved/reusable-workflow-no-composite-action-call.yml

@@ -0,0 +1,116 @@
+id: known-unsolved-014
+title: "Reusable Workflows Cannot Be Called from Composite Actions"
+category: known-unsolved
+severity: limitation
+tags:
+  - composite-action
+  - reusable-workflow
+  - workflow-call
+  - limitation
+  - uses-key
+  - no-fix
+patterns:
+  - regex: "Reusable workflows cannot be referenced from composite actions"
+    flags: "i"
+  - regex: "uses:.*\\.github/workflows/.*\\.yml.*composite"
+    flags: "i"
+  - regex: "A reusable workflow cannot be used as a step in a composite action"
+    flags: "i"
+error_messages:
+  - "Error: Reusable workflows cannot be referenced from composite actions."
+  - "A reusable workflow cannot be used as a step in a composite action."
+root_cause: |
+  GitHub Actions enforces a strict separation between two different abstraction levels:
+  - **Actions** (composite, JavaScript, Docker) — called from workflow steps via `uses:`
+  - **Reusable workflows** (called via `workflow_call` trigger) — called from workflow jobs
+    via `uses:` at the JOB level, not the step level
+
+  A composite action runs within a step inside a job. A reusable workflow, however, IS a
+  job (or set of jobs). You cannot embed a job inside a step — this is a fundamental
+  architectural constraint, not a configuration error.
+
+  This fails at validation time with a clear error message. The error is triggered when:
+  - A composite action's `runs.steps` contains a `uses:` entry that points to a
+    `.github/workflows/*.yml` file (a reusable workflow)
+  - An organization tried to nest workflow-level orchestration inside a step-level action
+
+  There is no workaround that preserves both the composite action wrapping and the reusable
+  workflow invocation. GitHub has confirmed this is by design and has no plans to change it.
+  The GitHub Actions team's rationale: reusable workflows operate at the job/runner level
+  and require job-level context (needs:, outputs:, secrets: inheritance) that cannot exist
+  inside a step.
+fix: |
+  There is no fix — this is a platform limitation.
+
+  The recommended alternatives are:
+  1. **Restructure to call the reusable workflow at the job level** (not from inside a
+     composite action). Move the reusable workflow call to a dedicated job in your workflow
+     file using `jobs.my-job.uses:`.
+  2. **Convert the reusable workflow into a composite action** if the logic does not require
+     job-level features (matrix, needs: dependencies, explicit runner selection, secrets
+     inheritance via `secrets: inherit`).
+  3. **Inline the reusable workflow steps** into the composite action directly. While this
+     loses the DRY benefit of the reusable workflow, it resolves the structural constraint.
+fix_code:
+  - language: yaml
+    label: "Call reusable workflow at job level (not from composite action)"
+    code: |
+      # ❌ This FAILS — cannot call reusable workflow from composite action step
+      # In: .github/actions/my-composite/action.yml
+      # runs:
+      #   using: "composite"
+      #   steps:
+      #     - uses: ./.github/workflows/shared-build.yml   # ERROR: not allowed
+      #       with:
+      #         environment: staging
+
+      # ✅ Call reusable workflow at job level in workflow file instead
+      jobs:
+        setup:
+          runs-on: ubuntu-latest
+          steps:
+            # Composite action can still do pre/post steps
+            - uses: ./.github/actions/my-composite
+              with:
+                param: value
+
+        shared-build:
+          needs: setup
+          uses: ./.github/workflows/shared-build.yml
+          with:
+            environment: staging
+          secrets: inherit
+  - language: yaml
+    label: "Convert reusable workflow to composite action (when job-level features not needed)"
+    code: |
+      # .github/actions/shared-build/action.yml
+      name: "Shared Build"
+      description: "Composite action equivalent of the shared-build reusable workflow"
+      inputs:
+        environment:
+          required: true
+          description: "Target environment"
+      runs:
+        using: "composite"
+        steps:
+          - name: Setup Node
+            uses: actions/setup-node@v4
+            with:
+              node-version: '20'
+          - name: Build
+            shell: bash
+            run: npm run build:${{ inputs.environment }}
+prevention:
+  - "Understand the GitHub Actions hierarchy: Docker/JS/composite actions run WITHIN steps; reusable workflows run AS jobs."
+  - "Use composite actions when you want to share steps across workflows within a single job."
+  - "Use reusable workflows (workflow_call) when you want to share an entire job or multi-job sequence."
+  - "If you need both abstraction levels, combine them: a job calls a reusable workflow, and within that workflow's jobs, steps call composite actions."
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows#limitations"
+    label: "GitHub docs — Reusing workflows: limitations (composite action restriction)"
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action"
+    label: "GitHub docs — Creating a composite action"
+  - url: "https://github.com/orgs/community/discussions/11834"
+    label: "Community discussion #11834 — reusable workflow called from composite action error"
+  - url: "https://stackoverflow.com/questions/70421268/how-to-reference-a-reusable-workflow-from-a-composite-action"
+    label: "Stack Overflow — reference reusable workflow from composite action"

package/errors/known-unsolved/schedule-trigger-default-branch-only.yml

@@ -0,0 +1,113 @@
+id: known-unsolved-015
+title: "Scheduled Workflows Only Run on the Default Branch — Cannot Target Arbitrary Branches"
+category: known-unsolved
+severity: limitation
+tags:
+  - schedule
+  - cron
+  - default-branch
+  - trigger
+  - branches-filter
+  - platform-limitation
+patterns:
+  - regex: "schedule.*branches|branches.*schedule"
+    flags: "i"
+  - regex: "cron.*not.*branch|branch.*cron.*ignored"
+    flags: "i"
+  - regex: "Unexpected value 'branches'"
+    flags: "i"
+error_messages:
+  - "You have an error in your yaml syntax on line X"
+  - "Unexpected value 'branches'"
+  - "The 'branches' filter is not supported under 'schedule'"
+root_cause: |
+  GitHub Actions schedule (cron) triggers **always run the workflow file from the
+  repository's default branch** (typically `main`). This is an intentional platform
+  security constraint.
+
+  There is no supported way to target a non-default branch with a `schedule:` trigger:
+  - Adding `branches:` under `schedule:` causes a YAML syntax error ("Unexpected value
+    'branches'") — it is not a valid key in that position.
+  - Placing the schedule workflow on a non-default branch does not cause it to run.
+  - The `github.ref` and `github.head_ref` values will always reflect the default branch
+    when triggered by a schedule event.
+
+  **Why GitHub enforces this:**
+  If scheduled workflows could target arbitrary branches, an attacker who pushes
+  malicious code to a feature branch could have it execute on a cron schedule with the
+  repository's full secrets — a significant supply-chain risk. By restricting cron runs
+  to the default branch, GitHub ensures only reviewed/merged code runs on schedule.
+
+  **Platform impact:**
+  - Cannot create separate nightly build schedules for multiple branches from one repo.
+  - Cannot run a scheduled integration test on a long-lived release branch without
+    special workarounds.
+  - Community has requested this capability since 2021 (community discussion #16107).
+
+  Sources: Stack Overflow Q/A, GitHub Community #16107, GitHub Docs
+fix: |
+  There is no direct fix — this is a platform constraint. Use these workarounds:
+
+  **Workaround 1 (Recommended): Check out the target branch in the scheduled workflow**
+  Keep the scheduled workflow on the default branch but have the job check out the
+  desired branch in its `actions/checkout` step:
+
+  **Workaround 2: Trigger via `workflow_dispatch` from an external scheduler**
+  Use the GitHub REST API or `gh workflow run` from a controlled external system
+  (another scheduled job, GitHub App, etc.) to trigger a `workflow_dispatch` event
+  targeting a specific `ref` (branch or tag).
+
+  **Workaround 3: `workflow_run` chaining**
+  Not a direct substitute, but a workflow triggered by `workflow_run` on a push to
+  the target branch can perform scheduled-like follow-up logic.
+
+  **For release branches:** Merge a scheduled workflow file into each release branch
+  as part of the branch maintenance process — each branch can independently schedule
+  its own cron.
+fix_code:
+  - language: yaml
+    label: "Broken — branches filter not valid under schedule, causes YAML error"
+    code: |
+      # ❌ BROKEN: 'branches' is not a valid key under schedule — YAML syntax error
+      on:
+        schedule:
+          - cron: '0 1 * * *'
+            branches:          # ← invalid key, causes: Unexpected value 'branches'
+              - release/v2
+  - language: yaml
+    label: "Workaround — check out target branch in the scheduled workflow step"
+    code: |
+      # ✅ WORKAROUND: workflow lives on default branch, checks out the desired ref
+      on:
+        schedule:
+          - cron: '0 1 * * *'   # runs from default branch (main)
+
+      jobs:
+        nightly-test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: 'release/v2'    # explicitly check out the target branch
+            # All subsequent steps operate on release/v2 code
+            - run: ./run-tests.sh
+  - language: yaml
+    label: "Workaround — trigger workflow_dispatch against a specific branch via gh CLI"
+    code: |
+      # ✅ WORKAROUND: External script that fires workflow_dispatch targeting a branch
+      # Run this from another scheduled job (e.g., a GitHub App or a cron runner)
+      gh workflow run nightly.yml \
+        --repo owner/repo \
+        --ref release/v2        # workflow_dispatch supports specifying a branch ref
+prevention:
+  - "Do not add `branches:` under `schedule:` — it is not a valid key and will cause YAML syntax errors."
+  - "Design scheduled workflows to check out the target branch explicitly via `actions/checkout` with the `ref:` input."
+  - "For complex multi-branch scheduling needs, consider using a GitHub App or external scheduler that fires `workflow_dispatch` events targeting specific refs."
+  - "Document this platform limitation in team wikis to prevent repeated attempts at adding `branches:` to schedule triggers."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule"
+    label: "GitHub Docs: Events that trigger workflows — schedule"
+  - url: "https://github.com/orgs/community/discussions/16107"
+    label: "GitHub Community #16107 — Schedule trigger target branch request"
+  - url: "https://stackoverflow.com/questions/63612155/how-do-i-trigger-a-scheduled-action-on-a-specific-branch"
+    label: "Stack Overflow: How to trigger a scheduled action on a specific branch"

package/errors/known-unsolved/secrets-not-allowed-in-if-conditions.yml

@@ -0,0 +1,149 @@
+id: known-unsolved-016
+title: "secrets Context Cannot Be Directly Referenced in if: Conditions"
+category: known-unsolved
+severity: limitation
+tags:
+  - secrets
+  - if-condition
+  - conditional
+  - env
+  - limitation
+  - expressions
+  - step-condition
+patterns:
+  - regex: "if:.*\\$\\{\\{.*secrets\\..*\\}\\}"
+    flags: "i"
+  - regex: "secrets\\.[A-Z_a-z]+\\s*!=\\s*''"
+    flags: "i"
+error_messages:
+  - "This job was skipped."
+root_cause: |
+  GitHub Actions explicitly prohibits direct use of the `secrets` context in `if:`
+  conditional expressions at the job or step level. The platform blocks this as a
+  security measure to prevent secret values from being leaked through expression
+  evaluation in workflow logs.
+
+  Attempting `if: ${{ secrets.MY_SECRET != '' }}` or `if: secrets.MY_SECRET` silently
+  fails — the condition evaluates to an empty string (falsy), causing the step or job
+  to be skipped with no error message, warning, or explanation.
+
+  The same restriction applies at the job level:
+    ```yaml
+    jobs:
+      deploy:
+        if: ${{ secrets.DEPLOY_KEY != '' }}  # silently evaluates wrong
+    ```
+
+  This catches developers off guard because:
+  - The workflow is syntactically valid and passes YAML linting — no parse error
+  - The failure mode is silent: the job/step is skipped with "This job was skipped"
+    rather than an explicit error about the secrets restriction
+  - The pattern looks correct by analogy with other contexts (`github.*`, `env.*`,
+    `vars.*`) that DO work in `if:` conditions
+  - Secrets used in `run:` scripts and `with:` inputs work fine — only `if:` is blocked
+
+  GitHub's documentation explicitly states: "Secrets cannot be directly referenced
+  in `if:` conditionals. Instead, consider setting secrets as job-level environment
+  variables, then referencing the environment variables to conditionally run steps."
+
+  As of 2026 this is a by-design limitation with no planned native fix.
+  `actionlint` now flags direct secret references in `if:` expressions as an error.
+
+  Sources:
+  - GitHub Docs — Using secrets in GitHub Actions (use-secrets.md)
+  - github/docs#12722 — PR documenting the `if:` condition restriction
+fix: |
+  Promote the secret to a job-level `env:` variable that evaluates the boolean (not the
+  secret value itself), then reference `env.VARIABLE_NAME` in the `if:` condition.
+
+  For job-level `if:` (not step-level), use a preceding detection job that outputs
+  whether the secret is present, and condition the downstream job on that output.
+fix_code:
+  - language: yaml
+    label: "WRONG — direct secrets reference in step if: condition"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy to production
+              if: ${{ secrets.DEPLOY_KEY != '' }}  # silently wrong — step is skipped
+              run: ./deploy.sh
+              env:
+                DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
+
+  - language: yaml
+    label: "CORRECT — promote secret presence to job-level env, reference in step if:"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          env:
+            # Safe: evaluates to "true"/"false" string — not the secret value itself
+            HAS_DEPLOY_KEY: ${{ secrets.DEPLOY_KEY != '' }}
+          steps:
+            - name: Deploy to production
+              if: env.HAS_DEPLOY_KEY == 'true'
+              run: ./deploy.sh
+              env:
+                DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
+
+  - language: yaml
+    label: "CORRECT — job-level conditional via detection job + output"
+    code: |
+      jobs:
+        check-secrets:
+          runs-on: ubuntu-latest
+          outputs:
+            has_key: ${{ steps.check.outputs.has_key }}
+          steps:
+            - id: check
+              env:
+                DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
+              run: |
+                if [ -n "$DEPLOY_KEY" ]; then
+                  echo "has_key=true" >> "$GITHUB_OUTPUT"
+                else
+                  echo "has_key=false" >> "$GITHUB_OUTPUT"
+                fi
+
+        deploy:
+          needs: check-secrets
+          # Job-level if: can reference job outputs — not secrets directly
+          if: needs.check-secrets.outputs.has_key == 'true'
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./deploy.sh
+              env:
+                DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
+
+  - language: yaml
+    label: "CORRECT — inline env check using bash within step"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy (skip gracefully if secret absent)
+              env:
+                DEPLOY_KEY: ${{ secrets.DEPLOY_KEY }}
+              run: |
+                if [ -z "$DEPLOY_KEY" ]; then
+                  echo "No DEPLOY_KEY configured — skipping deployment"
+                  exit 0
+                fi
+                ./deploy.sh
+prevention:
+  - "Never reference `secrets.*` directly in `if:` conditions — always promote to `env:` first."
+  - "Use `env.HAS_SECRET: ${{ secrets.MY_SECRET != '' }}` at the job level to create a safe boolean env var."
+  - "Install and run `actionlint` in CI — it now flags direct secret references in `if:` as an error."
+  - "For job-level conditionals based on secret presence, use a dedicated detection job with outputs."
+docs:
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#using-secrets-in-a-workflow"
+    label: "GitHub Docs: Using secrets in a workflow (secrets cannot be in if: conditionals)"
+  - url: "https://github.com/github/docs/pull/12722"
+    label: "github/docs#12722 — Document secrets in if: conditionals limitation"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsif"
+    label: "Workflow syntax: steps[*].if"
+  - url: "https://github.com/rhysd/actionlint"
+    label: "actionlint — flags direct secrets in if: conditions as an error"

package/errors/permissions-auth/dependabot-pr-secrets-unavailable.yml

@@ -0,0 +1,133 @@
+id: permissions-auth-013
+title: "Dependabot Pull Requests Cannot Access Repository Secrets — Read-Only Token"
+category: permissions-auth
+severity: silent-failure
+tags:
+  - dependabot
+  - secrets
+  - github-token
+  - pull-request
+  - read-only
+patterns:
+  - regex: "Context access might be invalid: secrets\\."
+    flags: "i"
+  - regex: "denied|forbidden|403"
+    flags: "i"
+  - regex: "Resource not accessible by integration"
+    flags: "i"
+error_messages:
+  - "Context access might be invalid: secrets.NPM_TOKEN"
+  - "Error: Process completed with exit code 1."
+  - "HttpError: Resource not accessible by integration"
+root_cause: |
+  For security reasons, GitHub Actions workflows triggered by Dependabot pull requests
+  are granted a **read-only GITHUB_TOKEN** and **cannot access repository secrets**.
+
+  When a Dependabot PR triggers an `on: pull_request` workflow:
+  - `secrets.*` expressions evaluate to empty string (not an error — silently empty)
+  - `GITHUB_TOKEN` has read-only permissions (cannot write to the repository, push
+    tags, create releases, comment on PRs, etc.)
+  - Steps that need secrets (publishing to npm, Docker Hub, PyPI, etc.) fail with
+    authentication errors or silently produce wrong results
+
+  This is intentional: Dependabot opens PRs that update dependencies from external
+  sources. If Dependabot-triggered workflows had full secret access, a malicious
+  package update could exfiltrate your credentials via a modified build step.
+
+  The failure is often silent because:
+  - The secret evaluates to empty string — tools may fail with "missing credentials"
+    rather than a clear "secret unavailable" error
+  - `GITHUB_TOKEN` write failures show as 403 "Resource not accessible by integration"
+
+  Sources: dependabot/dependabot-core#3253, #5464
+fix: |
+  Choose one of these approaches depending on your security requirements:
+
+  **Option 1 (Recommended): Use Dependabot secrets**
+  Add the required secrets to the Dependabot secrets store (Settings > Secrets and
+  variables > Dependabot). Dependabot-triggered workflows can access these separately
+  from repository secrets.
+
+  **Option 2: Auto-approve and merge without secrets**
+  For dependency updates, use `pull_request_review` + `pull_request` auto-merge
+  pattern — approve Dependabot PRs that pass CI without needing secrets.
+
+  **Option 3: Use `pull_request_target` with caution**
+  `pull_request_target` runs in the base repo context and has full secret access.
+  Only use this for trusted, controlled steps (like leaving a comment) — never
+  checkout and run untrusted fork code in a `pull_request_target` step with secrets.
+
+  **Option 4: Filter out Dependabot runs**
+  Add `if: github.actor != 'dependabot[bot]'` to skip secret-requiring steps for
+  Dependabot PRs, letting CI pass without the publishing step.
+fix_code:
+  - language: yaml
+    label: "Add secrets to Dependabot secrets store (Settings → Secrets → Dependabot)"
+    code: |
+      # Add NPM_TOKEN (and any other required secrets) to:
+      # Settings > Secrets and variables > Dependabot
+      # These are separate from repository secrets and accessible to Dependabot runs.
+
+      # No workflow change needed — ${{ secrets.NPM_TOKEN }} will resolve correctly
+      # once the secret is added to the Dependabot secrets store.
+  - language: yaml
+    label: "Skip secret-requiring steps for Dependabot PRs"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Run tests
+              run: npm test
+              # Tests run for all PRs including Dependabot
+
+            - name: Publish to npm (skip for Dependabot)
+              if: github.actor != 'dependabot[bot]'
+              run: npm publish
+              env:
+                NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+              # NPM_TOKEN is empty for Dependabot — skip the step entirely
+  - language: yaml
+    label: "Auto-approve Dependabot PRs using Dependabot secrets + gh CLI"
+    code: |
+      name: Auto-approve Dependabot
+      on: pull_request
+
+      permissions:
+        pull-requests: write
+        contents: write
+
+      jobs:
+        auto-approve:
+          runs-on: ubuntu-latest
+          if: github.actor == 'dependabot[bot]'
+          steps:
+            - name: Fetch Dependabot metadata
+              id: meta
+              uses: dependabot/fetch-metadata@v2
+
+            - name: Auto-approve minor and patch updates
+              if: steps.meta.outputs.update-type != 'version-update:semver-major'
+              run: gh pr review --approve "$PR_URL"
+              env:
+                PR_URL: ${{ github.event.pull_request.html_url }}
+                GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+                # GITHUB_TOKEN in dependabot context is read-only for repo content
+                # but CAN approve PRs when permissions: pull-requests: write is set
+prevention:
+  - "Never assume repository secrets are available in Dependabot-triggered workflows — they aren't."
+  - "Use `github.actor == 'dependabot[bot]'` conditions to branch logic for Dependabot vs human PRs."
+  - "Add required secrets to the Dependabot secrets store separately from repository secrets."
+  - "Audit CI workflows for `${{ secrets.* }}` usage and test with a Dependabot PR to confirm behavior."
+  - "Do not use `pull_request_target` with `actions/checkout` on the PR head ref — this is a security vulnerability."
+docs:
+  - url: "https://docs.github.com/en/code-security/dependabot/working-with-dependabot/automating-dependabot-with-github-actions"
+    label: "Automating Dependabot with GitHub Actions"
+  - url: "https://docs.github.com/en/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot"
+    label: "Configuring Dependabot secrets"
+  - url: "https://github.com/dependabot/dependabot-core/issues/3253"
+    label: "dependabot-core#3253 — secrets unavailable in Dependabot-triggered workflows"
+  - url: "https://github.com/dependabot/dependabot-core/issues/5464"
+    label: "dependabot-core#5464 — Dependabot read-only token behavior"