@htekdev/actions-debugger 1.0.78 → 1.0.80

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/merge-queue-branch-cache-isolation.yml

@@ -0,0 +1,80 @@
+id: caching-artifacts-045
+title: "Merge queue (merge_group) runs cannot restore cache saved by pull_request runs"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - merge-queue
+  - merge_group
+  - cache-isolation
+  - branch-scoping
+  - cache-miss
+patterns:
+  - regex: 'Cache not found for input keys'
+    flags: i
+  - regex: 'gh-readonly-queue'
+    flags: i
+error_messages:
+  - "Cache not found for input keys:"
+  - "No cache found for key: Linux-node-"
+root_cause: |
+  GitHub Actions caches are branch-scoped. When the merge_group trigger fires,
+  GitHub creates a temporary branch named
+  gh-readonly-queue/main/pr-<number>-<sha> with a fresh merge commit. This
+  temporary branch has no prior cache entries, so every cache lookup is a cache
+  miss — even if the identical hashFiles() key was successfully saved during the
+  preceding pull_request run on the feature branch.
+
+  Branch-scoped cache fallback rules allow access to the base branch (e.g., main)
+  but NOT to arbitrary feature branches. The gh-readonly-queue/* branch is treated
+  as a new branch with no cache history and no access to feature-branch caches.
+  Only caches saved directly to main (or the configured merge target) are accessible
+  in merge queue runs.
+
+  The result: CI times effectively double. The pull_request run warms the cache
+  but the merge queue run cannot use it and must rebuild from scratch.
+fix: |
+  Seed caches on the base branch via push-triggered or scheduled workflows so
+  merge queue runs can restore from main's cache. Use restore-keys with a
+  branch-agnostic prefix to maximize fallback hit rate.
+fix_code:
+  - language: yaml
+    label: "Use restore-keys for base branch fallback"
+    code: |
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          # Exact key includes lock file hash — works for push/PR
+          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+          # restore-keys fall back to base branch cache (accessible in merge_group)
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+  - language: yaml
+    label: "Seed base branch cache via push workflow"
+    code: |
+      # Separate workflow to warm cache on main after every merge
+      on:
+        push:
+          branches: [main]
+
+      jobs:
+        warm-cache:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: '20'
+                cache: npm
+            - run: npm ci
+prevention:
+  - "Seed caches on your base branch (main) so merge queue runs can restore from it."
+  - "Use branch-agnostic restore-keys prefixes — they survive the gh-readonly-queue/* branch context."
+  - "Avoid cache keys that include branch name or github.head_ref — they will never match in merge queue."
+  - "setup-node/setup-python cache: integration automatically includes restore-keys and handles this gracefully."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#merge_group"
+    label: "GitHub Actions: merge_group trigger"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache"
+    label: "GitHub Actions: Cache branch access restrictions"

package/errors/concurrency-timing/rerun-cancel-original-missing-run-attempt.yml

@@ -0,0 +1,67 @@
+id: concurrency-timing-039
+title: "Manual re-run cancels original run when concurrency group omits github.run_attempt"
+category: concurrency-timing
+severity: error
+tags:
+  - concurrency
+  - re-run
+  - cancel-in-progress
+  - run-attempt
+  - manual-rerun
+patterns:
+  - regex: 'This run was cancelled'
+    flags: i
+  - regex: 'run_attempt'
+    flags: i
+error_messages:
+  - "This run was cancelled."
+  - "A run for this workflow is already in progress."
+root_cause: |
+  When cancel-in-progress: true is set and the concurrency group key does not
+  include github.run_attempt, every manual re-run of a workflow is treated as a
+  duplicate of the original run (since run_id and ref are the same). The re-run
+  immediately cancels the still-executing original attempt, or the concurrency
+  group queues the re-run and cancels any pending run — which may be the active
+  original.
+
+  The run_id is stable across re-runs but run_attempt increments (1, 2, 3...).
+  Without run_attempt in the concurrency group key, GitHub has no way to
+  distinguish re-run attempt 2 from the still-running attempt 1.
+
+  This produces confusing CI failures: a developer clicks "Re-run jobs" on a
+  failed workflow and immediately sees the original (or the re-run itself)
+  cancelled by the concurrency system.
+fix: |
+  Include github.run_attempt in the concurrency group key so each attempt is
+  treated as a distinct slot. This allows re-runs to coexist with or cleanly
+  supersede the original without unexpected cancellations.
+fix_code:
+  - language: yaml
+    label: "Include run_attempt in concurrency group key"
+    code: |
+      # WRONG: re-runs and originals share the same concurrency slot
+      # concurrency:
+      #   group: ${{ github.workflow }}-${{ github.ref }}
+      #   cancel-in-progress: true
+
+      # CORRECT: each attempt gets its own slot, preventing cross-attempt cancellation
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}-${{ github.run_attempt }}
+        cancel-in-progress: true
+
+  - language: yaml
+    label: "Alternative: cancel-in-progress only for push/PR, not re-runs"
+    code: |
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        # Only cancel-in-progress for first attempt; re-runs are never cancelled
+        cancel-in-progress: ${{ github.run_attempt == 1 }}
+prevention:
+  - "Always include github.run_attempt in concurrency group keys when cancel-in-progress: true is set."
+  - "Test re-run behavior explicitly — concurrency cancellation bugs only surface when you manually re-run."
+  - "Consider using cancel-in-progress: ${{ github.run_attempt == 1 }} to preserve re-run integrity."
+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-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#github-context"
+    label: "GitHub Actions: github.run_attempt context"

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/fromjson-object-stored-in-env-stringifies.yml

@@ -0,0 +1,77 @@
+id: silent-failures-074
+title: "fromJSON() object or array stored in env: block silently becomes '[object Object]'"
+category: silent-failures
+severity: silent-failure
+tags:
+  - fromjson
+  - env-context
+  - type-coercion
+  - json-parsing
+  - stringification
+patterns:
+  - regex: 'env\s*:.*\$\{\{\s*fromJSON\('
+    flags: ims
+error_messages:
+  - "[object Object]"
+  - "Unexpected token 'o', \"[object O\"... is not valid JSON"
+root_cause: |
+  The fromJSON() function in GitHub Actions expressions parses a JSON string
+  into a typed value — object, array, boolean, or number. However, when the
+  result is assigned to an env: variable, the Actions runner coerces the value
+  to a string using JavaScript's default toString(). For objects this produces
+  the literal string [object Object]; for arrays it produces a comma-joined
+  string (e.g., a,b,c).
+
+  The step exits with code 0 and the env variable appears set, but its value is
+  the stringified form rather than the JSON structure the developer expected.
+  Subsequent steps that reference ${{ env.CONFIG }} or echo the variable and
+  pipe it through jq will receive [object Object] and fail to parse — or silently
+  produce wrong results.
+
+  Booleans and numbers survive correctly: fromJSON('true') in env: produces the
+  string 'true', and fromJSON('42') produces '42' — these are the only safe uses.
+fix: |
+  Pass structured JSON data between steps via GITHUB_OUTPUT (as a raw JSON
+  string), then consume the stored string with fromJSON() in downstream
+  expression contexts. Never store objects or arrays via fromJSON() in env: blocks.
+fix_code:
+  - language: yaml
+    label: "Store JSON in GITHUB_OUTPUT, consume via fromJSON in expressions"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            # WRONG: fromJSON object in env: becomes '[object Object]'
+            # - name: Bad config
+            #   env:
+            #     CONFIG: ${{ fromJSON(inputs.config_json) }}
+            #   run: echo "$CONFIG" | jq .host  # fails: '[object Object]' is not JSON
+
+            # CORRECT: store raw JSON string in GITHUB_OUTPUT
+            - name: Store config
+              id: cfg
+              run: echo 'config=${{ inputs.config_json }}' >> $GITHUB_OUTPUT
+
+            # Access fields with fromJSON() directly in expression context
+            - name: Use config
+              run: |
+                echo "Host: ${{ fromJSON(steps.cfg.outputs.config).host }}"
+                echo "Port: ${{ fromJSON(steps.cfg.outputs.config).port }}"
+
+            # Scalar fromJSON values are safe in env: (boolean, number)
+            - name: Scalar fromJSON is fine
+              env:
+                IS_PROD: ${{ fromJSON(inputs.is_prod) }}
+                TIMEOUT: ${{ fromJSON(inputs.timeout) }}
+              run: echo "prod=$IS_PROD timeout=$TIMEOUT"
+prevention:
+  - "Never assign fromJSON() results that produce objects or arrays to env: variables."
+  - "Use fromJSON() inline in expression contexts (${{ fromJSON(x).field }}) rather than materializing into env vars."
+  - "Store JSON blobs as raw strings in GITHUB_OUTPUT and parse with jq in shell or fromJSON() in expressions."
+  - "For object env vars, keep the value as a raw JSON string and parse in shell with jq or python -c."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#fromjson"
+    label: "GitHub Actions: fromJSON expression function"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs"
+    label: "GitHub Actions: Passing information between jobs"

package/errors/triggers/event-types-unknown-value-silently-ignored.yml

@@ -0,0 +1,89 @@
+id: triggers-053
+title: "Unknown or misspelled values in on.<event>.types[] are silently ignored — workflow never triggers"
+category: triggers
+severity: silent-failure
+tags:
+  - types-filter
+  - trigger
+  - typo
+  - pull-request
+  - silent-failure
+patterns:
+  - regex: 'types\s*:\s*\[.*(?:syncronize|synchronised|synchronize d|re-opened|labeld|assign)\]'
+    flags: i
+  - regex: 'types\s*:\s*\n(?:\s+-\s+\w+\n)*\s+-\s+(?!opened|closed|reopened|synchronize|labeled|unlabeled|assigned|unassigned|review_requested|ready_for_review|converted_to_draft|locked|unlocked|milestoned|demilestoned|edited)\w'
+    flags: im
+error_messages:
+  - "Workflow is not triggered"
+  - "No runs found"
+root_cause: |
+  GitHub Actions silently discards unrecognized values in the types: filter
+  array for pull_request, pull_request_target, and other typed events. There is
+  no validation error, no schema warning, and no run log entry — the workflow
+  simply never fires for the intended activity type.
+
+  The most common cause is a typo in a well-known type name:
+    - syncronize  (correct: synchronize)
+    - re-opened   (correct: reopened)
+    - labeld      (correct: labeled)
+    - closed      (correct: closed — note: not 'merged')
+
+  A second common cause is listing only the new type while forgetting that the
+  default types are no longer active. For example, types: [synchronize] drops
+  the implicit opened and reopened behaviors, so a newly opened PR will not
+  trigger CI at all.
+
+  actionlint >=0.7.0 can detect unknown type values but is not always used in
+  local development workflows.
+fix: |
+  Verify all type values against the official list for each event. Include all
+  intended types explicitly — once types: is specified, the defaults no longer
+  apply.
+fix_code:
+  - language: yaml
+    label: "Correct types for pull_request CI — always include all intended types"
+    code: |
+      on:
+        pull_request:
+          # WRONG examples (silently never trigger):
+          # types: [opened, syncronize, re-opened]   # typos
+          # types: [synchronize]                     # drops opened/reopened
+
+          # CORRECT: include all intended activity types
+          types:
+            - opened
+            - synchronize
+            - reopened
+
+  - language: yaml
+    label: "All valid pull_request types for reference"
+    code: |
+      on:
+        pull_request:
+          types:
+            # Commonly needed for CI:
+            - opened          # new PR created
+            - synchronize     # new commit pushed to PR branch
+            - reopened        # closed PR re-opened
+            # Useful for label-gated workflows:
+            - labeled
+            - unlabeled
+            # Draft/review flow:
+            - ready_for_review
+            - converted_to_draft
+            # Assignment:
+            - assigned
+            - unassigned
+            - review_requested
+prevention:
+  - "Run actionlint (>=0.7.0) in CI to detect unknown type values — it reports them as errors."
+  - "When adding types:, explicitly list ALL types you need — defaults no longer apply once types: is present."
+  - "After changing types:, trigger one manual test run per type to confirm the filter is working."
+  - "Use the GitHub Actions VS Code extension — it underlines unknown type values as warnings."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request"
+    label: "GitHub Actions: pull_request event types"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_target"
+    label: "GitHub Actions: pull_request_target event types"
+  - url: "https://rhysd.github.io/actionlint/"
+    label: "actionlint: GitHub Actions linter"

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.78",
+  "version": "1.0.80",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",