@htekdev/actions-debugger 1.0.52 → 1.0.54

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

@@ -0,0 +1,95 @@
+id: caching-artifacts-037
+title: "upload-artifact if-no-files-found defaults to 'warn' — empty upload succeeds, download job fails"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - upload-artifact
+  - if-no-files-found
+  - artifacts
+  - silent
+  - warn
+  - download
+patterns:
+  - regex: 'No files were found with the provided path'
+    flags: i
+  - regex: 'No artifact uploads were performed'
+    flags: i
+  - regex: 'was not found for the associated workflow run'
+    flags: i
+error_messages:
+  - "No files were found with the provided path: ./dist. No artifacts will be uploaded."
+  - "Warning: No files were found with the provided path: build/"
+  - "No artifact uploads were performed."
+  - "Error: An artifact named build-output was not found for the associated workflow run."
+root_cause: |
+  The if-no-files-found input of actions/upload-artifact defaults to warn, not error.
+  When the upload path: glob matches no files — because the build directory is missing,
+  a glob pattern is wrong, the working-directory setting differs from the upload path,
+  or a preceding build step failed silently — the upload step logs a warning message and
+  exits with code 0 (success).
+
+  The calling workflow sees a green upload step in the UI. The problem only surfaces in
+  the downstream job that calls actions/download-artifact, which fails with an error like
+  "An artifact named X was not found for the associated workflow run."
+
+  Developers spend time debugging the download step or the job that uses the artifact when
+  the real problem — the build not producing output — occurred earlier, often in a different
+  job. The default warn behavior exists for optional artifacts, but it is a frequent source
+  of confusion for required CI artifacts.
+fix: |
+  Set if-no-files-found: error on every upload step where the artifact is required.
+  The upload step will immediately fail with a descriptive error message that names the
+  missing path, pointing directly to the correct job.
+
+  Reserve warn or ignore only for genuinely optional artifacts — for example, test
+  screenshots that only exist when tests fail, or coverage reports that may be skipped
+  in some build configurations.
+fix_code:
+  - language: yaml
+    label: "Correct: fail immediately when required build output is missing"
+    code: |
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: ./dist/
+          if-no-files-found: error   # Fail here — not in the downstream download job
+  - language: yaml
+    label: "Optional artifact — keep warn or ignore"
+    code: |
+      - name: Upload test screenshots (optional — only exist on test failure)
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-screenshots
+          path: ./test-results/screenshots/
+          if-no-files-found: ignore   # OK — screenshots only exist when tests fail
+  - language: yaml
+    label: "Verify build output before uploading"
+    code: |
+      - name: Verify dist/ was built
+        run: |
+          if [ ! -d "./dist" ] || [ -z "$(ls -A ./dist)" ]; then
+            echo "ERROR: dist/ directory is empty or missing"
+            exit 1
+          fi
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: ./dist/
+          if-no-files-found: error
+prevention:
+  - "Default to if-no-files-found: error in all CI pipeline templates for required artifacts"
+  - "Note that upload path: is relative to GITHUB_WORKSPACE, not the step's working-directory setting"
+  - "Add an explicit build verification step before upload to fail fast with a clear message"
+  - "Audit existing workflows: any upload-artifact step without if-no-files-found: error is a silent failure risk"
+  - "When a build step uses continue-on-error: true, verify it did not silently skip output generation before uploading"
+docs:
+  - url: "https://github.com/actions/upload-artifact#inputs"
+    label: "actions/upload-artifact: Input parameters reference"
+  - url: "https://github.com/actions/upload-artifact/blob/main/RELEASES.md"
+    label: "actions/upload-artifact: Release notes"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-and-sharing-data-from-a-workflow"
+    label: "GitHub Docs: Storing and sharing data from a workflow"

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-039.yml

@@ -0,0 +1,108 @@
+id: permissions-auth-039
+title: "setup-node registry-url creates .npmrc but NODE_AUTH_TOKEN not set → npm E401"
+category: permissions-auth
+severity: error
+tags:
+  - setup-node
+  - npm
+  - registry
+  - authentication
+  - publish
+  - node_auth_token
+patterns:
+  - regex: 'npm ERR! code E401'
+    flags: i
+  - regex: 'npm ERR! 401 Unauthorized'
+    flags: i
+  - regex: 'npm ERR! need auth'
+    flags: i
+  - regex: 'npm error code EBADAUTH'
+    flags: i
+error_messages:
+  - "npm ERR! code E401"
+  - "npm ERR! 401 Unauthorized - PUT https://registry.npmjs.org/@scope/package-name"
+  - "npm ERR! need auth You need to authorize this machine using `npm adduser`"
+  - "npm error code EBADAUTH"
+root_cause: |
+  When registry-url is set in actions/setup-node, the action generates an .npmrc file
+  containing a token placeholder line such as:
+    //registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}
+
+  The variable name NODE_AUTH_TOKEN is hardcoded in this template and must be supplied
+  as an environment variable at runtime on every step that communicates with the registry.
+
+  If the npm publish or npm install step does not declare
+  `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}` in its env: block, the placeholder expands
+  to an empty string. npm sends an unauthenticated request and receives HTTP 401
+  Unauthorized from the registry.
+
+  The setup-node step itself succeeds with no warnings — there is no validation that
+  NODE_AUTH_TOKEN will be set. The 401 only surfaces during the npm command, misleading
+  developers to investigate the token or registry configuration rather than the missing
+  env: declaration.
+fix: |
+  Add NODE_AUTH_TOKEN to the env: block of every step that runs npm commands against the
+  authenticated registry. The variable name must be exactly NODE_AUTH_TOKEN — npm reads
+  it directly from the .npmrc template generated by setup-node.
+
+  For GitHub Packages (npm.pkg.github.com), use secrets.GITHUB_TOKEN.
+  For npmjs.com, use a dedicated automation token stored as a repository secret (e.g. NPM_TOKEN).
+
+  If all registry requests — including npm install of private scoped packages — need
+  authentication (not just publish), also set always-auth: true in the setup-node step.
+fix_code:
+  - language: yaml
+    label: "Correct: NODE_AUTH_TOKEN on the publish step"
+    code: |
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Publish to npm
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+  - language: yaml
+    label: "GitHub Packages registry variant"
+    code: |
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://npm.pkg.github.com'
+          scope: '@your-org'
+
+      - name: Publish to GitHub Packages
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  - language: yaml
+    label: "Private package install with always-auth"
+    code: |
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://npm.pkg.github.com'
+          scope: '@your-org'
+          always-auth: true    # Send auth on all requests, not just publish
+
+      - name: Install dependencies (includes private scoped packages)
+        run: npm ci
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+prevention:
+  - "Every npm step that interacts with an authenticated registry must declare NODE_AUTH_TOKEN in its env: block"
+  - "Setting registry-url in setup-node does NOT automatically forward any secrets to npm — the env: mapping is always required"
+  - "Use always-auth: true in setup-node when npm install (not just publish) must authenticate, such as for private scoped packages"
+  - "Store your npm automation token as a repository secret: Settings → Secrets and variables → Actions → New repository secret"
+  - "For GitHub Packages, NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }} is sufficient — no separate token needed"
+docs:
+  - url: "https://github.com/actions/setup-node#publishing-to-npmjs-and-github-packages-registries"
+    label: "actions/setup-node: Publishing to registries"
+  - url: "https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry"
+    label: "GitHub Docs: Working with the npm registry"
+  - url: "https://docs.npmjs.com/using-private-packages-in-a-ci-cd-workflow"
+    label: "npm Docs: Using private packages in CI/CD"

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

@@ -0,0 +1,93 @@
+id: runner-environment-111
+title: "setup-node node-version: 'latest' silently upgrades to new Node.js major, breaking engines field"
+category: runner-environment
+severity: silent-failure
+tags:
+  - setup-node
+  - node-version
+  - latest
+  - engines
+  - breaking-change
+  - major-version
+  - semver
+patterns:
+  - regex: 'The engine "node" is incompatible with this module'
+    flags: i
+  - regex: 'EBADENGINE.*Unsupported engine'
+    flags: i
+  - regex: 'npm warn EBADENGINE'
+    flags: i
+  - regex: 'engine.*node.*incompatible.*Expected version'
+    flags: i
+error_messages:
+  - "error The engine \"node\" is incompatible with this module. Expected version \">=18 <21\". Got \"23.x.x\""
+  - "npm warn EBADENGINE Unsupported engine { required: { node: '>=16 <20' }, current: { node: 'v22.0.0' } }"
+  - "npm error code EBADENGINE"
+  - "error This package requires Node.js >= 18.0.0 and <= 22.x"
+root_cause: |
+  When node-version: 'latest' is used in actions/setup-node, the action resolves the
+  alias against the official Node.js release schedule manifest on every workflow run.
+  When Node.js releases a new major version (e.g. v23.0.0, v24.0.0), the next run silently
+  downloads and activates the new major without any warning in the setup-node step output.
+
+  Packages that declare an engines constraint in their package.json (e.g.
+  engines: { node: ">=18 <22" }) then fail during npm install or yarn install with
+  EBADENGINE because the newly installed version exceeds the accepted range.
+
+  The setup-node step itself succeeds and logs the installed version; the failure only
+  appears downstream when the package manager processes the engines field. Because the
+  workflow ran successfully for months before the Node.js major release, developers
+  are not expecting a version bump and may incorrectly blame a dependency change.
+
+  Native addons and frameworks that have not yet published compatibility updates for the
+  new major can also fail during postinstall or build steps.
+fix: |
+  Pin to a specific LTS major version string (e.g. '20', '22') rather than 'latest'.
+  LTS majors receive security patches but do not automatically jump to a new major.
+
+  Alternatively, use the node-version-file input to read the version from a .nvmrc or
+  .node-version file committed to the repository. This keeps the Node.js version
+  consistent between local development and CI and makes version upgrades explicit
+  (a PR changes the version file).
+fix_code:
+  - language: yaml
+    label: "Pin to a specific LTS major (recommended)"
+    code: |
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'   # Pinned LTS major — will not jump to Node 24 automatically
+          cache: 'npm'
+  - language: yaml
+    label: "Use .nvmrc for repo-defined version shared with local dev"
+    code: |
+      # .nvmrc (committed to repository root)
+      # 22.x
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'   # Same version in local dev and CI
+          cache: 'npm'
+  - language: yaml
+    label: "Pin with explicit patch version for maximum reproducibility"
+    code: |
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22.13.1'   # Exact patch — fully reproducible but requires manual updates
+          cache: 'npm'
+prevention:
+  - "Never use node-version: 'latest' in production or long-lived CI workflows — pin to an LTS major"
+  - "Prefer '18', '20', or '22' (active LTS) — these receive security patches without surprise major bumps"
+  - "Use node-version-file pointing to .nvmrc to keep local development and CI on the same version"
+  - "Use Renovate or Dependabot to automate controlled Node.js upgrades with a PR and changelog review"
+  - "Test new Node.js majors in a dedicated branch before adopting them in main CI"
+  - "Declare an engines field in package.json to make your Node.js version requirement explicit and testable"
+docs:
+  - url: "https://github.com/actions/setup-node#supported-version-syntax"
+    label: "actions/setup-node: Supported version syntax"
+  - url: "https://nodejs.org/en/about/previous-releases"
+    label: "Node.js: Release schedule and LTS versions"
+  - url: "https://docs.npmjs.com/cli/v10/configuring-npm/package-json#engines"
+    label: "npm: package.json engines field documentation"

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

@@ -0,0 +1,100 @@
+id: silent-failures-054
+title: "Windows CRLF line endings in committed scripts cause bad interpreter error on Linux runners"
+category: silent-failures
+severity: error
+tags:
+  - checkout
+  - crlf
+  - line-endings
+  - windows
+  - bash
+  - gitattributes
+  - bad-interpreter
+patterns:
+  - regex: 'bad interpreter.*No such file or directory'
+    flags: i
+  - regex: '\^M: command not found'
+    flags: ''
+  - regex: '/bin/bash\^M'
+    flags: ''
+  - regex: '\r: command not found'
+    flags: ''
+error_messages:
+  - "/bin/bash^M: bad interpreter: No such file or directory"
+  - "^M: command not found"
+  - ": /bin/sh^M: bad interpreter: No such file or directory"
+  - "syntax error: unexpected end of file"
+root_cause: |
+  Shell scripts, Python files, and other text files committed from Windows workstations
+  where core.autocrlf is false (or not configured) retain Windows CRLF (\r\n) line endings.
+  actions/checkout preserves committed bytes exactly — it does not normalize line endings.
+
+  On a Linux runner, the kernel reads the shebang line #!/bin/bash\r as the interpreter
+  path /bin/bash^M (with a literal carriage return appended). No file with that name exists,
+  so the kernel returns "bad interpreter: No such file or directory." The error message
+  looks like a missing binary or path problem, masking the true cause: CRLF line endings.
+
+  This is a classic silent failure because:
+  - The developer's Windows machine runs the script correctly
+  - The checkout step succeeds with no warnings about line endings
+  - The failure only manifests when the script is executed on a Linux runner
+  - Most text editors hide the ^M characters, so the file looks normal in review
+fix: |
+  Add a .gitattributes file to the repository root specifying LF normalization for text
+  files. This instructs Git to store files with LF endings in the repository regardless
+  of the committer's OS or local git configuration.
+
+  After adding .gitattributes, re-normalize all tracked files: stage all files with the
+  renormalize flag (e.g. `add --renormalize .` via the CLI), then commit the result.
+  Without this step, already-committed CRLF files remain unchanged.
+
+  Also add a CI detection step to catch any future regressions before they reach main.
+fix_code:
+  - language: yaml
+    label: ".gitattributes — enforce LF for scripts and text files"
+    code: |
+      # .gitattributes (add to repository root)
+
+      # Normalize all text files to LF in the repository
+      * text=auto eol=lf
+
+      # Explicitly enforce LF for scripts and config files
+      *.sh   text eol=lf
+      *.bash text eol=lf
+      *.py   text eol=lf
+      *.yml  text eol=lf
+      *.yaml text eol=lf
+      *.json text eol=lf
+
+      # Keep CRLF for Windows-specific files
+      *.bat text eol=crlf
+      *.cmd text eol=crlf
+  - language: yaml
+    label: "CI step to detect CRLF in shell and Python scripts"
+    code: |
+      - name: Check for CRLF line endings in scripts
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v4
+          - name: Detect CRLF
+            run: |
+              found=$(find . -name '*.sh' -o -name '*.py' -o -name '*.yml' | \
+                xargs file 2>/dev/null | grep CRLF || true)
+              if [ -n "$found" ]; then
+                echo "ERROR: CRLF line endings detected in the following files:"
+                echo "$found"
+                exit 1
+              fi
+prevention:
+  - "Add .gitattributes with `* text=auto eol=lf` to every repository that may be edited on Windows"
+  - "Re-normalize existing files after adding .gitattributes: use the CLI `add --renormalize .` flag, then commit"
+  - "Configure the autocrlf setting on Windows development machines: set core.autocrlf=input so CRLF is converted to LF on commit"
+  - "Configure your editor (VS Code, Notepad++, JetBrains) to use LF line endings for shell and YAML files by default"
+  - "Add a CRLF detection step in CI to fail PRs that introduce Windows line endings into script files"
+docs:
+  - url: "https://docs.github.com/en/get-started/getting-started-with-git/configuring-git-to-handle-line-endings"
+    label: "GitHub Docs: Configuring Git to handle line endings"
+  - url: "https://git-scm.com/docs/gitattributes"
+    label: "Git: gitattributes documentation"
+  - url: "https://github.com/actions/checkout/issues/135"
+    label: "actions/checkout Issue #135: Line ending normalization"

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