@htekdev/actions-debugger 1.0.103 → 1.0.104

package/errors/caching-artifacts/upload-artifact-v4-hidden-files-excluded-by-default.yml

@@ -0,0 +1,82 @@
+id: caching-artifacts-059
+title: 'actions/upload-artifact@v4 excludes hidden files by default — dotfiles silently missing from artifacts'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - upload-artifact
+  - v4
+  - hidden-files
+  - dotfiles
+  - include-hidden-files
+  - silent-omission
+patterns:
+  - regex: 'uses:\s*actions/upload-artifact@v4'
+    flags: 'i'
+  - regex: 'include-hidden-files:\s*false'
+    flags: 'i'
+error_messages:
+  - 'No files were found with the provided path'
+  - 'Uploading 0 files'
+  - 'Found no files matching'
+root_cause: |
+  actions/upload-artifact@v4 introduced the include-hidden-files input, which defaults
+  to false. Any file or directory whose name begins with a dot (.) is silently excluded
+  from the artifact upload. The action completes with a success status and reports the
+  number of files uploaded — only inspecting that count reveals that dotfiles were
+  skipped.
+
+  Common files and directories affected:
+    .env, .env.production, .env.local     — environment configuration
+    .npmrc, .nvmrc, .node-version          — Node.js toolchain config
+    .htaccess                              — Apache web server config
+    .browserslistrc, .babelrc              — build tool configuration
+    .next/, .nuxt/, .svelte-kit/           — framework build output directories
+    .vitepress/, .docusaurus/              — documentation build output
+
+  Workflows migrated from v3 to v4 silently break: the artifact is created and
+  downloaded without any error, but dependent steps fail when the expected dotfiles
+  are absent. Framework deployments (Next.js, Nuxt, SvelteKit) that upload their build
+  output are most frequently affected since their output directories are hidden.
+fix: |
+  Set include-hidden-files: true on the upload step whenever dotfiles or dot-directories
+  must be preserved in the artifact:
+
+    - uses: actions/upload-artifact@v4
+      with:
+        name: build-output
+        path: ./dist
+        include-hidden-files: true
+
+  Alternatively, explicitly list only the required hidden files in the path input to
+  avoid uploading the entire directory with hidden file inclusion.
+fix_code:
+  - language: yaml
+    label: 'Add include-hidden-files: true to preserve dotfiles and dot-directories'
+    code: |
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: ./.next          # Next.js build output is a hidden directory
+          include-hidden-files: true   # required — excluded by default in v4
+  - language: yaml
+    label: 'Alternative: explicitly list hidden files instead of directory glob'
+    code: |
+      - name: Upload build artifacts including dotfiles
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: |
+            ./dist
+            ./.env.production
+            ./.nvmrc
+            ./.npmrc
+prevention:
+  - 'Set include-hidden-files: true when uploading directories known to contain dotfiles or dot-directories (.next/, .nuxt/, .svelte-kit/, etc.)'
+  - 'After migrating from upload-artifact@v3 to @v4, inspect the artifact file count in the run log — a drop indicates hidden files were excluded'
+  - 'Add a post-upload verification step: download the artifact in a subsequent job and assert the expected dotfiles exist'
+docs:
+  - url: 'https://github.com/actions/upload-artifact/blob/main/README.md'
+    label: 'actions/upload-artifact README: include-hidden-files input'
+  - url: 'https://github.com/actions/upload-artifact/blob/main/docs/migration-v3-to-v4.md'
+    label: 'Migration guide: upload-artifact v3 to v4'

package/errors/concurrency-timing/github-run-id-concurrency-group-disables-cancel-in-progress.yml

@@ -0,0 +1,90 @@
+id: concurrency-timing-048
+title: 'github.run_id in concurrency group key disables cancel-in-progress — every run is unique, unlimited parallelism'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - cancel-in-progress
+  - github-run-id
+  - unique-key
+  - parallelism
+  - anti-pattern
+patterns:
+  - regex: 'group:.*\$\{\{\s*github\.run_id\s*\}\}'
+    flags: 'i'
+  - regex: 'group:.*github\.run_id'
+    flags: 'i'
+error_messages:
+  - 'Old workflow runs are not being cancelled despite cancel-in-progress: true'
+  - 'Multiple concurrent runs executing simultaneously'
+root_cause: |
+  github.run_id is always unique per workflow run — it is the numeric identifier
+  assigned at run creation time. When used in the concurrency group key, every run
+  evaluates to a different group name. No two runs ever share the same group, so
+  cancel-in-progress: true has nothing to cancel. All runs proceed simultaneously.
+
+  This anti-pattern typically originates from developers who experienced unwanted
+  concurrency cancellations and "fixed" the problem by adding a unique value to the
+  group key. The immediate cancellation symptom disappears but a more serious problem
+  is introduced: on high-velocity branches, dozens of in-progress CI runs pile up
+  simultaneously, exhausting the available runner pool and increasing costs.
+
+  Related: github.sha in the group key has the same effect (concurrency-timing-030),
+  but github.run_id is more severe. github.sha can repeat when a commit is re-run;
+  github.run_id is unconditionally unique per run and per re-run attempt, so
+  cancel-in-progress is permanently disabled with no exceptions.
+fix: |
+  Remove github.run_id from the concurrency group key. Use github.ref (for branch-scoped
+  deduplication) or github.head_ref (for PR-scoped deduplication). If the original
+  goal was to prevent manual dispatch runs from being cancelled, scope the unique key
+  to workflow_dispatch events only using a conditional expression:
+
+    group: >-
+      ${{ github.workflow }}-
+      ${{ github.event_name == 'workflow_dispatch' && github.run_id || github.ref }}
+fix_code:
+  - language: yaml
+    label: 'Wrong: github.run_id makes every run unique — cancel-in-progress is dead code'
+    code: |
+      # WRONG: every run gets its own unique group — cancel-in-progress never fires
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}-${{ github.run_id }}
+        cancel-in-progress: true  # never cancels anything
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: 'Correct: branch-scoped group key enables cancel-in-progress'
+    code: |
+      # CORRECT: all pushes to same branch share one group
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: 'Advanced: isolate manual dispatch runs while deduplicating automated runs'
+    code: |
+      # Manual dispatch runs are never cancelled; push/PR runs cancel old runs on same branch
+      concurrency:
+        group: >-
+          ${{ github.workflow }}-
+          ${{ github.event_name == 'workflow_dispatch' && github.run_id || github.ref }}
+        cancel-in-progress: true
+prevention:
+  - 'Never add github.run_id to a concurrency group key when the goal is to cancel old runs — it defeats cancel-in-progress entirely'
+  - 'Verify cancel-in-progress by triggering two rapid pushes and confirming the first run is cancelled in the Actions UI'
+  - 'If cancellation of specific trigger types is unwanted, use event_name-conditional keys instead of unique values'
+  - 'Monitor runner utilization — unbounded parallel runs will exhaust available runners and increase billing'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#github-context'
+    label: 'GitHub Docs: github context — run_id'

package/errors/concurrency-timing/pull-request-target-base-ref-concurrency-serializes-all-prs.yml

@@ -0,0 +1,78 @@
+id: concurrency-timing-046
+title: 'pull_request_target github.ref resolves to base branch — all PRs targeting same branch share one concurrency slot'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - pull_request_target
+  - github-ref
+  - base-branch
+  - serialization
+patterns:
+  - regex: 'on:\s*\n\s+pull_request_target:'
+    flags: 'ms'
+  - regex: 'group:.*github\.ref'
+    flags: 'i'
+error_messages:
+  - 'This run was automatically queued'
+  - 'Waiting for a pending job to complete'
+root_cause: |
+  On pull_request events, github.ref is the head branch ref (e.g., refs/heads/my-feature).
+  On pull_request_target events, however, github.ref is the BASE branch ref (e.g.,
+  refs/heads/main) — the branch the PR targets. This is a security design choice that
+  prevents untrusted fork code from influencing the event ref.
+
+  When a concurrency group key uses github.ref in a pull_request_target workflow, all
+  open PRs targeting the same base branch (main, develop, etc.) evaluate to the identical
+  group key. Only one PR's CI can run at a time; all others queue behind it. On repos
+  with many open PRs, this effectively serializes all PR workflows into a single lane
+  with potentially multi-hour wait times.
+
+  The correct per-PR identifier in pull_request_target workflows is
+  github.event.pull_request.number — unique per PR regardless of base branch.
+fix: |
+  Replace github.ref with github.event.pull_request.number in concurrency group keys
+  for pull_request_target workflows. PR numbers are unique per repository and stable
+  across new commits to the same PR:
+
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+      cancel-in-progress: true
+fix_code:
+  - language: yaml
+    label: 'Wrong: github.ref = base branch on pull_request_target — all PRs share one slot'
+    code: |
+      # WRONG: github.ref = refs/heads/main for ALL PRs targeting main
+      on:
+        pull_request_target:
+
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}  # same for every PR!
+        cancel-in-progress: true
+  - language: yaml
+    label: 'Correct: use github.event.pull_request.number for per-PR isolation'
+    code: |
+      # CORRECT: PR number is unique per PR, stable across pushes to same PR
+      on:
+        pull_request_target:
+
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+        cancel-in-progress: true
+
+      jobs:
+        lint:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.pull_request.head.sha }}
+prevention:
+  - 'In pull_request_target workflows, never use github.ref as the sole differentiator in concurrency groups — it is the base branch ref'
+  - 'Use github.event.pull_request.number to scope concurrency to individual PRs'
+  - 'Audit concurrency groups when migrating workflows from pull_request to pull_request_target'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_target'
+    label: 'GitHub Docs: pull_request_target event'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency'

package/errors/concurrency-timing/workflow-dispatch-schedule-shared-concurrency-kills-scheduled-run.yml

@@ -0,0 +1,87 @@
+id: concurrency-timing-047
+title: 'workflow_dispatch and schedule sharing a concurrency group — manual dispatch silently cancels queued scheduled run'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - workflow_dispatch
+  - schedule
+  - cancel-in-progress
+  - scheduled-job
+patterns:
+  - regex: 'schedule:.*\n.*workflow_dispatch:|workflow_dispatch:.*\n.*schedule:'
+    flags: 'ms'
+  - regex: 'group:\s*.*github\.workflow'
+    flags: 'i'
+error_messages:
+  - 'This run was automatically cancelled'
+  - 'Canceling since a higher priority waiting run was found'
+root_cause: |
+  When a workflow is triggered by both schedule and workflow_dispatch and uses a shared
+  concurrency group key that does not include github.event_name (e.g.,
+  group: ${{ github.workflow }}-${{ github.ref }}), all runs — regardless of trigger
+  type — map to the same concurrency slot.
+
+  When cancel-in-progress: true is set, any manual workflow_dispatch run immediately
+  cancels the scheduled run that may be actively executing. A developer who triggers
+  a manual run can silently kill a scheduled maintenance job, nightly report, or backup
+  workflow with no warning or notification.
+
+  When cancel-in-progress: false, GitHub only keeps one pending run per concurrency
+  slot. A queued scheduled run is silently displaced when the dispatch run arrives.
+  The scheduled run is discarded with no error, no notification, and no log entry.
+
+  This affects maintenance workflows, report generators, data sync jobs, and backup
+  workflows where workflow_dispatch is added for "emergency manual runs" after the
+  initial scheduled implementation.
+fix: |
+  Include github.event_name in the concurrency group key to give each trigger type
+  its own independent concurrency slot:
+
+    group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
+
+  This ensures that manual dispatch runs and scheduled runs never compete for the
+  same slot and cannot cancel each other.
+fix_code:
+  - language: yaml
+    label: 'Wrong: schedule and workflow_dispatch share the same concurrency slot'
+    code: |
+      on:
+        schedule:
+          - cron: '0 3 * * *'   # nightly at 03:00 UTC
+        workflow_dispatch:
+
+      # WRONG: both trigger types evaluate to the same group key
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true  # dispatch run kills the in-progress scheduled run
+  - language: yaml
+    label: 'Correct: include github.event_name to isolate trigger types'
+    code: |
+      on:
+        schedule:
+          - cron: '0 3 * * *'
+        workflow_dispatch:
+
+      # CORRECT: schedule and workflow_dispatch get separate concurrency slots
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      jobs:
+        nightly:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./nightly-tasks.sh
+prevention:
+  - 'Always include ${{ github.event_name }} in the concurrency group for workflows with multiple trigger event types'
+  - 'After adding workflow_dispatch to an existing scheduled workflow, verify scheduled runs are not silently displaced'
+  - 'Monitor the Actions tab run history — consecutive scheduled run gaps may indicate silent cancellations'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'GitHub Docs: Using concurrency'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule'
+    label: 'GitHub Docs: schedule event'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_dispatch'
+    label: 'GitHub Docs: workflow_dispatch event'

package/package.json

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