@htekdev/actions-debugger 1.0.81 → 1.0.83

package/errors/runner-environment/ubuntu-24-ruby-not-preinstalled.yml

@@ -0,0 +1,74 @@
+id: runner-environment-146
+title: "ubuntu-24.04 runner — Ruby and gem not pre-installed"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24
+  - ruby
+  - gem
+  - tools-missing
+  - migration
+
+patterns:
+  - regex: 'ruby\s*:\s*command not found'
+    flags: i
+  - regex: 'gem\s*:\s*command not found'
+    flags: i
+  - regex: 'No such file or directory.*ruby'
+    flags: i
+
+error_messages:
+  - "/usr/bin/bash: ruby: command not found"
+  - "/usr/bin/bash: gem: command not found"
+  - "Error: ruby not found"
+
+root_cause: |
+  GitHub's ubuntu-24.04 runner image does not include Ruby in its pre-installed
+  software list. Unlike ubuntu-22.04 (which ships Ruby 3.0.x from the Ubuntu 22
+  package repository), ubuntu-24.04 dropped Ruby as a default pre-installed tool.
+
+  Workflows that rely on `ruby`, `gem`, `bundle`, or `rake` being available without
+  an explicit setup step will fail with "command not found" when the runner image is
+  ubuntu-24.04 or when ubuntu-latest resolves to ubuntu-24.04.
+
+  This commonly affects:
+  - Workflows that run `gem install` or `bundle install` directly
+  - Custom scripts that call `ruby my-script.rb`
+  - Jekyll static site workflows without the setup-ruby action
+  - Workflows that inherited ubuntu-22.04 behavior when pinned to ubuntu-latest
+
+fix: |
+  Use the ruby/setup-ruby action to install Ruby on any runner. This is the
+  recommended approach for cross-platform consistency and version pinning.
+
+  Alternatively, install Ruby via apt-get if a specific package-managed version
+  is acceptable, but ruby/setup-ruby is strongly preferred for version control.
+
+fix_code:
+  - language: yaml
+    label: "Use ruby/setup-ruby action (recommended)"
+    code: |
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true   # runs bundle install and caches gems
+
+      - run: ruby my-script.rb
+
+  - language: yaml
+    label: "Install via apt-get (version uncontrolled)"
+    code: |
+      - run: sudo apt-get install -y ruby ruby-dev
+
+prevention:
+  - Always use ruby/setup-ruby instead of relying on pre-installed Ruby.
+  - Test workflows against ubuntu-24.04 explicitly before switching ubuntu-latest.
+  - Check the ubuntu-24.04 pre-installed software list when migrating from ubuntu-22.04.
+
+docs:
+  - url: https://github.com/ruby/setup-ruby
+    label: "ruby/setup-ruby — GitHub Actions"
+  - url: https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md
+    label: "ubuntu-24.04 runner image — pre-installed software"
+  - url: https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2204-Readme.md
+    label: "ubuntu-22.04 runner image — Ruby pre-installed"

package/errors/runner-environment/windows-shell-powershell-is-ps5-not-ps7.yml

@@ -0,0 +1,85 @@
+id: runner-environment-147
+title: "Windows runner 'shell: powershell' invokes PowerShell 5 not PowerShell 7"
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - powershell
+  - pwsh
+  - shell
+  - powershell-version
+
+patterns:
+  - regex: 'The term .{0,20} is not recognized as the name of a cmdlet'
+    flags: i
+  - regex: 'Unexpected token.*\?\.'
+    flags: i
+  - regex: 'parameter cannot be found.*Parallel'
+    flags: i
+
+error_messages:
+  - "The term '??' is not recognized as the name of a cmdlet, function, script file, or operable program."
+  - "Unexpected token '?.' in expression or statement."
+  - "ForEach-Object: A parameter cannot be found that matches parameter name 'Parallel'."
+
+root_cause: |
+  On Windows GitHub-hosted runners, explicitly setting `shell: powershell` in a
+  workflow step invokes `powershell.exe` — Windows PowerShell 5.1 — NOT the modern
+  PowerShell 7.x (pwsh).
+
+  Windows PowerShell 5.1 is a separate executable that lacks numerous features
+  introduced in PowerShell 6.0 (Core) and later:
+  - Null-coalescing operator: `$a ?? $b` (requires PS 7.0+)
+  - Null-coalescing assignment: `$a ??= 'default'` (requires PS 7.0+)
+  - Null-conditional member access: `$obj?.Property` (requires PS 7.0+)
+  - Ternary operator: `$x ? $y : $z` (requires PS 7.0+)
+  - ForEach-Object -Parallel (requires PS 7.0+)
+  - Pipeline chain operators: `&&`, `||` (requires PS 7.0+)
+
+  The default shell on Windows runners (when no `shell:` key is specified) is `pwsh`
+  (PowerShell 7). This means workflows that omit `shell:` work fine, but any step that
+  explicitly adds `shell: powershell` regresses to PowerShell 5.1.
+
+  Developers often set `shell: powershell` when they mean "use PowerShell" without
+  knowing the distinction between Windows PowerShell and PowerShell 7.
+
+fix: |
+  Replace `shell: powershell` with `shell: pwsh` to use PowerShell 7.
+
+  If the workflow requires PowerShell 5.1 compatibility (rare), audit the script
+  and remove PS7-only syntax. However, in almost all cases the intent is PowerShell 7.
+
+fix_code:
+  - language: yaml
+    label: "Use pwsh for PowerShell 7 (fix)"
+    code: |
+      # Before (broken on modern PS syntax):
+      # - run: $value = $null ?? "default"
+      #   shell: powershell
+
+      # After (correct):
+      - run: $value = $null ?? "default"
+        shell: pwsh
+  - language: yaml
+    label: "Set pwsh as default shell for all Windows steps"
+    code: |
+      defaults:
+        run:
+          shell: pwsh
+
+      jobs:
+        build:
+          runs-on: windows-latest
+          steps:
+            - run: $value = $null ?? "default"   # uses pwsh by default
+
+prevention:
+  - 'Use `shell: pwsh` (not `shell: powershell`) in any step using PowerShell 6+ syntax.'
+  - 'Set `defaults.run.shell: pwsh` at workflow level to apply PowerShell 7 globally on Windows.'
+  - 'Use actionlint — it does not currently distinguish PS5 vs PS7 but code review should catch explicit `shell: powershell`.'
+
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-syntax-for-github-actions#jobsjob_idstepsshell'
+    label: 'Workflow syntax: shell — GitHub Docs'
+  - url: 'https://learn.microsoft.com/en-us/powershell/scripting/whats-new/differences-from-windows-powershell'
+    label: 'Differences between Windows PowerShell 5.1 and PowerShell 7 — Microsoft Docs'

package/errors/silent-failures/github-event-inputs-undefined-in-workflow-call.yml

@@ -0,0 +1,102 @@
+id: silent-failures-077
+title: '`github.event.inputs` is undefined (null) when workflow triggered via `workflow_call`'
+category: silent-failures
+severity: silent-failure
+tags:
+  - workflow-call
+  - workflow-dispatch
+  - inputs
+  - github-event-inputs
+  - reusable-workflow
+patterns:
+  - regex: 'github\.event\.inputs\.'
+    flags: 'g'
+  - regex: 'on:\s*\n\s+workflow_call:'
+    flags: 'im'
+error_messages:
+  - "Expression github.event.inputs.environment evaluated to ''"
+  - 'github.event.inputs is null'
+  - 'unexpected value '''''
+root_cause: |
+  When a workflow supports both `workflow_dispatch` and `workflow_call` triggers,
+  developers often use `github.event.inputs.param` to read input values.
+  This works for `workflow_dispatch` but silently fails for `workflow_call`:
+
+  - `workflow_dispatch`: inputs are surfaced at `github.event.inputs.*`
+    (always strings regardless of declared type)
+  - `workflow_call`: inputs are NOT placed in `github.event.inputs`; they are
+    only available via the `inputs` context (`inputs.param`)
+
+  When a reusable workflow is invoked via `workflow_call`, `github.event.inputs`
+  is an empty object — referencing `github.event.inputs.param` evaluates to an
+  empty string `''`, not an error. The workflow continues running with silently
+  missing parameter values, producing incorrect behavior rather than a visible
+  failure.
+
+  The `inputs` context (without `github.event.`) is the correct way to read
+  inputs in both scenarios, as it is populated for both `workflow_dispatch` and
+  `workflow_call`.
+fix: |
+  Replace all `github.event.inputs.*` references with `inputs.*` — the `inputs`
+  context works correctly for both `workflow_dispatch` and `workflow_call` events.
+fix_code:
+  - language: yaml
+    label: 'Use inputs context instead of github.event.inputs'
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              type: string
+              required: true
+        workflow_call:
+          inputs:
+            environment:
+              type: string
+              required: true
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            # BAD: github.event.inputs is empty/null in workflow_call context
+            - run: echo "Deploying to ${{ github.event.inputs.environment }}"
+
+            # GOOD: inputs context works for both workflow_dispatch and workflow_call
+            - run: echo "Deploying to ${{ inputs.environment }}"
+
+  - language: yaml
+    label: 'Dual-trigger workflow using inputs context correctly'
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            dry_run:
+              type: boolean
+              default: false
+        workflow_call:
+          inputs:
+            dry_run:
+              type: boolean
+              default: false
+
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            # inputs.dry_run works for both dispatch and call
+            - if: '!inputs.dry_run'
+              run: ./publish.sh
+prevention:
+  - 'Always use the `inputs` context (not `github.event.inputs`) when reading inputs in workflows that support both `workflow_dispatch` and `workflow_call`'
+  - 'Grep your workflow files for `github.event.inputs` and replace with `inputs` before adding a `workflow_call` trigger'
+  - '`github.event.inputs` values are always strings; `inputs` respects the declared type (boolean, number, string, choice)'
+  - 'Test reusable workflows by calling them from another workflow, not just via the UI dispatch button'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_call'
+    label: 'workflow_call event — GitHub Docs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch'
+    label: 'workflow_dispatch event — GitHub Docs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#inputs-context'
+    label: 'inputs context — GitHub Docs'

package/errors/silent-failures/job-outputs-block-missing-needs-always-empty.yml

@@ -0,0 +1,85 @@
+id: silent-failures-076
+title: "Job outputs: block missing — needs.job.outputs.key is always empty string in downstream jobs"
+category: silent-failures
+severity: silent-failure
+tags:
+  - job-outputs
+  - needs-context
+  - GITHUB_OUTPUT
+  - outputs-block
+  - empty-string
+  - downstream-jobs
+patterns:
+  - regex: 'needs\.[a-z_][a-z0-9_-]*\.outputs\.[a-z_][a-z0-9_-]*'
+    flags: 'i'
+error_messages:
+  - "needs.deploy.outputs.artifact_url is always empty string"
+  - "needs.build.outputs.sha: empty output in downstream job"
+root_cause: |
+  Writing to $GITHUB_OUTPUT inside a step only makes the value available within that job
+  via steps.<step_id>.outputs.<key>. To expose an output to downstream jobs via
+  needs.<job>.outputs.<key>, the job must explicitly declare an outputs: block that maps
+  key names to step output expressions using ${{ steps.<id>.outputs.<key> }}.
+
+  Without the job-level outputs: mapping, $GITHUB_OUTPUT writes are silently ignored by
+  downstream consumers — needs.<job>.outputs.<key> evaluates to an empty string with no
+  warning, error, or annotation. The step that wrote to $GITHUB_OUTPUT exits with code 0
+  and no indication of the problem.
+
+  This two-step mechanism is required: the step writes to $GITHUB_OUTPUT (job-internal),
+  and the job's outputs: block re-exports selected values to the workflow's needs graph.
+fix: |
+  Add an outputs: block at the job level (as a sibling of runs-on:, steps:, etc.)
+  that maps the desired key names to the corresponding step output expressions.
+  Every key you want accessible via needs.<job>.outputs.<key> must appear in this block.
+fix_code:
+  - language: yaml
+    label: "Correct: job outputs: block declares which step outputs to expose"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          outputs:
+            artifact-version: ${{ steps.version.outputs.value }}
+            build-sha: ${{ steps.hash.outputs.sha }}
+          steps:
+            - name: Compute version
+              id: version
+              run: echo "value=1.2.3" >> $GITHUB_OUTPUT
+            - name: Compute hash
+              id: hash
+              run: echo "sha=$(sha256sum dist/app | cut -d' ' -f1)" >> $GITHUB_OUTPUT
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying ${{ needs.build.outputs.artifact-version }}"
+  - language: yaml
+    label: "Wrong: outputs: block absent — needs.build.outputs.* is always empty"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          # No outputs: block — step writes are invisible to downstream jobs
+          steps:
+            - name: Compute version
+              id: version
+              run: echo "value=1.2.3" >> $GITHUB_OUTPUT
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "${{ needs.build.outputs.artifact-version }}"  # Always ''
+prevention:
+  - "Any job that produces values for downstream jobs MUST have a matching outputs: block"
+  - "Use actionlint — it warns when needs.<job>.outputs.<key> references an undeclared key"
+  - "Debug by printing ${{ toJSON(needs) }} in a downstream step to see all available outputs"
+  - "Note: steps.<id>.outputs.<key> within the same job does NOT require an outputs: block"
+  - "Composite action outputs and reusable workflow outputs have separate but analogous declaration requirements"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs"
+    label: "GitHub Docs: Passing information between jobs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idoutputs"
+    label: "GitHub Docs: jobs.<job_id>.outputs syntax"

package/errors/triggers/pull-request-closed-fires-for-unmerged-prs.yml

@@ -0,0 +1,79 @@
+id: triggers-057
+title: '`on.pull_request types: [closed]` fires for both merged AND unmerged PR closures — use `if: merged == true` guard'
+category: triggers
+severity: silent-failure
+tags:
+  - pull_request
+  - closed
+  - merged
+  - event-types
+  - deploy-on-merge
+
+patterns:
+  - regex: 'types:\s*\[.*closed.*\]'
+    flags: 'i'
+  - regex: 'on:\s*\n\s+pull_request:\s*\n\s+types:\s*\[.*closed'
+    flags: 'im'
+
+error_messages:
+  - "github.event.action: closed"
+  - "github.event.pull_request.merged: false"
+
+root_cause: |
+  The `pull_request` event `closed` type fires whenever a PR is closed — regardless
+  of whether it was merged or simply closed without merging. GitHub does not provide
+  a `merged` type for the `pull_request` event.
+
+  Developers commonly use `types: [closed]` to trigger deployment or post-merge
+  workflows, assuming `closed` is equivalent to "merged into the base branch". In
+  reality, a PR can be closed (abandoned, rejected) without being merged, and the
+  `closed` event fires in both cases.
+
+  The distinction is only available via `github.event.pull_request.merged` (a
+  boolean) or `github.event.pull_request.merge_commit_sha` (non-null if merged).
+  Without an explicit check, workflows using `types: [closed]` will run on
+  abandoned PRs, causing spurious deployments, incorrect release triggers, or
+  unnecessary job runs.
+
+fix: |
+  Add an `if:` condition to the job or workflow that checks
+  `github.event.pull_request.merged == true` to ensure the workflow only
+  proceeds when the PR was actually merged.
+
+fix_code:
+  - language: yaml
+    label: 'Guard job with merged == true check'
+    code: |
+      on:
+        pull_request:
+          types: [closed]
+
+      jobs:
+        deploy:
+          # Only run when PR was merged, not when simply closed
+          if: github.event.pull_request.merged == true
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+  - language: yaml
+    label: 'Equivalent guard using merge_commit_sha'
+    code: |
+      jobs:
+        notify:
+          if: github.event.pull_request.merge_commit_sha != ''
+          runs-on: ubuntu-latest
+          steps:
+            - name: Notify on merge
+              run: echo "PR merged at ${{ github.event.pull_request.merge_commit_sha }}"
+
+prevention:
+  - 'Never use `types: [closed]` without an `if: github.event.pull_request.merged == true` guard for merge-triggered workflows.'
+  - 'Remember: there is no `merged` event type for `pull_request` — `closed` is the closest type, but it requires the merged guard.'
+  - 'Test your workflow by manually closing a PR without merging and verifying the workflow does not run (or is skipped).'
+
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request'
+    label: 'pull_request event — GitHub Docs'
+  - url: 'https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request'
+    label: 'pull_request webhook payload — GitHub Docs'

package/errors/triggers/push-branches-filter-bypassed-by-tag-push.yml

@@ -0,0 +1,83 @@
+id: triggers-055
+title: "branches: filter does not apply to tag pushes — tag push always triggers unless tags-ignore is set"
+category: triggers
+severity: silent-failure
+tags:
+  - push
+  - branches-filter
+  - tags
+  - tag-push
+  - tags-ignore
+  - ref-type
+patterns:
+  - regex: 'on:\s*\n\s+push:\s*\n\s+branches:'
+    flags: 'm'
+  - regex: 'Triggered by refs/tags/'
+    flags: 'i'
+error_messages:
+  - "Run triggered by push to refs/tags/v1.0.0 (unexpected — only branches: [main] was set)"
+root_cause: |
+  The branches: filter under on.push: only evaluates branch refs (refs/heads/*). A push
+  to a tag ref (refs/tags/*) is an entirely separate ref type that the branches: filter
+  has no authority to gate. If no tags: or tags-ignore: filter is specified under
+  on.push:, ALL tag pushes pass through unconditionally.
+
+  This causes workflows intended to run "only on pushes to main" to also run on every
+  release tag, annotated tag, and automated tag created by CI pipelines.
+
+  Branch and tag filters are independent dimensions of the push event:
+    branches: / branches-ignore:  — applies ONLY to branch refs (refs/heads/*)
+    tags: / tags-ignore:          — applies ONLY to tag refs (refs/tags/*)
+
+  If a filter type is absent, all refs of that type pass through.
+  Setting branches: [main] does NOT automatically exclude tags.
+
+  The same mechanism applies in reverse: a tags: filter does not affect branch pushes.
+  And the paths: filter is also bypassed by tag pushes (see push-paths-filter-bypassed-by-tag).
+fix: |
+  To restrict the workflow to branch pushes only, add a tags-ignore: ['**'] pattern
+  to exclude all tag pushes. Alternatively, add an if: condition to check github.ref_type.
+fix_code:
+  - language: yaml
+    label: "Option 1: add tags-ignore to explicitly exclude all tag pushes"
+    code: |
+      on:
+        push:
+          branches:
+            - main
+            - 'release/**'
+          tags-ignore:
+            - '**'   # Exclude all tag pushes from triggering this workflow
+  - language: yaml
+    label: "Option 2: use if condition on the job to check ref_type"
+    code: |
+      on:
+        push:
+          branches:
+            - main
+
+      jobs:
+        build:
+          if: github.ref_type == 'branch'   # Skip if triggered by a tag push
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Only runs on branch pushes"
+  - language: yaml
+    label: "Option 3: explicitly allow specific tags alongside branches"
+    code: |
+      on:
+        push:
+          branches:
+            - main
+          tags:
+            - 'v[0-9]+.[0-9]+.[0-9]+'  # Only semver release tags; other tags excluded
+prevention:
+  - "Whenever you set branches:, also consider whether you need tags-ignore: ['**'] to exclude tag pushes"
+  - "Check if automated tooling (release-please, semantic-release, etc.) creates tags in your repo — they will trigger this workflow"
+  - "The same principle applies to paths: filter — it also does not block tag pushes"
+  - "Remember the rule: absent filter = all refs of that type pass through"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpushbranchestagsbranches-ignoretags-ignore"
+    label: "GitHub Docs: push event branches/tags filter syntax"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#push"
+    label: "GitHub Docs: Push event triggers"

package/errors/triggers/release-created-fires-on-draft.yml

@@ -0,0 +1,75 @@
+id: triggers-056
+title: '`on.release: types: [created]` fires when a draft release is first saved'
+category: triggers
+severity: silent-failure
+tags:
+  - release
+  - triggers
+  - draft
+  - created
+  - published
+patterns:
+  - regex: 'types:\s*\[?created\]?'
+    flags: 'i'
+  - regex: 'on:\s*\n\s+release:'
+    flags: 'im'
+error_messages:
+  - 'Triggered by: release'
+  - 'github.event.action: created'
+  - 'github.event.release.draft: true'
+root_cause: |
+  The `release` event with `types: [created]` fires when ANY release record is
+  first created in GitHub — including draft releases. When a developer clicks
+  "Save draft" to prepare release notes before publishing, GitHub fires the
+  `created` event immediately. This causes deployment or publish workflows to
+  run against an incomplete, unpublished draft.
+
+  The `created` type maps to the moment the release row is inserted in GitHub's
+  database, regardless of draft or published state. Many developers assume
+  `created` means "publicly released" because that mirrors the UI action of
+  clicking "Publish release", but the event fires earlier.
+
+  The correct type for "a release is now publicly visible" is `published`, which
+  fires only when the release transitions from draft (or pre-release) to a
+  published, non-draft release.
+fix: |
+  Use `types: [published]` for workflows that should only run when a release
+  becomes publicly available. Add an `if:` guard as a defensive layer when
+  using `created`.
+fix_code:
+  - language: yaml
+    label: 'Use published instead of created for deploy workflows'
+    code: |
+      # BAD: fires on draft creation too
+      on:
+        release:
+          types: [created]
+
+      # GOOD: fires only when release becomes publicly published
+      on:
+        release:
+          types: [published]
+  - language: yaml
+    label: 'Defensive if: guard when created type is required'
+    code: |
+      on:
+        release:
+          types: [created]
+      jobs:
+        deploy:
+          # Skip execution when triggered by a draft save
+          if: '!github.event.release.draft'
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+prevention:
+  - 'Prefer `types: [published]` for deployment workflows to avoid triggering on draft saves'
+  - 'Note: `published` also fires when a pre-release is promoted to a full release — guard with `!github.event.release.prerelease` if needed'
+  - 'Add `if: ''!github.event.release.draft''` as an explicit guard when using the `created` type'
+  - 'Test your release workflow by creating a draft release and verifying it does or does not trigger as expected'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#release'
+    label: 'release event — GitHub Docs'
+  - url: 'https://docs.github.com/en/rest/releases/releases#create-a-release'
+    label: 'Create a release REST API — GitHub Docs'

package/errors/yaml-syntax/reusable-workflow-with-secrets-context-rejected.yml

@@ -0,0 +1,98 @@
+id: yaml-syntax-052
+title: '`secrets` context not available in `with:` inputs for reusable workflow calls — use `secrets:` block instead'
+category: yaml-syntax
+severity: error
+tags:
+  - reusable-workflows
+  - secrets
+  - with
+  - workflow-call
+  - secrets-context
+
+patterns:
+  - regex: 'Context access might be invalid: secrets'
+    flags: 'i'
+  - regex: 'secrets\.[A-Z_][A-Z0-9_]*'
+    flags: 'i'
+
+error_messages:
+  - "Context access might be invalid: secrets"
+  - "The workflow is not valid. .github/workflows/caller.yml: Unrecognized named-value: 'secrets'"
+  - "Unrecognized named-value: 'secrets'. Located at position 1 within expression: secrets.MY_TOKEN"
+
+root_cause: |
+  When calling a reusable workflow, the `with:` key (which passes inputs) does NOT
+  have access to the `secrets` context. The `secrets` context is intentionally
+  restricted to the `secrets:` block of the reusable workflow call to prevent
+  secrets from being accidentally exposed as plain-text input values.
+
+  This restriction applies ONLY to reusable workflow calls (`jobs.<id>.uses:`).
+  Regular action steps (`steps.<id>.uses:`) DO allow `${{ secrets.MY_SECRET }}`
+  in their `with:` blocks.
+
+  Attempting to pass a secret via `with:` in a reusable workflow call results in
+  an actionlint error or a runtime error: "Context access might be invalid: secrets".
+  Even if it were allowed, passing secrets as `with:` inputs would expose the
+  secret value in the workflow logs as a plain-text input.
+
+  The correct mechanism is the `secrets:` mapping on the calling job, which
+  explicitly maps caller secrets to the callee's declared `on.workflow_call.secrets`
+  parameters. This preserves masking and audit trail.
+
+fix: |
+  Move secret values from `with:` to the `secrets:` block of the reusable
+  workflow call. Ensure the callee workflow declares the secret under
+  `on.workflow_call.secrets` with a matching name.
+
+fix_code:
+  - language: yaml
+    label: 'Caller workflow — pass secrets via secrets: not with:'
+    code: |
+      # BAD: secrets context not available in with:
+      # jobs:
+      #   call:
+      #     uses: ./.github/workflows/deploy.yml
+      #     with:
+      #       token: ${{ secrets.DEPLOY_TOKEN }}   # Error: secrets context invalid here
+
+      # GOOD: pass secrets via secrets: block
+      jobs:
+        call:
+          uses: ./.github/workflows/deploy.yml
+          with:
+            environment: production   # non-secret inputs go here
+          secrets:
+            deploy-token: ${{ secrets.DEPLOY_TOKEN }}   # secrets go here
+  - language: yaml
+    label: 'Callee workflow — declare secrets under on.workflow_call.secrets'
+    code: |
+      # .github/workflows/deploy.yml
+      on:
+        workflow_call:
+          inputs:
+            environment:
+              type: string
+              required: true
+          secrets:
+            deploy-token:
+              required: true
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Use the secret
+              env:
+                TOKEN: ${{ secrets.deploy-token }}
+              run: echo "Deploying to ${{ inputs.environment }}"
+
+prevention:
+  - 'Never use `${{ secrets.* }}` inside `with:` of a reusable workflow call — the `secrets` context is blocked there.'
+  - 'Declare all required secrets in the callee under `on.workflow_call.secrets:` and pass them via `secrets:` in the caller.'
+  - 'Run actionlint in CI to catch `secrets` context misuse before it reaches runtime.'
+
+docs:
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#using-inputs-and-secrets-in-a-reusable-workflow'
+    label: 'Using inputs and secrets in a reusable workflow — GitHub Docs'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#passing-secrets-to-called-workflows'
+    label: 'Passing secrets to called workflows — GitHub Docs'