@htekdev/actions-debugger 1.0.52 → 1.0.53

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/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.52",
+  "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",