@htekdev/actions-debugger 1.0.67 → 1.0.69

package/errors/caching-artifacts/artifact-retention-days-silently-capped-org-maximum.yml

@@ -0,0 +1,69 @@
+id: caching-artifacts-043
+title: "upload-artifact retention-days silently capped at organization maximum — artifact expires earlier than configured"
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - upload-artifact
+  - retention-days
+  - artifacts
+  - organization-policy
+  - expiry
+patterns:
+  - regex: 'Artifact will be retained for \d+ days'
+    flags: "i"
+error_messages:
+  - "Artifact will be retained for"
+root_cause: |
+  When actions/upload-artifact is configured with a retention-days value that exceeds the
+  organization's or repository's maximum artifact retention setting, GitHub silently caps
+  the retention period to the configured maximum without emitting any error or warning.
+  The upload step completes successfully, the workflow shows green, and the artifact is
+  created — but it expires sooner than the workflow author intended.
+
+  This is particularly dangerous for:
+  - Compliance workflows that retain build artifacts for audits
+  - Release workflows where binaries must survive for customer download periods
+  - Security scanning workflows that need artifacts for post-incident review
+
+  The only way to discover the cap is to inspect the artifact's expiration date in the
+  repository's Actions UI after upload, or query the REST API. Developers who set
+  retention-days: 365 expecting one-year retention will find artifacts disappearing after
+  90 days (the default org maximum) with no log evidence of the cap.
+fix: |
+  Check your organization's artifact retention maximum under Organization Settings → Actions
+  → General → Artifact and log retention, and ensure retention-days in upload-artifact is
+  set to a value at or below this limit. If you need retention beyond the org maximum
+  (e.g., for compliance), use GitHub Releases for tagged builds, or an external artifact
+  store (S3, Azure Blob, GCS). You can also query the artifact API to assert the actual
+  expiry date and fail the workflow if it doesn't match expectations.
+fix_code:
+  - language: yaml
+    label: "Cap retention-days to org maximum and use GitHub Releases for long-term storage"
+    code: |
+      - name: Upload build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-output-${{ github.sha }}
+          path: dist/
+          # Must be <= your org's maximum retention setting
+          # Check: Org Settings → Actions → General → Artifact and log retention
+          retention-days: 30
+
+      # For artifacts requiring retention beyond the org maximum (e.g., release binaries),
+      # attach them to a GitHub Release instead:
+      - name: Create GitHub Release with artifact
+        uses: softprops/action-gh-release@v2
+        if: startsWith(github.ref, 'refs/tags/')
+        with:
+          files: dist/**
+          # Release assets are NOT subject to the artifact retention policy
+prevention:
+  - "Check your organization's artifact retention maximum before setting retention-days in upload-artifact"
+  - "For artifacts requiring long-term storage, use GitHub Releases or an external object store (S3, GCS, Azure Blob)"
+  - "Add a workflow step that queries the artifact expiry via the REST API and fails if it doesn't match the intended retention"
+  - "Document the org retention limit in a comment next to retention-days to alert future editors"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-workflow-data-as-artifacts"
+    label: "Storing workflow data as artifacts — GitHub Docs"
+  - url: "https://docs.github.com/en/organizations/managing-organization-settings/configuring-the-retention-period-for-github-actions-artifacts-and-logs-in-your-organization"
+    label: "Configuring artifact retention period for your organization — GitHub Docs"

package/errors/concurrency-timing/cancel-in-progress-deployment-environment-review-loop.yml

@@ -0,0 +1,76 @@
+id: concurrency-timing-036
+title: "cancel-in-progress: true cancels pending deployment environment reviews — deployment never completes"
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - deployment
+  - environment
+  - cancel-in-progress
+  - required-reviewers
+patterns:
+  - regex: 'waiting for a required environment'
+    flags: "i"
+  - regex: 'Deployment to .+ was cancelled'
+    flags: "i"
+error_messages:
+  - "This workflow run is waiting for a required environment"
+  - "Deployment to production was cancelled"
+root_cause: |
+  When a deployment job targets an environment with required reviewers (protection rules)
+  and cancel-in-progress: true is set on the concurrency group, every new push cancels the
+  pending workflow run — including the one awaiting reviewer approval. The reviewer is
+  notified, starts the review process, but before they approve a new commit arrives and
+  cancels the run. The cycle repeats indefinitely: deployments queue, reviewers are
+  interrupted, and nothing ever reaches production. No diagnostic error is surfaced; the
+  workflow simply shows "Cancelled" with no indication that a required-reviewer gate was
+  involved.
+fix: |
+  Remove cancel-in-progress: true from the concurrency group used by the deployment job.
+  Use cancel-in-progress: false (the default) so pending approval runs survive new commits.
+  To still get fast feedback on CI, split the workflow into two separate files: a fast CI
+  workflow with cancel-in-progress: true, and a deployment workflow (triggered on CI success)
+  with cancel-in-progress: false so approval gates are preserved.
+fix_code:
+  - language: yaml
+    label: "Split CI and deploy workflows with separate concurrency policies"
+    code: |
+      # .github/workflows/ci.yml — cancel old CI runs freely
+      on: [push, pull_request]
+      concurrency:
+        group: ci-${{ github.ref }}
+        cancel-in-progress: true
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+
+      # .github/workflows/deploy.yml — preserve pending deployment approvals
+      on:
+        workflow_run:
+          workflows: [CI]
+          types: [completed]
+          branches: [main]
+      concurrency:
+        group: deploy-${{ github.ref }}
+        cancel-in-progress: false   # preserves pending required-reviewer approval
+      jobs:
+        deploy:
+          if: ${{ github.event.workflow_run.conclusion == 'success' }}
+          environment: production   # has required reviewers
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "Deploying..."
+prevention:
+  - "Never combine cancel-in-progress: true with deployment jobs that have required-reviewer environment protection rules"
+  - "Use separate workflow files for CI and deployment to apply different concurrency policies"
+  - "Set cancel-in-progress: false (or omit it) on any concurrency group that wraps a deployment environment job"
+  - "Test the deployment approval flow explicitly after adding or changing concurrency settings"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency"
+    label: "Using concurrency — GitHub Docs"
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/reviewing-deployments"
+    label: "Reviewing deployments — GitHub Docs"

package/errors/concurrency-timing/concurrency-group-missing-ref-cross-branch-cancellation.yml

@@ -0,0 +1,62 @@
+id: concurrency-timing-037
+title: "Concurrency group key missing github.ref accidentally cancels runs on other branches"
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - concurrency
+  - cancel-in-progress
+  - github-ref
+  - branches
+  - cross-branch
+patterns:
+  - regex: 'cancelled because a more recent run with the same concurrency'
+    flags: "i"
+  - regex: 'This run was cancelled'
+    flags: "i"
+error_messages:
+  - "This run was cancelled because a more recent run with the same concurrency key is in progress"
+root_cause: |
+  When the concurrency group key is set to a static string or uses only github.workflow
+  without including github.ref, all branches share the same concurrency slot. A push to
+  any feature branch will cancel an in-progress run on main — or vice versa. With
+  cancel-in-progress: true, a developer's feature branch push can silently abort a
+  production branch deployment or a release CI run. The cancellation message ("This run
+  was cancelled because a more recent run with the same concurrency key is in progress")
+  gives no indication that the runs are on completely different branches. This is among the
+  most common misconfiguration in copy-pasted concurrency examples that omit github.ref.
+fix: |
+  Always include github.ref (or github.head_ref for pull_request events) in the concurrency
+  group key so each branch maintains its own independent concurrency slot. For pull requests,
+  use github.event.pull_request.number to prevent conflicts between simultaneously open PRs
+  targeting the same branch. For scheduled or manual workflows where github.ref is always
+  the same, use github.run_id to allow parallel runs.
+fix_code:
+  - language: yaml
+    label: "Include github.ref in the concurrency key to isolate each branch"
+    code: |
+      # WRONG — all branches share one concurrency slot, pushes to any branch
+      # cancel runs on all other branches
+      # concurrency:
+      #   group: ${{ github.workflow }}
+      #   cancel-in-progress: true
+
+      # CORRECT — each branch has its own independent concurrency slot
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.ref }}
+        cancel-in-progress: true
+
+      # For pull_request events, scope to the PR number for extra precision
+      # (prevents PR-A and PR-B from cancelling each other when both target main)
+      concurrency:
+        group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+        cancel-in-progress: true
+prevention:
+  - "Always include github.ref or github.head_ref in the concurrency group key"
+  - "For pull_request workflows, use github.event.pull_request.number || github.ref to scope to individual PRs"
+  - "Audit all workflow concurrency keys whenever enabling cancel-in-progress: true"
+  - "Use a unique prefix per workflow type (ci-, deploy-, lint-) to prevent cross-workflow collisions even when github.ref is included"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency"
+    label: "Using concurrency — GitHub Docs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#concurrency"
+    label: "Concurrency syntax — GitHub Docs"

package/errors/known-unsolved/composite-action-no-pre-post-lifecycle-hooks.yml

@@ -0,0 +1,94 @@
+id: known-unsolved-043
+title: 'Composite actions do not support pre: and post: lifecycle hooks — no guaranteed setup or cleanup code'
+category: known-unsolved
+severity: limitation
+tags:
+  - composite-action
+  - pre-step
+  - post-step
+  - cleanup
+  - lifecycle
+patterns:
+  - regex: 'Unexpected value ''pre'''
+    flags: 'i'
+  - regex: 'Unexpected value ''post'''
+    flags: 'i'
+error_messages:
+  - "Unexpected value 'pre'"
+  - "Unexpected value 'post'"
+  - 'pre: and post: are only supported in JavaScript and Docker container actions'
+root_cause: |
+  GitHub Actions supports pre: and post: lifecycle hooks in JavaScript actions (using: node20/node24)
+  and Docker container actions (using: docker). These hooks run before and after the main action
+  step respectively, and the post: hook runs even when the workflow is cancelled or fails —
+  making them ideal for guaranteed resource cleanup.
+
+  Composite actions (using: composite) do NOT support pre: or post: hooks. Attempting to add
+  pre: or post: to an action.yml with using: composite causes a validation error. This means
+  shell-based or Python-based composite actions cannot register guaranteed cleanup code that
+  runs after the job, regardless of success, failure, or cancellation.
+
+  Common affected patterns:
+  - Database seeding in setup steps that must be torn down in post:
+  - Port forwarding or tunnel setup that must be closed after the job
+  - Temporary credential setup that must be revoked after the workflow
+  - Cloud resource creation that must be deleted to avoid cost leaks
+fix: |
+  There is no direct fix — this is a known GitHub Actions platform limitation. Common workarounds:
+
+  Option A: Add explicit cleanup steps in calling workflows using if: always().
+  Option B: Wrap the composite logic in a thin JavaScript action that shells out to scripts,
+  enabling pre:/post: hook support.
+  Option C: Use a separate cleanup job with needs: [main-job] and if: always() for teardown.
+  Note: Option C adds latency and does not run on runner process kill.
+fix_code:
+  - language: yaml
+    label: 'Workaround: use if: always() cleanup step in the calling workflow'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Setup composite action
+              uses: ./.github/actions/my-composite-action
+
+            - name: Run build
+              run: make build
+
+            # Cleanup runs even if previous steps fail or are cancelled
+            - name: Cleanup resources
+              if: always()
+              run: |
+                echo "Cleaning up resources created by composite action..."
+                # teardown commands here
+
+  - language: yaml
+    label: 'Workaround: separate cleanup job guaranteed to run after main job'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: ./.github/actions/my-composite-action
+            - run: make build
+
+        cleanup:
+          runs-on: ubuntu-latest
+          needs: [build]
+          # Runs even when the build job fails or is cancelled
+          if: always()
+          steps:
+            - name: Teardown
+              run: |
+                echo "Running post-job cleanup..."
+prevention:
+  - "Design composite actions to be stateless and idempotent when possible — avoid side effects that require guaranteed cleanup"
+  - "Document in the composite action README that callers must add if: always() cleanup steps"
+  - "For actions that require guaranteed pre:/post: lifecycle hooks, consider wrapping in a JavaScript action"
+docs:
+  - url: 'https://github.com/actions/runner/issues/1478'
+    label: 'actions/runner#1478 — Support pre and post steps in Composite Actions (393 reactions)'
+  - url: 'https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-composite-actions'
+    label: 'Metadata syntax for composite actions — GitHub Docs'
+  - url: 'https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runspre'
+    label: 'pre: lifecycle hook — JavaScript and Docker actions only'

package/errors/runner-environment/docker-build-push-provenance-default-manifest-index.yml

@@ -0,0 +1,81 @@
+id: runner-environment-130
+title: 'docker/build-push-action default provenance: true pushes OCI image index for single-platform builds — breaks registries that do not support image indexes'
+category: runner-environment
+severity: silent-failure
+tags:
+  - docker
+  - build-push-action
+  - provenance
+  - oci
+  - manifest-index
+patterns:
+  - regex: 'manifest unknown'
+    flags: 'i'
+  - regex: 'unexpected status: \d{3}'
+    flags: 'i'
+error_messages:
+  - 'manifest unknown'
+  - 'unexpected status: 400'
+  - 'unexpected status: 403'
+root_cause: |
+  Starting with docker/build-push-action v4, the provenance input defaults to mode=min,
+  which attaches an SLSA provenance attestation to every pushed image. This causes the action
+  to push an OCI image index (manifest list) to the registry instead of a plain image manifest,
+  even for single-platform builds.
+
+  Registries and tools that do not support OCI image indexes may return "manifest unknown"
+  errors, return 400/403 HTTP responses, or silently resolve to an unexpected image variant.
+  Some container registries (such as older versions of GCR) display the provenance attestation
+  as a separate image entry with a creation timestamp of 0 epoch (Unix epoch), causing
+  confusion in image management dashboards.
+
+  The behavior is silent in successful-looking cases: the push completes without error, but
+  downstream 'docker pull' or 'FROM image:tag' in a Dockerfile may resolve the image index
+  instead of a plain image manifest, causing unexpected platform or size differences.
+fix: |
+  Set provenance: false in docker/build-push-action to restore plain image manifest behavior
+  for single-platform builds. If SLSA provenance is required, use actions/attest-build-provenance
+  as a separate step after the push.
+fix_code:
+  - language: yaml
+    label: 'Disable provenance to push plain image manifest for single-platform builds'
+    code: |
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
+          # Disable default provenance attestation to push a plain image manifest.
+          # Required for registries that do not support OCI image indexes.
+          provenance: false
+
+  - language: yaml
+    label: 'Add SLSA provenance separately using actions/attest-build-provenance'
+    code: |
+      - name: Build and push
+        id: push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
+          provenance: false
+
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@v2
+        with:
+          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          subject-digest: ${{ steps.push.outputs.digest }}
+          push-to-registry: true
+prevention:
+  - "Set 'provenance: false' in docker/build-push-action unless your target registry explicitly supports OCI image indexes"
+  - "Test image pulling from the registry after pushing to confirm the correct manifest type was stored"
+  - "Use 'docker manifest inspect' to verify the pushed image is a plain manifest and not a manifest index when provenance is enabled"
+docs:
+  - url: 'https://github.com/docker/build-push-action/issues/755'
+    label: 'docker/build-push-action#755 — Action started to push manifest indexes instead of images for a single platform'
+  - url: 'https://docs.docker.com/build/ci/github-actions/attestations/'
+    label: 'Docker build attestations with GitHub Actions'
+  - url: 'https://docs.docker.com/reference/cli/docker/buildx/build/#provenance'
+    label: 'docker buildx build --provenance flag documentation'

package/errors/runner-environment/setup-node-yarn-packagemanager-corepack-conflict.yml

@@ -0,0 +1,71 @@
+id: runner-environment-129
+title: 'setup-node cache: yarn fails when packageManager specifies Yarn 4 in package.json — Corepack version mismatch'
+category: runner-environment
+severity: error
+tags:
+  - setup-node
+  - yarn
+  - corepack
+  - packageManager
+  - package-json
+patterns:
+  - regex: 'Presence of the "packageManager" field indicates that the project is meant to be used with Corepack'
+    flags: 'i'
+  - regex: 'the current global version of Yarn is \d+\.\d+'
+    flags: 'i'
+error_messages:
+  - 'This project''s package.json defines "packageManager": "yarn@4.x.x". However the current global version of Yarn is 1.22.22.'
+  - 'Presence of the "packageManager" field indicates that the project is meant to be used with Corepack'
+root_cause: |
+  When package.json contains a "packageManager" field specifying Yarn 4 (e.g., "yarn@4.1.1"),
+  Yarn's integrity check detects the field and requires the project to be managed via Corepack.
+  The system Yarn installed on GitHub-hosted runners is Yarn Classic (1.x), which responds to
+  the "packageManager" constraint by throwing an error if Corepack is not enabled.
+
+  When actions/setup-node is configured with cache: 'yarn', it detects the "packageManager"
+  field, attempts to use the specified Yarn version via Corepack, but Corepack is not enabled
+  by default on GitHub-hosted runners. The resulting error prevents setup-node from completing
+  and fails the job before any build steps run.
+
+  This affects workflows being upgraded from Yarn Classic to Yarn 4 (Berry) via the
+  "packageManager" field in package.json, or projects that adopted the "packageManager"
+  field for strict version pinning.
+fix: |
+  Enable Corepack before running setup-node. Two options depending on your setup-node version:
+
+  Option A: Add a 'corepack enable' run step before setup-node (works with all versions).
+  Option B: Use 'enable-node-corepack: true' input (requires setup-node v4.2+).
+  Option C: Remove 'packageManager' from package.json and manage Yarn version via .yarnrc.yml only.
+fix_code:
+  - language: yaml
+    label: 'Enable Corepack before setup-node (Yarn 4 / Berry projects)'
+    code: |
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Set up Node.js with Yarn cache
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'yarn'
+
+  - language: yaml
+    label: 'Alternative: enable-node-corepack input (setup-node v4.2+)'
+    code: |
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'yarn'
+          enable-node-corepack: true
+prevention:
+  - "Always run 'corepack enable' before setup-node when package.json has a 'packageManager' field specifying Yarn 4+"
+  - "Verify Corepack is enabled before relying on setup-node's yarn cache integration in Yarn Berry projects"
+  - "Pin the Yarn version in .yarnrc.yml in addition to the packageManager field to ensure consistent resolution"
+docs:
+  - url: 'https://github.com/actions/setup-node/issues/1027'
+    label: 'actions/setup-node#1027 — If cache: yarn is specified, this action fails (38 reactions)'
+  - url: 'https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md#corepack'
+    label: 'setup-node advanced usage — Corepack support'
+  - url: 'https://yarnpkg.com/getting-started/install'
+    label: 'Yarn Berry — Installation via Corepack'

package/errors/triggers/schedule-workflow-disabled-on-fork.yml

@@ -0,0 +1,69 @@
+id: triggers-048
+title: 'Scheduled workflows silently disabled on forked repositories — on.schedule never fires until manually re-enabled in Settings'
+category: triggers
+severity: silent-failure
+tags:
+  - schedule
+  - fork
+  - workflow-disabled
+  - cron
+  - repository-settings
+patterns:
+  - regex: 'Scheduled workflows are disabled for this repository'
+    flags: 'i'
+  - regex: 'This workflow is disabled'
+    flags: 'i'
+error_messages:
+  - 'Scheduled workflows are disabled for this repository'
+  - 'This workflow is disabled'
+root_cause: |
+  When a repository containing scheduled workflows is forked, GitHub automatically disables
+  all workflow triggers in the fork. This prevents scheduled CI runs from unexpectedly
+  consuming GitHub Actions minutes from the fork owner's account and avoids unintended
+  side effects from cloned automation.
+
+  Scheduled workflows (on.schedule:) stop firing entirely on the fork, even if the workflow
+  YAML is correct and the branch is up to date. The workflow appears in the Actions tab and
+  can be triggered manually via workflow_dispatch, but on.schedule: events are suppressed.
+
+  This commonly affects:
+  - Contributors forking repos to test or contribute scheduled jobs (e.g., nightly builds,
+    dependency updates, scheduled reports)
+  - Organizations using forks as part of their branching or release strategy and expecting
+    scheduled maintenance tasks to continue
+  - CI setups where scheduled smoke tests or integration tests are part of the fork workflow
+
+  The only indicator is the workflow showing as "disabled" in the Actions tab or in the
+  workflow run history, which is easy to miss.
+fix: |
+  Navigate to the fork repository and enable workflows manually:
+  Settings (fork repo) -> Actions -> General -> Allow all actions and reusable workflows.
+  Then enable the specific workflow in the Actions tab by clicking "Enable workflow".
+  There is no workflow-level or API-level way to force-enable schedules on a fork automatically.
+fix_code:
+  - language: yaml
+    label: 'Add workflow_dispatch fallback so contributors can trigger manually on forks'
+    code: |
+      on:
+        # Note: scheduled runs are DISABLED on forked repositories by default.
+        # Contributors must enable workflows in Settings -> Actions -> General.
+        schedule:
+          - cron: '0 2 * * *'
+
+        # Add workflow_dispatch as a fallback for manual triggering on forks
+        workflow_dispatch:
+          inputs:
+            reason:
+              description: 'Reason for manual run (required when testing on a fork)'
+              required: false
+              default: 'manual trigger'
+
+prevention:
+  - "Document in CONTRIBUTING.md that scheduled workflows must be manually enabled on forks via Settings -> Actions -> General"
+  - "Add workflow_dispatch to all scheduled workflows so contributors can manually trigger them on forks during development"
+  - "Use repository_dispatch or workflow_run from the upstream repo to trigger downstream automation instead of relying on fork schedules"
+docs:
+  - url: 'https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/disabling-and-enabling-a-workflow'
+    label: 'Disabling and enabling a workflow — GitHub Docs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule'
+    label: 'schedule event — GitHub Docs'

package/errors/yaml-syntax/run-block-scalar-folded-gt-collapses-newlines.yml

@@ -0,0 +1,76 @@
+id: yaml-syntax-044
+title: "run: > (folded block scalar) collapses newlines to spaces — multi-line shell scripts break silently"
+category: yaml-syntax
+severity: error
+tags:
+  - yaml
+  - run
+  - block-scalar
+  - multiline
+  - shell
+  - folded
+patterns:
+  - regex: 'syntax error near unexpected token'
+    flags: "i"
+  - regex: 'command not found'
+    flags: "i"
+  - regex: 'unexpected EOF while looking for matching'
+    flags: "i"
+error_messages:
+  - "syntax error near unexpected token"
+  - "command not found"
+  - "unexpected EOF while looking for matching `\"'"
+root_cause: |
+  YAML has two block scalar indicators: | (literal) preserves newlines exactly, while >
+  (folded) collapses newlines between non-empty lines into a single space. When a GitHub
+  Actions run: block uses > instead of |, every line break in the shell script becomes a
+  space. Multi-line scripts are silently concatenated into a single command that the shell
+  cannot parse, producing confusing errors like "syntax error near unexpected token" or
+  "command not found" pointing to the wrong line.
+
+  This is especially common when:
+  - Developers copy YAML examples from documentation that use > for prose (not scripts)
+  - IDEs or formatters suggest > to reduce visual indentation
+  - Developers confuse > (folded) and | (literal) because both produce multi-line blocks
+
+  Example: a three-line script becomes one run-together line:
+    # With run: >       becomes: echo "start"   VAR=hello   echo "$VAR"
+    # With run: |       becomes: echo "start" \n VAR=hello \n echo "$VAR"  (correct)
+fix: |
+  Always use | (pipe / literal block scalar) for run: steps that contain shell scripts.
+  The | indicator preserves newlines exactly as written. The > indicator should only be
+  used for prose strings (e.g., long error messages or descriptions) where newline
+  collapsing is intentional.
+fix_code:
+  - language: yaml
+    label: "Use | (literal) not > (folded) for run: shell scripts"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            # WRONG — > folds newlines into spaces, script becomes one broken command
+            # - name: Build
+            #   run: >
+            #     echo "Starting build"
+            #     npm install
+            #     npm run build
+
+            # CORRECT — | preserves newlines, each command runs on its own line
+            - name: Build
+              run: |
+                echo "Starting build"
+                npm install
+                npm run build
+prevention:
+  - "Always use | (literal block scalar) for run: blocks containing shell scripts"
+  - "Reserve > (folded block scalar) for non-executable prose strings only"
+  - "Enable a YAML linter (e.g., actionlint, yamllint) in pre-commit hooks to catch > in run: blocks"
+  - "When in doubt: | keeps lines as lines; > joins lines with spaces"
+docs:
+  - url: "https://yaml.org/spec/1.2.2/#chapter-8-block-style-productions"
+    label: "YAML block scalar styles — YAML spec"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun"
+    label: "jobs.<id>.steps[*].run — GitHub Docs"
+  - 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.67",
+  "version": "1.0.69",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",