@htekdev/actions-debugger 1.0.79 → 1.0.81

package/errors/caching-artifacts/cache-exact-key-hit-skips-save-stale.yml

@@ -0,0 +1,81 @@
+id: caching-artifacts-046
+title: "actions/cache exact key hit skips save step — caches go stale when dependency hash doesn't change"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - save-always
+  - cache-hit
+  - stale-cache
+  - cache-invalidation
+patterns:
+  - regex: 'Cache hit occurred on the primary key'
+    flags: i
+  - regex: 'Not saving cache'
+    flags: i
+error_messages:
+  - "Cache hit occurred on the primary key, not saving cache."
+  - "Not saving cache as it is not requested."
+root_cause: |
+  When actions/cache finds an exact match for the primary key, it sets
+  cache-hit: 'true' and the post-step save is skipped entirely. The rationale is
+  that since the key already exists, re-saving an identical entry would be wasteful.
+
+  However, this behaviour means that cache content changes that do NOT affect the
+  hash (e.g., transitive package security patches, tool binary updates, or
+  generated files included in the cached path) are never persisted. The cache
+  entry stays frozen at the state it was in when the key was first saved.
+
+  Common scenario: a workflow caches node_modules keyed on package-lock.json hash.
+  The lock file goes unchanged for weeks, but npm packages receive silent patch
+  updates or a cached binary becomes corrupt. Every run gets a cache hit, skips the
+  save, and the stale or corrupt content continues to be served until the lock file
+  hash finally changes.
+fix: |
+  Set save-always: true on the cache step to force a save even when the exact key
+  already exists. For finer control, split the action into separate
+  actions/cache/restore and actions/cache/save steps so the save can run
+  conditionally. To immediately invalidate a specific cache entry, delete it via
+  the GitHub REST API or the Actions UI under Repository > Actions > Caches.
+fix_code:
+  - language: yaml
+    label: "Force save on every run with save-always"
+    code: |
+      - name: Cache node_modules
+        uses: actions/cache@v4
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: ${{ runner.os }}-node-
+          # Always save even if exact key already exists in the cache
+          save-always: true
+
+  - language: yaml
+    label: "Split restore and save for conditional save logic"
+    code: |
+      - name: Restore cache
+        id: cache-restore
+        uses: actions/cache/restore@v4
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: ${{ runner.os }}-node-
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Save cache
+        uses: actions/cache/save@v4
+        if: always()
+        with:
+          path: node_modules
+          key: ${{ steps.cache-restore.outputs.cache-primary-key }}
+prevention:
+  - "Use save-always: true when cached content may diverge from the hash key (e.g., tool caches, binary downloads)."
+  - "Periodically evict stale cache entries via the GitHub REST API DELETE /repos/{owner}/{repo}/actions/caches/{cache_id}."
+  - "Include a tool version or date component in the cache key when the content should rotate on a schedule."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows"
+    label: "GitHub Actions: Caching dependencies"
+  - url: "https://github.com/actions/cache#save-always"
+    label: "actions/cache README: save-always option"

package/errors/caching-artifacts/cache-lookup-only-no-restore-silent.yml

@@ -0,0 +1,88 @@
+id: caching-artifacts-048
+title: "actions/cache lookup-only: true checks cache existence but does NOT restore files"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - cache
+  - lookup-only
+  - cache-hit
+  - restore
+  - silent-no-op
+patterns:
+  - regex: 'lookup-only.*true'
+    flags: 'i'
+  - regex: 'Cache found and can be restored from key'
+    flags: 'i'
+error_messages:
+  - "Cache found and can be restored from key: node-modules-abc123"
+  - "lookup-only is set, skipping restore."
+root_cause: |
+  The lookup-only: true input on actions/cache@v4 instructs the action to query
+  the cache service and report whether an entry exists (via the cache-hit output)
+  without transferring any data to the runner. No files are downloaded or written
+  to disk.
+
+  Developers who add lookup-only: true hoping to get a "lightweight restore that
+  skips the upload post-step" receive a misleading green step. The cache-hit output
+  reports 'true', the step log says "Cache found and can be restored from key",
+  and everything looks successful — but the working directory is empty.
+  Subsequent build steps that depend on the cached files fail with cryptic errors
+  (missing executables, import errors, or blank node_modules) that appear unrelated
+  to caching.
+
+  The intended use case for lookup-only is a two-job pipeline: Job A checks if the
+  cache exists (lookup-only: true) and, if not, builds and saves it; Job B restores
+  normally. It is NOT a performance shortcut for regular restore-and-save workflows.
+fix: |
+  Remove lookup-only: true from any step that should actually restore cached files.
+  Use lookup-only: true only in a dedicated pre-check job that gates whether an
+  expensive build step needs to run, combined with a normal actions/cache step in
+  the subsequent job that performs the real restore.
+fix_code:
+  - language: yaml
+    label: "Remove lookup-only for normal cache restore (most cases)"
+    code: |
+      - name: Restore node_modules cache
+        id: cache
+        uses: actions/cache@v4
+        with:
+          path: node_modules
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: ${{ runner.os }}-node-
+          # Do NOT set lookup-only: true here — files must be restored
+  - language: yaml
+    label: "Correct pattern: lookup-only in check job, real restore in build job"
+    code: |
+      jobs:
+        check-cache:
+          runs-on: ubuntu-latest
+          outputs:
+            cache-hit: ${{ steps.lookup.outputs.cache-hit }}
+          steps:
+            - id: lookup
+              uses: actions/cache@v4
+              with:
+                path: node_modules
+                key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+                lookup-only: true   # only check — no download
+
+        build:
+          needs: check-cache
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/cache@v4
+              with:
+                path: node_modules
+                key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+                # no lookup-only — restores files and saves after build
+            - if: needs.check-cache.outputs.cache-hit != 'true'
+              run: npm ci
+prevention:
+  - "Only use lookup-only: true in a dedicated cache-check job that feeds a conditional build gate."
+  - "After using lookup-only, always follow up with a standard actions/cache step (no lookup-only) in the job that needs the files."
+  - "If you want to skip the post-step cache save, use actions/cache/restore instead of setting lookup-only: true."
+docs:
+  - url: "https://github.com/actions/cache#inputs"
+    label: "actions/cache README: inputs including lookup-only"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows"
+    label: "GitHub Actions: Caching dependencies"

package/errors/caching-artifacts/upload-artifact-rerun-run-id-collision.yml

@@ -0,0 +1,67 @@
+id: caching-artifacts-047
+title: "Re-run job fails with 'artifact already exists' when artifact name includes github.run_id"
+category: caching-artifacts
+severity: error
+tags:
+  - upload-artifact
+  - re-run
+  - run_id
+  - run_attempt
+  - artifact-name
+  - collision
+patterns:
+  - regex: 'An artifact with this name already exists on the workflow run'
+    flags: 'i'
+  - regex: 'Unable to upload artifact.*already exists'
+    flags: 'i'
+error_messages:
+  - "An artifact with this name already exists on the workflow run."
+  - "Unable to upload artifact: An artifact with this name already exists on the run."
+root_cause: |
+  github.run_id identifies a workflow run and remains the same value across all
+  re-run attempts triggered from the GitHub UI or REST API. When an artifact name
+  is constructed using github.run_id (e.g., my-build-${{ github.run_id }}), the
+  first attempt uploads successfully. If the job fails and is re-run, the re-run
+  attempt tries to create an artifact with the identical name on the same run.
+
+  actions/upload-artifact@v4 enforces unique artifact names per run as a hard
+  error (changed from v3 which silently overwrote). The re-run therefore fails
+  immediately with "artifact already exists" before any meaningful work is done.
+
+  Teams reach for run_id because it appears to be a unique-per-execution
+  identifier. It is not: it is unique per workflow trigger, stable across all
+  re-run attempts within that trigger.
+fix: |
+  Append github.run_attempt to the artifact name. run_attempt starts at 1 and
+  increments for each re-run of the same run_id, making the combined value unique
+  across attempts. Consumers of the artifact (download steps, workflow_run
+  triggers) must include run_attempt in their own references to locate the
+  correct artifact.
+fix_code:
+  - language: yaml
+    label: "Include run_attempt to make artifact name unique across re-runs"
+    code: |
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          # run_attempt increments on each re-run, preventing name collision
+          name: my-build-${{ github.run_id }}-${{ github.run_attempt }}
+          path: dist/
+  - language: yaml
+    label: "Download the matching artifact in a downstream job"
+    code: |
+      - name: Download build artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: my-build-${{ github.run_id }}-${{ github.run_attempt }}
+          path: dist/
+prevention:
+  - "Never use github.run_id alone as an artifact name uniqueness guarantee — it is stable across all re-runs of the same run."
+  - "Combine github.run_id with github.run_attempt to produce a name that is unique within a run AND across re-run attempts."
+  - "Use a matrix value or job name as the differentiator instead of run_id when the artifact is consumed by a job in the same workflow."
+  - "Check the GitHub UI Actions > Artifacts list to inspect existing artifact names before debugging re-run failures."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-workflow-data-as-artifacts"
+    label: "GitHub Actions: Storing workflow data as artifacts"
+  - url: "https://github.com/actions/upload-artifact#not-uploading-to-the-same-artifact"
+    label: "actions/upload-artifact: unique artifact names per run"

package/errors/concurrency-timing/workflow-dispatch-push-shared-concurrency-cancel.yml

@@ -0,0 +1,64 @@
+id: concurrency-timing-040
+title: "workflow_dispatch and push share concurrency group, dispatch cancels in-progress CI"
+category: concurrency-timing
+severity: error
+tags:
+  - concurrency
+  - workflow-dispatch
+  - push
+  - cancel-in-progress
+  - event-name
+patterns:
+  - regex: 'This run was cancelled'
+    flags: i
+  - regex: 'concurrency.*workflow_dispatch|workflow_dispatch.*concurrency'
+    flags: ims
+error_messages:
+  - "This run was cancelled."
+  - "A run for this workflow is already in progress."
+root_cause: |
+  When a concurrency group key is built from github.workflow and github.ref alone,
+  both workflow_dispatch and push events on the same branch produce an identical key.
+  GitHub treats them as competing occupants of the same concurrency slot.
+
+  With cancel-in-progress: true, a manually dispatched run immediately cancels any
+  push-triggered CI run already in progress (or vice versa). Without cancel-in-progress,
+  the dispatch run queues behind the push run but still competes for the same slot.
+
+  This catches developers off guard when they manually trigger a workflow for
+  debugging while CI is running — the in-progress CI run is silently cancelled. Or a
+  push to the same branch during a long dispatch run causes the dispatch to be evicted.
+fix: |
+  Include github.event_name in the concurrency group key to give workflow_dispatch
+  and push events separate concurrency slots. Alternatively, use a conditional
+  cancel-in-progress expression so manual dispatches are never cancelled.
+fix_code:
+  - language: yaml
+    label: "Include event_name to separate dispatch and push slots"
+    code: |
+      # WRONG: dispatch and push on same branch share a slot and cancel each other
+      # concurrency:
+      #   group: ${{ github.workflow }}-${{ github.ref }}
+      #   cancel-in-progress: true
+
+      # CORRECT: each event type gets its own concurrency slot
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
+        cancel-in-progress: true
+
+  - language: yaml
+    label: "Alternative: only cancel-in-progress for push and pull_request, not dispatch"
+    code: |
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        # Manual dispatches are never cancelled; push/PR runs are stacked-and-cancelled
+        cancel-in-progress: ${{ github.event_name != 'workflow_dispatch' }}
+prevention:
+  - "Always include github.event_name in concurrency group keys when a workflow has multiple trigger events."
+  - "Test concurrency behavior by triggering both events in quick succession; bugs only surface under race conditions."
+  - "For release or deploy workflows, consider separate workflows for dispatch vs automated CI rather than sharing concurrency."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#concurrency"
+    label: "GitHub Actions: Concurrency syntax"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch"
+    label: "GitHub Actions: workflow_dispatch event"

package/errors/permissions-auth/dependabot-pr-repository-secrets-not-injected.yml

@@ -0,0 +1,81 @@
+id: permissions-auth-048
+title: "Dependabot PR workflows cannot access repository secrets — only Dependabot secrets are injected"
+category: permissions-auth
+severity: error
+tags:
+  - dependabot
+  - secrets
+  - pull-request
+  - registry-auth
+  - secret-isolation
+patterns:
+  - regex: 'Input required and not supplied'
+    flags: i
+  - regex: '401 Unauthorized'
+    flags: i
+error_messages:
+  - "Error: Input required and not supplied: token"
+  - "npm ERR! code E401"
+  - "Error: Unauthorized"
+root_cause: |
+  When Dependabot opens or updates a pull request, GitHub Actions workflows triggered
+  by that PR run in an isolated secret context. Repository secrets (defined under
+  Settings > Secrets and variables > Actions) are NOT injected into Dependabot-triggered
+  workflow runs. Only secrets defined under Settings > Secrets and variables > Dependabot
+  are available.
+
+  This means steps that reference secrets.NPM_TOKEN, secrets.DOCKER_PASSWORD,
+  secrets.SONAR_TOKEN, or any custom repository secret will receive an empty string.
+  Actions that validate their inputs (e.g., a custom action with required: true on a
+  token input) will fail with "Input required and not supplied". Registry steps will
+  fail with 401 Unauthorized.
+
+  GITHUB_TOKEN is exempt and is still injected normally for Dependabot runs.
+fix: |
+  Re-create the required secrets under Settings > Secrets and variables > Dependabot
+  (a separate namespace from Actions secrets). Dependabot reads from its own secret
+  store, not the repository Actions secret store. Alternatively, restructure the
+  workflow so secret-dependent steps only run on non-Dependabot actors using an
+  if: condition.
+fix_code:
+  - language: yaml
+    label: "Add secrets to Dependabot secret store in GitHub UI"
+    code: |
+      # In GitHub: Settings > Secrets and variables > Dependabot
+      # Add the same secret names you use in your Actions secrets.
+      # They are stored separately and only injected for Dependabot-triggered runs.
+
+      # No workflow YAML change required — just add the secret in the UI.
+      # Example workflow remains unchanged:
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm publish
+              env:
+                NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}  # Works once added to Dependabot secrets
+
+  - language: yaml
+    label: "Skip secret-dependent steps when actor is dependabot"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Publish to registry
+              # Skip publish step for Dependabot PRs that lack the token
+              if: github.actor != 'dependabot[bot]'
+              run: npm publish
+              env:
+                NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+prevention:
+  - "Maintain parallel secrets under both Actions and Dependabot secret stores for tokens Dependabot PRs need."
+  - "Audit workflows triggered by pull_request to identify steps using custom secrets — they silently fail for Dependabot."
+  - "Use github.actor != 'dependabot[bot]' guards on publish/deploy steps that Dependabot PRs should skip."
+docs:
+  - url: "https://docs.github.com/en/code-security/dependabot/working-with-dependabot/automating-dependabot-with-github-actions#accessing-secrets"
+    label: "GitHub Docs: Accessing secrets in Dependabot workflows"
+  - url: "https://docs.github.com/en/code-security/dependabot/working-with-dependabot/configuring-access-to-private-registries-for-dependabot"
+    label: "GitHub Docs: Dependabot and private registries"

package/errors/silent-failures/if-failure-not-triggered-on-cancellation.yml

@@ -0,0 +1,96 @@
+id: silent-failures-075
+title: "if: failure() notification job is skipped when workflow is manually cancelled"
+category: silent-failures
+severity: silent-failure
+tags:
+  - if-condition
+  - failure
+  - cancelled
+  - always
+  - notification
+  - cleanup
+patterns:
+  - regex: 'if:\s*failure\(\)'
+    flags: 'i'
+  - regex: 'Skipping.*cancelled'
+    flags: 'i'
+error_messages:
+  - "Skipping: The job was skipped because one or more of its needs jobs was cancelled."
+root_cause: |
+  When a workflow is manually cancelled (via the GitHub UI "Cancel run" button or
+  the REST API), in-progress jobs receive a cancellation signal. Jobs that have not
+  yet started are given the conclusion "cancelled". Jobs with if: failure() are
+  only evaluated against the "failure" conclusion — "cancelled" is a distinct
+  conclusion value. Because cancelled != failure, the condition evaluates to false
+  and the notification or cleanup job is silently skipped.
+
+  This catches teams by surprise when they add an alerting job intended to fire
+  whenever CI does not succeed:
+
+    notify-on-failure:
+      needs: build
+      if: failure()
+      runs-on: ubuntu-latest
+      steps:
+        - name: Send Slack alert
+          ...
+
+  When an operator cancels a run mid-flight, the build job is marked cancelled,
+  not failed. The notify job evaluates if: failure() → false and is skipped with
+  no Slack message. The on-call team receives no signal that a run was interrupted.
+
+  The failure() function returns true only when at least one needed job has a
+  "failure" conclusion. It does NOT return true for "cancelled" conclusions.
+fix: |
+  Use if: failure() || cancelled() to catch both failure and cancellation, or use
+  if: always() combined with a conditional check on the job's outcome inside the
+  step if you only want to act on non-success outcomes.
+fix_code:
+  - language: yaml
+    label: "Catch both failure and cancellation in a notification job"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: make build
+
+        notify-on-failure:
+          needs: build
+          # failure() catches job failures; cancelled() catches manual cancellation
+          if: failure() || cancelled()
+          runs-on: ubuntu-latest
+          steps:
+            - name: Send failure or cancellation alert
+              run: |
+                echo "Build concluded: ${{ needs.build.result }}"
+                # Send Slack/PagerDuty notification here
+  - language: yaml
+    label: "Use always() and gate on outcome inside the step for fine-grained control"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - run: make build
+
+        notify:
+          needs: build
+          if: always()
+          runs-on: ubuntu-latest
+          steps:
+            - name: Notify only on non-success outcomes
+              if: needs.build.result != 'success'
+              run: |
+                echo "Build result: ${{ needs.build.result }}"
+                # Handles: failure, cancelled, skipped
+prevention:
+  - "Use if: failure() || cancelled() instead of if: failure() for any alert, notification, or cleanup job that must run whenever CI does not succeed."
+  - "Prefer if: always() when the downstream job should run regardless of upstream outcome (e.g., always upload test reports)."
+  - "Audit all notification and cleanup jobs after cancellation to confirm they fired as expected — cancelled runs don't generate failure alerts by default."
+  - "The cancelled() function returns true when the workflow or job has been cancelled; combine with failure() using || for comprehensive coverage."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-conditions-to-control-job-execution"
+    label: "GitHub Actions: Using conditions to control job execution"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-conditions-to-control-job-execution#available-status-check-functions"
+    label: "GitHub Actions: Available status check functions — failure(), cancelled(), always()"

package/errors/triggers/workflow-dispatch-choice-input-api-no-validation.yml

@@ -0,0 +1,98 @@
+id: triggers-054
+title: "workflow_dispatch choice input not validated when triggered via REST API — invalid values silently accepted"
+category: triggers
+severity: silent-failure
+tags:
+  - workflow-dispatch
+  - choice-input
+  - rest-api
+  - inputs
+  - validation
+  - gh-cli
+patterns:
+  - regex: 'type:\s*choice'
+    flags: 'i'
+  - regex: 'inputs\.\w+.*choice'
+    flags: 'i'
+error_messages:
+  - "Workflow ran with input value not in declared choices list"
+root_cause: |
+  The type: choice input in on.workflow_dispatch.inputs renders a dropdown
+  selector in the GitHub Actions UI and prevents users from submitting values
+  outside the declared options list. This validation is enforced entirely
+  client-side in the browser.
+
+  When a workflow is triggered via the GitHub REST API
+  (POST /repos/{owner}/{repo}/actions/workflows/{id}/dispatches) or the GitHub
+  CLI (gh workflow run --field key=value), GitHub does NOT validate that the
+  supplied value matches any of the declared choices. Any arbitrary string is
+  accepted and forwarded as-is to the workflow.
+
+  A workflow dispatched with inputs: { environment: "PROD" } when the declared
+  choices are ["prod", "staging", "dev"] will run with inputs.environment == "PROD".
+  Every if: condition that compares against the lower-case variants evaluates to
+  false, all deployment branches are skipped, and the workflow exits successfully
+  with no indication that the value was invalid. The mistyped run is invisible
+  unless logs are inspected manually.
+fix: |
+  Add an explicit allowlist validation step at the top of the workflow that checks
+  the input value and exits with a non-zero status and a descriptive error message
+  if the value is not in the expected set. This makes API-triggered runs fail fast
+  with a clear error rather than silently no-oping.
+fix_code:
+  - language: yaml
+    label: "Validate choice input with an allowlist check"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              type: choice
+              description: Target deployment environment
+              options:
+                - prod
+                - staging
+                - dev
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Validate environment input
+              run: |
+                allowed="prod staging dev"
+                input="${{ inputs.environment }}"
+                if [[ ! " $allowed " =~ " ${input} " ]]; then
+                  echo "::error::Invalid environment '${input}'. Allowed values: $allowed"
+                  exit 1
+                fi
+
+            - name: Deploy to ${{ inputs.environment }}
+              run: echo "Deploying to ${{ inputs.environment }}"
+  - language: yaml
+    label: "Case-insensitive validation with normalisation"
+    code: |
+      - name: Validate and normalise environment input
+        id: validate
+        run: |
+          input=$(echo "${{ inputs.environment }}" | tr '[:upper:]' '[:lower:]')
+          allowed=("prod" "staging" "dev")
+          valid=false
+          for v in "${allowed[@]}"; do
+            [[ "$input" == "$v" ]] && valid=true && break
+          done
+          if [[ "$valid" != "true" ]]; then
+            echo "::error::Unrecognised environment '${{ inputs.environment }}' (normalised: '$input'). Allowed: ${allowed[*]}"
+            exit 1
+          fi
+          echo "environment=$input" >> "$GITHUB_OUTPUT"
+prevention:
+  - "Treat type: choice as a UI hint only — always validate inputs programmatically inside the workflow."
+  - "Add an allowlist guard as the first step of any job that branches on a choice input."
+  - "Document valid values and casing rules in the input description field so API callers know the expected format."
+  - "Use actionlint to detect misspelled choices at authoring time before they reach production."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch"
+    label: "GitHub Actions: workflow_dispatch event — inputs"
+  - url: "https://docs.github.com/en/rest/actions/workflows#create-a-workflow-dispatch-event"
+    label: "GitHub REST API: Create a workflow dispatch event"

package/errors/yaml-syntax/secrets-context-unavailable-in-if-condition.yml

@@ -0,0 +1,72 @@
+id: yaml-syntax-050
+title: "secrets context used in job/step if: condition rejected — only valid in env: and with: blocks"
+category: yaml-syntax
+severity: error
+tags:
+  - secrets
+  - if-condition
+  - expression-context
+  - actionlint
+  - context-availability
+patterns:
+  - regex: 'Unrecognized named-value: ''secrets'''
+    flags: i
+  - regex: 'Context access might be invalid: secrets'
+    flags: i
+error_messages:
+  - "Unrecognized named-value: 'secrets'. Located at position 1 within expression"
+  - "Context access might be invalid: secrets"
+root_cause: |
+  The secrets context is only available inside env: blocks and action input with: blocks.
+  It cannot be used in if: conditions at the job or step level.
+
+  A common pattern is to conditionally run a deployment step only when a secret is
+  configured: if: secrets.DEPLOY_TOKEN != ''. GitHub's expression evaluator rejects
+  this at runtime with "Unrecognized named-value: 'secrets'", failing the step or job
+  before it even starts. actionlint reports this as a static analysis error under
+  "Context access might be invalid: secrets".
+
+  The restriction is documented in GitHub's context availability table: the secrets
+  context is listed as unavailable for job.<job_id>.if and steps.<step_id>.if.
+fix: |
+  Map the secret to an environment variable in an env: block, then check the
+  environment variable in the if: condition using the env context. For a job-level
+  gate, set the env var at the job level and reference it in a step if: condition.
+fix_code:
+  - language: yaml
+    label: "Bridge secret through env var for step-level if:"
+    code: |
+      # WRONG: secrets context not available in if: conditions
+      # - name: Deploy
+      #   if: secrets.DEPLOY_TOKEN != ''
+      #   run: ./deploy.sh
+
+      # CORRECT: map secret to env var, check env var in if:
+      - name: Deploy
+        if: env.DEPLOY_TOKEN != ''
+        env:
+          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
+        run: ./deploy.sh
+
+  - language: yaml
+    label: "Job-level env gate evaluated in step if:"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          env:
+            # Set at job level so all steps can reference it
+            DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
+          steps:
+            - name: Deploy
+              if: env.DEPLOY_TOKEN != ''
+              run: ./deploy.sh
+prevention:
+  - "Never reference secrets.* in if: conditions — always bridge through an env: variable first."
+  - "Run actionlint in CI to catch 'Context access might be invalid: secrets' errors before they reach production."
+  - "Consider using a boolean repository variable (vars.DEPLOY_ENABLED) as a conditional gate rather than checking secret presence."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#context-availability"
+    label: "GitHub Actions: Context availability"
+  - url: "https://rhysd.github.io/actionlint/checks.html#check-contexts-and-special-functions"
+    label: "actionlint: Context availability checks"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htekdev/actions-debugger",
-  "version": "1.0.79",
+  "version": "1.0.81",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",