@htekdev/actions-debugger 1.0.51 → 1.0.53

package/errors/caching-artifacts/caching-artifacts-036.yml

@@ -0,0 +1,155 @@
+id: caching-artifacts-036
+title: 'actions/cache post step skips save when job is cancelled — cache never populated after cancellation'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - actions-cache
+  - job-cancellation
+  - post-step
+  - cache-save
+  - cancel-in-progress
+  - concurrency
+  - always
+patterns:
+  - regex: 'Post\s+Run\s+actions/cache.*skipped|Cache\s+save\s+skipped'
+    flags: 'i'
+  - regex: 'uses:\s*actions/cache@'
+    flags: 'i'
+error_messages:
+  - 'Post Run actions/cache@v4 skipped'
+  - 'Cache save skipped'
+  - '##[warning]Cache save skipped.'
+  - 'Warning: Cache save failed.'
+root_cause: |
+  The actions/cache action saves the cache in a lifecycle "post" step that runs
+  automatically after the main job steps complete. When a job is cancelled — via
+  the Actions UI, concurrency cancel-in-progress, or exceeding job timeout-minutes
+  — post steps do NOT execute.
+
+  This creates a cache starvation loop:
+  1. Job starts with cache miss — slow dependency installation begins (minutes)
+  2. A new push triggers another workflow run while the first is still installing
+  3. concurrency: cancel-in-progress terminates the first run mid-install
+  4. The first run never reaches its post step — cache is not saved
+  5. The second run also sees a cache miss — the same slow install repeats
+  6. Repeated cancellations mean the cache is never populated
+
+  This is invisible in workflow logs: cancelled jobs simply show as cancelled with
+  no specific warning about the cache post step being skipped. Teams diagnose it
+  as "caching isn't working" without realizing cancellation is the root cause.
+
+  Affected workflows:
+  - Any workflow with concurrency: cancel-in-progress that also uses actions/cache
+  - Workflows with aggressive job timeout-minutes that expire during installs
+  - Flaky workflows that are frequently manually cancelled and re-run
+  - Matrix workflows where one failing matrix branch cancels siblings
+
+  When a job fails (but is not cancelled), post steps DO run normally — the issue
+  is specific to cancellations and hard timeouts.
+fix: |
+  Use the split actions/cache/restore + actions/cache/save pattern with
+  if: always() on the save step. This gives explicit control over cache saving
+  independent of the job lifecycle hooks:
+
+    - uses: actions/cache/restore@v4
+      id: cache-restore
+      with:
+        key: ...
+        path: ...
+
+    # ... install and build steps ...
+
+    - uses: actions/cache/save@v4
+      if: always()
+      with:
+        key: ${{ steps.cache-restore.outputs.cache-primary-key }}
+        path: ...
+
+  The split restore/save pattern (available since actions/cache v3.3.0 in 2023)
+  runs the save as an explicit step with if: always(), which executes during the
+  graceful shutdown window even when the job is being cancelled.
+
+  Important caveat: if the runner process is killed with SIGKILL (hard preemption,
+  host failure), no steps including if: always() will run — this is a
+  platform-level constraint outside GitHub Actions' control.
+fix_code:
+  - language: yaml
+    label: 'Split restore/save pattern with unconditional save to survive cancellation'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          # Even with cancel-in-progress, the explicit save step will run
+          concurrency:
+            group: ${{ github.workflow }}-${{ github.ref }}
+            cancel-in-progress: true
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Restore cached dependencies
+              uses: actions/cache/restore@v4
+              id: cache-restore
+              with:
+                path: ~/.npm
+                key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+                restore-keys: |
+                  ${{ runner.os }}-npm-
+
+            - name: Install dependencies
+              if: steps.cache-restore.outputs.cache-hit != 'true'
+              run: npm ci
+
+            - name: Run tests
+              run: npm test
+
+            - name: Save cache
+              uses: actions/cache/save@v4
+              if: always()   # Runs during graceful cancellation shutdown window
+              with:
+                path: ~/.npm
+                key: ${{ steps.cache-restore.outputs.cache-primary-key }}
+
+  - language: yaml
+    label: 'Python pip cache with split save pattern'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Restore pip cache
+              uses: actions/cache/restore@v4
+              id: pip-cache
+              with:
+                path: ~/.cache/pip
+                key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements*.txt') }}
+                restore-keys: |
+                  ${{ runner.os }}-pip-
+
+            - name: Install Python dependencies
+              run: pip install -r requirements.txt
+
+            - name: Run pytest
+              run: pytest
+
+            - name: Save pip cache
+              uses: actions/cache/save@v4
+              if: always()
+              with:
+                path: ~/.cache/pip
+                key: ${{ steps.pip-cache.outputs.cache-primary-key }}
+prevention:
+  - 'Prefer the split actions/cache/restore + actions/cache/save pattern over the combined actions/cache action for any workflow using concurrency: cancel-in-progress'
+  - 'Always add if: always() to explicit cache save steps so they execute regardless of upstream step failure or cancellation signal'
+  - 'Monitor workflow logs for "Post Run actions/cache skipped" messages — this is a reliable indicator that cache is never being populated after cancellations'
+  - 'Use actions/cache v3.3.0 or later — the split restore/save subactions were introduced in that release'
+docs:
+  - url: 'https://github.com/actions/cache/blob/main/save/README.md'
+    label: 'actions/cache: Explicit save action documentation'
+  - url: 'https://github.com/actions/cache#save-action'
+    label: 'actions/cache: Split restore and save usage pattern'
+  - url: 'https://github.com/orgs/community/discussions/47469'
+    label: 'GitHub Community #47469: Cache not saved when workflow is cancelled'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-syntax-for-github-actions#jobsjob_idstepsif'
+    label: 'GitHub Docs: Using conditions to control job execution'

package/errors/concurrency-timing/concurrency-timing-030.yml

@@ -0,0 +1,102 @@
+id: concurrency-timing-030
+title: 'github.sha concurrency group key makes every run unique — cancel-in-progress never fires'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - cancel-in-progress
+  - github-sha
+  - unique-key
+  - workflow-cancellation
+  - silent-failure
+patterns:
+  - regex: 'group:\s*.*\$\{\{[^}]*github\.sha[^}]*\}\}'
+    flags: 'i'
+  - regex: 'cancel-in-progress:\s*true'
+    flags: 'i'
+error_messages:
+  - 'Old workflow runs are not being cancelled despite cancel-in-progress: true'
+  - 'All workflow runs queue independently instead of cancelling previous runs'
+  - 'Concurrent workflows are running in parallel when they should be cancelled'
+root_cause: |
+  github.sha is unique per commit. When used as (any part of) the concurrency group
+  key, every workflow run gets a different group name. Because no two runs ever share
+  the same group, the cancel-in-progress mechanism has nothing to act on — all runs
+  proceed independently and simultaneously.
+
+  This is the inverse of the intended behavior. Developers add ${{ github.sha }}
+  thinking "this will identify runs for the same commit and cancel old ones," but
+  since each commit produces a unique SHA, each run is placed in its own group with
+  no overlap. The result is effectively no concurrency control at all.
+
+  Common mistake patterns:
+    group: ${{ github.workflow }}-${{ github.sha }}        # unique per commit — never cancels
+    group: ${{ github.ref }}-${{ github.sha }}             # unique per commit — never cancels
+    group: deploy-${{ github.sha }}                        # unique per commit — never cancels
+
+  The correct key for "cancel older runs on the same branch" is a value that stays
+  constant across pushes to the same branch — github.ref, github.head_ref (for PRs),
+  or a composite like github.workflow-github.ref.
+
+  Source: Frequently reported on Stack Overflow [github-actions] tag and GitHub
+  Community discussions. GitHub Docs concurrency examples explicitly use github.ref,
+  not github.sha.
+fix: |
+  Replace github.sha with github.ref (or github.head_ref for pull request workflows)
+  in the concurrency group key. Use a composite that stays constant for all pushes
+  to the same branch:
+
+  - For branch workflows: ${{ github.workflow }}-${{ github.ref }}
+  - For PR workflows:     ${{ github.workflow }}-${{ github.head_ref }}
+  - For global uniqueness: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}
+
+  Only use github.sha in the group key when you explicitly want every run to be
+  isolated (e.g., no cancellation ever — but then cancel-in-progress: true is meaningless).
+fix_code:
+  - language: yaml
+    label: 'Wrong: github.sha makes every run unique — cancel-in-progress never fires'
+    code: |
+      # WRONG: every push creates a new unique group — nothing is ever cancelled
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.sha }}
+        cancel-in-progress: true   # dead code — no prior run shares this group
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+  - language: yaml
+    label: 'Correct: github.ref stays constant per branch — prior runs are cancelled'
+    code: |
+      # CORRECT: all pushes to the same branch share one group
+      # cancel-in-progress: true cancels any in-flight run when a new push arrives
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+  - language: yaml
+    label: 'PR-specific: use github.head_ref to scope to the PR branch'
+    code: |
+      # For pull_request workflows, head_ref is the PR branch name (stable per PR)
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+        cancel-in-progress: true
+prevention:
+  - 'Never use github.sha in a concurrency group key when the goal is to cancel old runs — it makes every run unique'
+  - 'For branch-scoped cancellation use github.ref; for PR-scoped cancellation use github.head_ref'
+  - 'If cancel-in-progress: true is set, verify the group key stays constant across multiple pushes to the same branch'
+  - 'Use actionlint to catch unreachable concurrency group patterns'
+  - 'Read the GitHub Docs concurrency examples — they all use github.ref, not github.sha'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs'
+    label: 'GitHub Docs: Controlling concurrency of workflows and jobs'
+  - url: 'https://stackoverflow.com/questions/66335225/how-to-cancel-previous-runs-in-the-pr-when-you-push-new-commitschanges'
+    label: 'Stack Overflow: How to cancel previous runs when you push new commits'

package/errors/concurrency-timing/concurrency-timing-031.yml

@@ -0,0 +1,102 @@
+id: concurrency-timing-031
+title: 'cancel-in-progress: false does not create a FIFO queue — only one run can be pending'
+category: concurrency-timing
+severity: warning
+tags:
+  - concurrency
+  - cancel-in-progress
+  - queue
+  - pending-run
+  - fifo
+  - workflow-queuing
+patterns:
+  - regex: 'cancel-in-progress:\s*false'
+    flags: 'i'
+error_messages:
+  - 'Queued workflow run was cancelled unexpectedly even though cancel-in-progress is false'
+  - 'Expected runs to queue up but intermediate runs are being dropped'
+  - 'Second queued run cancelled when a third run was triggered'
+root_cause: |
+  When cancel-in-progress: false is set, many developers expect GitHub Actions to
+  maintain a FIFO queue of pending runs: Run 1 active → Run 2 queued → Run 3 waits
+  behind Run 2. This is not how it works.
+
+  GitHub Actions maintains at most ONE pending (queued) run per concurrency group.
+  The behavior with cancel-in-progress: false is:
+
+  1. Run 1: active (running)
+  2. Run 2 arrives: Run 2 enters pending state
+  3. Run 3 arrives: Run 2 is CANCELLED, Run 3 becomes the new pending run
+  4. Run 1 completes: Run 3 (latest) starts — Run 2 was silently dropped
+
+  This means: with three or more rapid commits, only the first (currently running)
+  and the last (most recently pushed) will ever execute. All intermediate runs are
+  cancelled and lost — even though cancel-in-progress is explicitly false.
+
+  This behavior is documented in GitHub Docs ("only the latest queued run will
+  start") but is widely misunderstood. The cancel-in-progress: false setting only
+  prevents cancelling the ACTIVE run — it does not prevent intermediate pending
+  runs from being replaced by newer ones.
+
+  Source: GitHub Docs concurrency documentation. Discussed in GitHub Community
+  discussions and multiple Stack Overflow questions about "runs being unexpectedly
+  cancelled with cancel-in-progress: false".
+fix: |
+  There is no built-in FIFO queue in GitHub Actions concurrency. To process every
+  run without dropping intermediates:
+
+  1. For pull requests: use GitHub's merge queue — it processes PRs sequentially
+  2. For deployments: use a separate queuing action (e.g., softprops/turnstyle) to
+     serialize runs without skipping intermediates
+  3. For simple "don't cancel active, run latest after": accept that cancel-in-progress:
+     false means intermediates are dropped and design accordingly
+  4. If every commit must be processed: remove the concurrency block entirely and
+     accept parallel runs, or implement idempotent jobs that can run concurrently
+fix_code:
+  - language: yaml
+    label: 'Misunderstood: cancel-in-progress: false does NOT queue all runs'
+    code: |
+      # MISUNDERSTOOD: developers expect runs 1, 2, 3 to all execute sequentially
+      # ACTUAL behavior: run 2 is cancelled when run 3 arrives
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: false   # protects ACTIVE run only; pending run is replaced
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "Deploying..."
+
+  - language: yaml
+    label: 'Explicit: accept one-pending semantics and design for idempotent jobs'
+    code: |
+      # If intermediate commits can be skipped (e.g., deploy only latest):
+      # cancel-in-progress: false ensures the active deploy finishes, then
+      # only the LATEST pending commit deploys next (intermediates dropped)
+      concurrency:
+        group: deploy-${{ github.ref }}
+        cancel-in-progress: false
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Deploy latest commit
+              run: |
+                echo "Deploying ${{ github.sha }}"
+                # Idempotent: deploying latest SHA is always safe
+prevention:
+  - 'Understand that cancel-in-progress: false only protects the active run — the pending slot still holds at most one run'
+  - 'Do not rely on concurrency groups for FIFO queuing — they are a deduplication mechanism, not a queue'
+  - 'For sequential processing of every commit, use merge queues or external serialization tooling'
+  - 'If every commit must be processed, either remove the concurrency block or use an event-based queue (e.g., repository_dispatch)'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs'
+    label: 'GitHub Docs: Controlling concurrency of workflows and jobs'
+  - url: 'https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue'
+    label: 'GitHub Docs: Managing a merge queue'
+  - url: 'https://github.com/softprops/turnstyle'
+    label: 'softprops/turnstyle: Wait for in-progress workflows'

package/errors/concurrency-timing/concurrency-timing-032.yml

@@ -0,0 +1,147 @@
+id: concurrency-timing-032
+title: 'Reusable workflow concurrency: is not inherited from caller — parallel instances can run simultaneously'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - reusable-workflow
+  - workflow-call
+  - parallel-runs
+  - concurrency-inheritance
+  - deployment
+patterns:
+  - regex: 'jobs\.\w+\.uses:\s*'
+    flags: 'i'
+  - regex: '^concurrency:'
+    flags: 'im'
+error_messages:
+  - 'Multiple simultaneous deployments triggered despite concurrency group on caller workflow'
+  - 'Reusable workflow running in parallel when caller has cancel-in-progress: true'
+  - 'Concurrency group on calling workflow does not prevent parallel reusable workflow runs'
+root_cause: |
+  When a workflow defines concurrency: at the workflow level and calls a reusable
+  workflow via jobs.<id>.uses:, the concurrency configuration is NOT propagated
+  to the called (callee) workflow. The reusable workflow runs with its own
+  independent concurrency context.
+
+  This means:
+  - Workflow A has concurrency: group: deploy-${{ github.ref }}
+  - Workflow A calls Reusable-Deploy.yml via jobs.deploy.uses
+  - If two branches both trigger Workflow A simultaneously, each instance of Workflow A
+    serializes itself via its own concurrency group — but both instances of
+    Reusable-Deploy.yml run in parallel with no concurrency restriction
+
+  The concurrency group defined in the CALLER protects the caller's run from
+  duplicate callers on the same ref. It does NOT create any concurrency group for
+  the callee. The callee executes as a distinct workflow run with no inherited
+  concurrency settings.
+
+  This is especially problematic for shared deployment reusable workflows:
+  - Multiple repos or branches can call the same reusable deployment workflow
+  - Each caller serializes itself per its own ref, but the shared callee runs
+    multiple parallel instances simultaneously
+  - Parallel deploys to the same environment proceed without conflict detection
+
+  Source: GitHub Docs explicitly states concurrency groups are scoped to the
+  specific workflow run. GitHub Community confirmed expected behavior in multiple
+  discussions about parallel reusable workflow instances.
+fix: |
+  Define concurrency: inside the reusable workflow itself, or accept a
+  concurrency-key input and use it within the callee:
+
+  Option 1 — Static group in reusable workflow:
+    Add concurrency: group: deploy-reusable to the callee workflow. This serializes
+    ALL calls to that reusable workflow globally.
+
+  Option 2 — Dynamic group via input:
+    Add a concurrency-key input to the reusable workflow. The caller passes
+    its own group key. The callee uses it: group: ${{ inputs.concurrency_key }}.
+    This gives callers control over which callee instances serialize against each other.
+
+  Option 3 — Environment-level protection:
+    Use GitHub deployment environments with required reviewers. Only one deployment
+    to an environment can be in progress at a time (pending review blocks others).
+fix_code:
+  - language: yaml
+    label: 'Caller: concurrency here only protects the caller — not the callee'
+    code: |
+      # caller-workflow.yml
+      # This concurrency group only prevents duplicate CALLERS for the same ref.
+      # It does NOT propagate to the reusable workflow.
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        deploy:
+          uses: ./.github/workflows/reusable-deploy.yml
+          with:
+            environment: production
+          secrets: inherit
+
+  - language: yaml
+    label: 'Fix option 1: define concurrency inside the reusable workflow'
+    code: |
+      # reusable-deploy.yml
+      on:
+        workflow_call:
+          inputs:
+            environment:
+              type: string
+              required: true
+
+      # Add concurrency here to serialize all calls to this reusable workflow
+      concurrency:
+        group: reusable-deploy-${{ inputs.environment }}
+        cancel-in-progress: false   # let active deploy finish; queue latest
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          environment: ${{ inputs.environment }}
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "Deploying to ${{ inputs.environment }}"
+
+  - language: yaml
+    label: 'Fix option 2: caller passes concurrency key as input'
+    code: |
+      # reusable-deploy.yml — accepts caller-controlled concurrency key
+      on:
+        workflow_call:
+          inputs:
+            concurrency_key:
+              type: string
+              required: false
+              default: 'reusable-deploy'
+
+      concurrency:
+        group: ${{ inputs.concurrency_key }}
+        cancel-in-progress: false
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "Deploying..."
+
+      ---
+      # caller-workflow.yml — passes its own ref as the key
+      jobs:
+        deploy:
+          uses: ./.github/workflows/reusable-deploy.yml
+          with:
+            concurrency_key: deploy-${{ github.ref }}
+prevention:
+  - 'Never assume the caller''s concurrency: group propagates to called reusable workflows — it does not'
+  - 'Define concurrency: inside every reusable workflow that manages shared resources (deployments, releases, package publishes)'
+  - 'Use deployment environments with required reviewers as an additional serialization layer for production deploys'
+  - 'Test reusable workflows by triggering two parallel calls and verifying only one runs at a time'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/control-the-concurrency-of-workflows-and-jobs'
+    label: 'GitHub Docs: Controlling concurrency of workflows and jobs'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows'
+    label: 'GitHub Docs: Reusing workflows'
+  - url: 'https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment'
+    label: 'GitHub Docs: Managing environments for deployment'

package/errors/permissions-auth/permissions-auth-038.yml

@@ -0,0 +1,148 @@
+id: permissions-auth-038
+title: 'secrets: inherit does not propagate environment-scoped secrets to reusable workflows'
+category: permissions-auth
+severity: silent-failure
+tags:
+  - secrets-inherit
+  - reusable-workflows
+  - environment-secrets
+  - workflow-call
+  - empty-secret
+  - deployment-environment
+patterns:
+  - regex: 'secrets:\s*inherit'
+    flags: 'i'
+  - regex: 'uses:\s*[./\w@-]+\.ya?ml\b'
+    flags: 'i'
+error_messages:
+  - 'Error: Input required and not supplied'
+  - 'Secret value is empty in reusable workflow'
+  - '##[error]The secret variable name is invalid'
+root_cause: |
+  When a caller workflow uses secrets: inherit to call a reusable workflow
+  (on.workflow_call), GitHub passes repository-level and organization-level
+  secrets to the called workflow. However, environment-scoped secrets are NOT
+  inherited — they arrive as empty strings with no error or warning.
+
+  Environment secrets are tied to a named deployment environment (e.g.,
+  "production", "staging") and are only accessible to jobs that declare
+  environment: <name> in their configuration. The secrets: inherit mechanism
+  operates at the repository/org secret scope level. It cannot bridge environment
+  context to a called workflow's jobs because those jobs run in a separate
+  workflow execution context and do not inherit the caller job's environment
+  declaration.
+
+  Failure scenario:
+  1. Caller job declares environment: production (activates env secrets in the caller)
+  2. Caller job uses secrets: inherit to call ./reusable.yml
+  3. Reusable workflow job reads secrets.PROD_DB_PASSWORD (an environment secret)
+  4. Reusable workflow job sees PROD_DB_PASSWORD as empty string
+  5. No error is thrown — the secret silently resolves to ""
+
+  This is documented as a GitHub platform limitation in the reusable workflows
+  documentation. GitHub Community discussion #26671 has many reports of this
+  surprising behavior.
+
+  Distinction from permissions-auth-037 (environment-secrets-job-scope):
+  - permissions-auth-037 covers jobs in the SAME workflow that lack environment:
+    declarations failing to access environment secrets.
+  - This entry covers the cross-workflow boundary where secrets: inherit does not
+    transfer environment secrets from caller to called workflow at all.
+fix: |
+  Explicitly declare and map environment secrets at the workflow_call boundary.
+  In the reusable workflow, declare each secret in the on.workflow_call.secrets
+  block. At the call site, explicitly pass each environment secret using the
+  secrets: mapping block (not secrets: inherit):
+
+  In the reusable workflow (workflow_call trigger):
+    on:
+      workflow_call:
+        secrets:
+          db_password:
+            required: true
+          api_key:
+            required: false
+
+  In the calling workflow:
+    jobs:
+      deploy:
+        environment: production
+        uses: ./.github/workflows/deploy.yml
+        secrets:
+          db_password: ${{ secrets.PROD_DB_PASSWORD }}
+          api_key: ${{ secrets.PROD_API_KEY }}
+
+  Alternatively, if the reusable workflow is in the same repository and the
+  environment name is fixed, you can declare environment: production on the job
+  inside the reusable workflow directly. This makes environment secrets accessible
+  in the called workflow at the cost of coupling it to a specific environment name.
+
+  Note: secrets: inherit and explicit secrets: mapping cannot be combined on the
+  same uses: step. Choose one approach: either inherit all repo/org secrets, or
+  map explicitly (which also allows passing environment secrets).
+fix_code:
+  - language: yaml
+    label: 'Reusable workflow — declare required secrets in workflow_call trigger'
+    code: |
+      # .github/workflows/deploy-reusable.yml
+      on:
+        workflow_call:
+          secrets:
+            db_password:
+              required: true
+            api_key:
+              required: true
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy application
+              env:
+                DB_PASSWORD: ${{ secrets.db_password }}
+                API_KEY: ${{ secrets.api_key }}
+              run: ./scripts/deploy.sh
+
+  - language: yaml
+    label: 'Caller workflow — explicitly map environment secrets (not secrets: inherit)'
+    code: |
+      # .github/workflows/deploy-caller.yml
+      jobs:
+        call-deploy:
+          environment: production       # Activates environment secrets in this calling job
+          uses: ./.github/workflows/deploy-reusable.yml
+          # WRONG: secrets: inherit     -- passes repo/org secrets but NOT environment secrets
+          secrets:
+            db_password: ${{ secrets.PROD_DB_PASSWORD }}    # Environment secret — must be explicit
+            api_key: ${{ secrets.PROD_API_KEY }}            # Environment secret — must be explicit
+
+  - language: yaml
+    label: 'Alternative — declare environment inside the reusable workflow job'
+    code: |
+      # .github/workflows/deploy-reusable.yml (alternative approach)
+      on:
+        workflow_call: {}
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          environment: production       # Directly activates environment secrets here
+          steps:                        # Couples reusable workflow to environment name
+            - name: Deploy application
+              env:
+                DB_PASSWORD: ${{ secrets.PROD_DB_PASSWORD }}
+              run: ./scripts/deploy.sh
+prevention:
+  - 'Never rely on secrets: inherit to pass environment-scoped secrets — always map them explicitly in the secrets: block of the workflow_call invocation'
+  - 'In reusable workflows, declare all required secrets in on.workflow_call.secrets with required: true so missing secrets fail loudly rather than silently resolving to empty strings'
+  - 'Document which secrets in your reusable workflow are environment-scoped vs repository-scoped so callers know the correct passing strategy'
+  - 'Test reusable workflows end-to-end from a caller workflow before deploying to production — secrets: inherit working in testing does not guarantee environment secrets work correctly'
+docs:
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#passing-secrets-to-called-workflows'
+    label: 'GitHub Docs: Passing secrets to called workflows'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-an-environment'
+    label: 'GitHub Docs: Creating secrets for an environment'
+  - url: 'https://github.com/orgs/community/discussions/26671'
+    label: 'GitHub Community #26671: secrets: inherit not passing environment secrets'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#limitations'
+    label: 'GitHub Docs: Reusable workflows — limitations'

package/errors/runner-environment/runner-environment-110.yml

@@ -0,0 +1,113 @@
+id: runner-environment-110
+title: 'actions/checkout default fetch-depth:1 shallow clone breaks git describe and changelog generation'
+category: runner-environment
+severity: error
+tags:
+  - checkout
+  - fetch-depth
+  - shallow-clone
+  - git-describe
+  - versioning
+  - changelog
+  - tags
+  - release
+patterns:
+  - regex: 'fatal:\s*No names found.*cannot describe|No tag can describe'
+    flags: 'i'
+  - regex: 'fetch-depth:\s*[01]\b'
+    flags: 'i'
+error_messages:
+  - 'fatal: No names found, cannot describe anything.'
+  - 'fatal: No tags can describe ''HEAD''.'
+  - 'error: No annotated tags can describe'
+  - '##[error]fatal: no tag exactly matches'
+root_cause: |
+  actions/checkout defaults to fetch-depth: 1 — a shallow clone that downloads
+  only the single most recent commit. This optimizes CI download speed but breaks
+  any operation that requires commit history or reachable tag ancestry:
+
+  - git describe --tags: requires a tag somewhere in the commit ancestry chain.
+    With depth 1, no ancestor commits exist, so no tags are reachable unless the
+    HEAD commit IS exactly the tagged commit. Returns "fatal: No names found,
+    cannot describe anything."
+
+  - Changelog generators (conventional-changelog, release-please, git-cliff,
+    semantic-release): need commit history to determine what changed since the
+    last release. With depth 1, they see zero commits and produce empty changelogs.
+
+  - Semantic versioning tools that count commits since last tag always return 0
+    because no prior commits (and thus no tags) are in the shallow history.
+
+  - Branch comparison and merge-base operations: git merge-base fails or produces
+    incorrect results with no shared history available.
+
+  A common workaround attempt — using fetch-tags: true with fetch-depth: 1 —
+  fetches tag objects but NOT the commits they point to in history, so
+  git describe still fails. The tags exist as objects but are not reachable from
+  HEAD via the commit graph.
+
+  This is one of the most-discussed GitHub Community topics: the checkout step
+  looks correct, CI succeeds, but release version numbers or changelogs are
+  unexpectedly empty or wrong, often discovered only after a real release attempt.
+fix: |
+  Set fetch-depth: 0 to fetch complete commit history including all tags:
+
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+  For large repositories where full history is prohibitively slow, use targeted
+  approaches:
+  - fetch-depth: 50 covers the last 50 commits — sufficient for active repos
+    that tag frequently, but risky for repos with infrequent tagging.
+  - fetch-depth: 0 combined with --filter=blob:none (partial clone) gets history
+    metadata without full file blobs — not directly configurable in the action but
+    achievable via fetch options in post-checkout scripts for advanced cases.
+
+  For changelog and release tools (release-please, git-cliff, semantic-release,
+  conventional-changelog), always use fetch-depth: 0. These tools explicitly
+  require full history and their documentation states this requirement.
+fix_code:
+  - language: yaml
+    label: 'Full history checkout for git describe and changelog generation tools'
+    code: |
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                fetch-depth: 0   # Full history required for version detection and changelogs
+                # Default fetch-depth: 1 (shallow) causes "No names found, cannot describe"
+
+            - name: Generate changelog
+              uses: orhun/git-cliff-action@v3
+              with:
+                config: cliff.toml
+
+  - language: yaml
+    label: 'Partial depth with fetch-tags for large repos — use with caution'
+    code: |
+      jobs:
+        version:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                fetch-depth: 100   # Last 100 commits — sufficient for frequently-tagged repos
+                fetch-tags: true   # Fetch tag objects so they appear in tag list
+                # WARNING: fetch-tags: true with a shallow clone fetches tag OBJECTS
+                # but NOT their commit ancestors — git describe may still fail if
+                # the tag is older than fetch-depth commits. Use fetch-depth: 0 to be safe.
+prevention:
+  - 'Set fetch-depth: 0 in any workflow that uses git describe, generates a changelog, or computes a semantic version from commit history'
+  - 'Document in your workflow why fetch-depth: 0 is required so future maintainers do not revert it to the shallow default'
+  - 'Do not assume fetch-tags: true solves shallow clone limitations for git describe — the tag objects must be reachable in the commit graph'
+  - 'Keep the default fetch-depth: 1 only for workflows that never need commit history — pure build and test jobs with no versioning or history analysis'
+docs:
+  - url: 'https://github.com/actions/checkout#usage'
+    label: 'actions/checkout: fetch-depth parameter documentation'
+  - url: 'https://github.com/orgs/community/discussions/25702'
+    label: 'GitHub Community: git describe fails with actions/checkout shallow clone'
+  - url: 'https://github.com/actions/checkout/issues/701'
+    label: 'actions/checkout #701: fetch-tags does not help with git describe on shallow clone'

package/errors/silent-failures/silent-failures-053.yml

@@ -0,0 +1,111 @@
+id: silent-failures-053
+title: 'workflow_dispatch boolean inputs arrive as strings — if: inputs.flag is always truthy'
+category: silent-failures
+severity: silent-failure
+tags:
+  - workflow-dispatch
+  - boolean-inputs
+  - type-coercion
+  - inputs-context
+  - string-comparison
+  - if-condition
+patterns:
+  - regex: 'inputs\.\w+\s*==\s*true\b'
+    flags: 'i'
+  - regex: 'if:\s*inputs\.\w+'
+    flags: 'i'
+error_messages:
+  - 'Step always runs even when boolean input is set to false'
+  - 'Boolean workflow_dispatch input behaves as truthy regardless of value'
+root_cause: |
+  GitHub Actions workflow_dispatch inputs defined with type: boolean are passed
+  to the workflow as strings ("true" or "false"), not as JavaScript/YAML booleans.
+
+  This means three common patterns silently misbehave:
+  - if: inputs.dry_run                      evaluates to always truthy (non-empty string)
+  - if: inputs.dry_run == true              always false (string "true" != boolean true)
+  - if: inputs.dry_run == false             always false (string "false" != boolean false)
+
+  The GitHub Actions expression evaluator converts the inputs context to strings
+  at the boundary between the event payload and the workflow context. Even though
+  the UI renders a checkbox, the underlying value is the literal string "true" or
+  "false". This behavior is consistent across workflow_dispatch and workflow_call
+  inputs of type boolean.
+
+  GitHub Community discussion #51504 documents this as expected behavior, but
+  thousands of developers are surprised by the mismatch between the checkbox UI
+  and the string runtime value.
+
+  Affected patterns:
+  - if: inputs.dry_run (truthy check — always true for any non-empty string value)
+  - if: inputs.flag == true (boolean comparison — always false for string "true")
+  - Ternary: ${{ inputs.flag && 'yes' || 'no' }} returns "yes" even when flag is "false"
+fix: |
+  Always compare workflow_dispatch boolean inputs to the string literal 'true'
+  or 'false':
+
+  - if: inputs.dry_run == 'true'       correct
+  - if: inputs.dry_run != 'true'       correct negation (catches "false" and "")
+  - if: inputs.dry_run == true         WRONG — string never equals boolean
+  - if: inputs.dry_run                 WRONG — always truthy for non-empty string
+
+  For workflow_call with boolean inputs, the same string coercion applies when
+  the calling workflow passes the value via the inputs: block.
+
+  The fromJSON() function converts the string to a real boolean if needed for
+  complex conditions: fromJSON(inputs.dry_run) returns actual true/false booleans.
+fix_code:
+  - language: yaml
+    label: 'Correct boolean input comparison using string equality'
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            dry_run:
+              description: 'Run without making changes'
+              type: boolean
+              default: false
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy (skip if dry run)
+              # WRONG: if: inputs.dry_run          -- always truthy (non-empty string)
+              # WRONG: if: inputs.dry_run == true   -- string never equals boolean
+              if: inputs.dry_run != 'true'
+              run: echo "Deploying..."
+
+            - name: Dry run notice
+              if: inputs.dry_run == 'true'
+              run: echo "Dry run mode — no changes made"
+
+  - language: yaml
+    label: 'Use fromJSON() to convert to real boolean for complex conditions'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Conditional step using fromJSON conversion
+              if: fromJSON(inputs.dry_run) == false
+              run: echo "Not a dry run — proceeding"
+
+            - name: Set environment variable from boolean input
+              env:
+                # fromJSON converts "true"/"false" string to actual boolean
+                DRY_RUN: ${{ fromJSON(inputs.dry_run) }}
+              run: |
+                echo "Dry run mode: $DRY_RUN"
+prevention:
+  - 'Always compare workflow_dispatch boolean inputs to the string literal ''true'' or ''false'', not to boolean true/false'
+  - 'Never use ''if: inputs.flag'' alone as a boolean check — the non-empty string "false" is truthy in GitHub Actions expressions'
+  - 'Use fromJSON(inputs.flag) when you need a real boolean value in expressions or env: context'
+  - 'Add a comment in your workflow noting that boolean dispatch inputs are strings at runtime to warn future maintainers'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-syntax-for-github-actions#onworkflow_dispatchinputs'
+    label: 'GitHub Docs: workflow_dispatch inputs syntax'
+  - url: 'https://github.com/orgs/community/discussions/51504'
+    label: 'GitHub Community #51504: Boolean inputs in workflow_dispatch are strings'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#fromjson'
+    label: 'GitHub Docs: fromJSON expression function'

package/errors/yaml-syntax/yaml-syntax-037.yml

@@ -0,0 +1,105 @@
+id: yaml-syntax-037
+title: 'Step cannot have both uses: and run: — mutually exclusive keys cause workflow validation failure'
+category: yaml-syntax
+severity: error
+tags:
+  - yaml-syntax
+  - uses
+  - run
+  - step-definition
+  - workflow-validation
+  - mutually-exclusive
+patterns:
+  - regex: 'uses:\s*.+\n\s+run:'
+    flags: 'im'
+  - regex: 'run:\s*.+\n\s+uses:'
+    flags: 'im'
+error_messages:
+  - "A step must define one of ['run', 'uses']"
+  - 'Unexpected value ''run'''
+  - 'Workflow file is not valid: .github/workflows/ci.yml (Line: N, Col: M): Unexpected value ''run'''
+  - "A step must not define both 'uses' and 'run'"
+root_cause: |
+  A GitHub Actions workflow step is either an action reference (uses:) or a
+  shell command (run:), but never both simultaneously. These two keys are mutually
+  exclusive by design: uses: runs a pre-built action with its own entry point, while
+  run: executes arbitrary shell commands in the runner's default shell.
+
+  Common scenarios that produce this error:
+
+  1. Adding a quick debug command to an existing action step:
+       - uses: actions/checkout@v4
+         run: echo "debug"          # INVALID — cannot add run: to a uses: step
+
+  2. Copy-paste error merging two separate steps into one:
+       - name: Setup and verify
+         uses: actions/setup-node@v4
+         run: node --version         # INVALID — should be two separate steps
+
+  3. Attempting to run commands after an action in a single step:
+       - uses: docker/build-push-action@v6
+         with:
+           push: true
+         run: docker image ls        # INVALID
+
+  The workflow is rejected at parse time with a validation error before any
+  job runs. The exact error message varies by GitHub Actions version but always
+  indicates that the step cannot define both keys.
+fix: |
+  Split the step into two separate steps: one with uses: for the action, and
+  a new step with run: for the shell command. Each step in a job must be
+  exclusively one type.
+fix_code:
+  - language: yaml
+    label: 'Wrong: uses: and run: in the same step — workflow validation fails'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Checkout and show files    # INVALID
+              uses: actions/checkout@v4
+              run: ls -la                       # INVALID: cannot add run: to uses: step
+
+  - language: yaml
+    label: 'Correct: split into two separate steps'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Checkout
+              uses: actions/checkout@v4         # action step
+
+            - name: Show files                  # separate shell step
+              run: ls -la
+
+  - language: yaml
+    label: 'Common mistake: adding debug run: to an action step'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/setup-node@v4
+              with:
+                node-version: '20'
+              # WRONG: adding run: here is invalid
+              # run: node --version
+
+            # CORRECT: add a separate step after the action
+            - name: Verify Node version
+              run: node --version
+prevention:
+  - 'Remember: every step is either uses: (action) OR run: (shell) — never both'
+  - 'To run commands after an action, always create a new step with its own name: and run:'
+  - 'Use actionlint locally to catch uses:/run: conflicts before pushing'
+  - 'Use the GitHub Actions VS Code extension — it highlights mutually exclusive keys in the editor'
+  - 'When copying steps from documentation, verify each step has only one of uses: or run:'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsuses'
+    label: 'GitHub Docs: jobs.<job_id>.steps[*].uses'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun'
+    label: 'GitHub Docs: jobs.<job_id>.steps[*].run'
+  - url: 'https://rhysd.github.io/actionlint/'
+    label: 'actionlint: Static checker for GitHub Actions workflow files'

package/package.json

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