@htekdev/actions-debugger 1.0.66 → 1.0.68

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/self-hosted-runner-stuck-queued-no-timeout.yml

@@ -0,0 +1,73 @@
+id: known-unsolved-042
+title: 'Job queues indefinitely when no self-hosted runner matches labels — no automatic queue-wait timeout'
+category: known-unsolved
+severity: limitation
+tags:
+  - self-hosted
+  - queued
+  - runner-labels
+  - timeout
+  - stuck-job
+patterns:
+  - regex: 'Waiting for a runner to pick up this job'
+    flags: 'i'
+  - regex: 'Job is waiting for a hosted runner to come online'
+    flags: 'i'
+error_messages:
+  - 'Waiting for a runner to pick up this job'
+  - 'Job is waiting for a hosted runner to come online'
+root_cause: |
+  When a job specifies runs-on: self-hosted (or a label array containing self-hosted),
+  GitHub places the job in a queue and waits for a matching runner to become available.
+  If no registered runner matches all required labels — because the runner is offline,
+  deregistered, at capacity, or the labels are mistyped — the job remains in "Queued"
+  state indefinitely with the message "Waiting for a runner to pick up this job."
+
+  GitHub does not apply an automatic queue-wait timeout. The only enforced limit is the
+  overall workflow timeout-minutes (default 360 minutes, maximum 35 days for self-hosted
+  runners). Runner labels are matched case-sensitively, so [self-hosted, Linux] does not
+  match a runner registered as [self-hosted, linux].
+
+  This is a recurring GitHub Community request: developers frequently discover queued jobs
+  hours or days later after expecting fast CI feedback.
+fix: |
+  There is no GitHub-native queue-wait timeout distinct from job runtime. Mitigations:
+  1. Add timeout-minutes at the job level to cap total job time including queue wait
+  2. Verify runner label spellings exactly match labels registered on the runner
+     (Settings → Actions → Runners shows registered labels)
+  3. Ensure at least one runner with all required labels is online and idle
+  4. Use ephemeral (JIT) runners with auto-scaling to prevent capacity exhaustion
+fix_code:
+  - language: yaml
+    label: 'Add timeout-minutes to fail fast when no runner is available'
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, linux, x64]
+          timeout-minutes: 30    # job fails if no runner picks it up within 30 minutes
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+  - language: yaml
+    label: 'Fallback to GitHub-hosted runner when self-hosted is unavailable'
+    code: |
+      jobs:
+        build:
+          runs-on: ${{ vars.USE_SELF_HOSTED == 'true' && fromJSON('["self-hosted","linux","x64"]') || 'ubuntu-latest' }}
+          timeout-minutes: 60
+          steps:
+            - uses: actions/checkout@v4
+            - run: make build
+prevention:
+  - 'Always set timeout-minutes on self-hosted runner jobs to prevent indefinite queuing'
+  - 'Verify runner labels match exactly — labels are case-sensitive (Linux vs linux)'
+  - 'Monitor runner pool health at Settings → Actions → Runners and alert on all-offline conditions'
+  - 'Use ephemeral (JIT) runners with auto-scaling to ensure available capacity on demand'
+  - 'Consider GitHub-hosted runner fallback for critical workflows'
+docs:
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-labels'
+    label: 'Self-hosted runner labels — GitHub Docs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes'
+    label: 'jobs.<job>.timeout-minutes — GitHub Docs'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners'
+    label: 'Autoscaling with self-hosted runners — GitHub Docs'

package/errors/silent-failures/actions-runner-debug-must-be-secret-not-variable.yml

@@ -0,0 +1,62 @@
+id: silent-failures-066
+title: 'ACTIONS_RUNNER_DEBUG and ACTIONS_STEP_DEBUG must be repository secrets, not variables'
+category: silent-failures
+severity: silent-failure
+tags:
+  - debug-logging
+  - ACTIONS_RUNNER_DEBUG
+  - ACTIONS_STEP_DEBUG
+  - secrets
+  - variables
+  - troubleshooting
+patterns:
+  - regex: 'ACTIONS_RUNNER_DEBUG|ACTIONS_STEP_DEBUG'
+    flags: 'i'
+error_messages:
+  - 'No additional debug output despite ACTIONS_RUNNER_DEBUG=true'
+  - 'Debug logging not enabled even though variable is set to true'
+root_cause: |
+  GitHub Actions checks ACTIONS_RUNNER_DEBUG and ACTIONS_STEP_DEBUG only when they are
+  set as repository or organization secrets. Setting them as repository variables
+  (Settings → Secrets and variables → Actions → Variables tab) has no effect whatsoever.
+  The runner bootstrap reads debug flags from the secrets store before variable contexts
+  are available, so a vars.ACTIONS_RUNNER_DEBUG reference inside the workflow YAML is
+  also ineffective. No warning is emitted when the variable exists but the corresponding
+  secret does not — the runner simply operates in non-debug mode silently.
+fix: |
+  Set ACTIONS_RUNNER_DEBUG and/or ACTIONS_STEP_DEBUG as repository secrets (not variables)
+  with the value "true":
+
+    Settings → Secrets and variables → Actions → Secrets tab → New repository secret
+      Name:  ACTIONS_RUNNER_DEBUG
+      Value: true
+
+  Alternatively, use the "Re-run jobs" UI button and check "Enable debug logging" for a
+  one-time debug run without creating a permanent secret.
+fix_code:
+  - language: yaml
+    label: 'Debug flags require repository secrets — no workflow YAML change needed'
+    code: |
+      # Create these as repository SECRETS (not Variables):
+      #   ACTIONS_RUNNER_DEBUG = true   (verbose runner diagnostic logs)
+      #   ACTIONS_STEP_DEBUG   = true   (verbose step-level output including set-output calls)
+      #
+      # Setting them under the Variables tab has NO effect.
+      # For one-off debugging use "Re-run jobs" → check "Enable debug logging".
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "Runner debug active when ACTIONS_RUNNER_DEBUG secret = true"
+prevention:
+  - 'Set ACTIONS_RUNNER_DEBUG and ACTIONS_STEP_DEBUG as Secrets, not Variables'
+  - 'Use the Re-run with debug logging checkbox for temporary one-off debugging'
+  - 'Check the Secrets tab — not the Variables tab — under Settings → Secrets and variables → Actions'
+  - 'Remember: debug flags are read during runner bootstrap before the vars context is available'
+docs:
+  - url: 'https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/troubleshooting-workflows/enabling-debug-logging'
+    label: 'Enabling debug logging — GitHub Docs'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions'
+    label: 'Using secrets in GitHub Actions — GitHub Docs'

package/errors/silent-failures/working-directory-ignored-on-uses-steps.yml

@@ -0,0 +1,80 @@
+id: silent-failures-067
+title: 'working-directory on a uses: step is silently ignored — only applies to run: steps'
+category: silent-failures
+severity: silent-failure
+tags:
+  - working-directory
+  - uses
+  - composite-action
+  - run
+  - path
+  - configuration
+patterns:
+  - regex: 'Error.*ENOENT.*no such file or directory'
+    flags: 'i'
+  - regex: 'No such file or directory'
+    flags: 'i'
+error_messages:
+  - 'Action runs from workspace root instead of specified working-directory'
+  - 'ENOENT: no such file or directory — action ignoring working-directory set on uses: step'
+root_cause: |
+  The step-level working-directory property only affects run: steps that execute shell
+  commands. Steps that use the uses: keyword to invoke an action — whether a JavaScript
+  action, Docker action, or composite action — silently ignore working-directory. The
+  property is discarded with no warning logged. The action runs from GITHUB_WORKSPACE
+  (the repository root) or from the action's own directory, not the directory specified
+  on the step.
+
+  This is a documented GitHub Actions limitation that surprises many developers who expect
+  working-directory to behave like a cd command applied to the entire step, regardless of
+  step type. It is one of the most common "action runs in wrong directory" reports on GitHub
+  Community Discussions.
+fix: |
+  Pass the desired directory as an explicit input to the action. For run: steps in the same
+  job, use defaults.run.working-directory at the job level. Do not set working-directory on
+  uses: steps — it is silently discarded.
+fix_code:
+  - language: yaml
+    label: 'Use job-level defaults.run for run steps; pass input for uses steps'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          defaults:
+            run:
+              working-directory: ./packages/my-app   # applies to all run: steps only
+
+          steps:
+            - uses: actions/checkout@v4
+
+            - run: npm install      # runs in ./packages/my-app ✓
+
+            # For uses: steps, pass the directory as an explicit action input:
+            - uses: ./.github/actions/my-action
+              with:
+                working-directory: ./packages/my-app   # action must accept this input
+  - language: yaml
+    label: 'Composite action: declare working-directory as an input'
+    code: |
+      # In .github/actions/my-action/action.yml:
+      inputs:
+        working-directory:
+          description: 'Directory to run in'
+          default: '.'
+      runs:
+        using: composite
+        steps:
+          - run: npm test
+            shell: bash
+            working-directory: ${{ inputs.working-directory }}
+prevention:
+  - 'Never set working-directory on steps that use uses: — it is silently ignored'
+  - 'For composite actions that need a target directory, declare an explicit working-directory input'
+  - 'Use defaults.run.working-directory at job level to apply a directory to all run: steps'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsworking-directory'
+    label: 'steps[*].working-directory — GitHub Docs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#defaultsrun'
+    label: 'defaults.run — GitHub Docs'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action'
+    label: 'Creating a composite action — GitHub Docs'

package/errors/triggers/pull-request-ready-for-review-type-missing.yml

@@ -0,0 +1,58 @@
+id: triggers-047
+title: 'pull_request default types exclude ready_for_review — draft-to-ready conversion skips CI'
+category: triggers
+severity: warning
+tags:
+  - pull_request
+  - draft
+  - ready_for_review
+  - types
+  - required-status-checks
+patterns:
+  - regex: 'on:\s*\n\s*pull_request\s*:'
+    flags: 'im'
+  - regex: 'pull_request\s*:\s*\n(?!\s*types)'
+    flags: 'im'
+error_messages:
+  - 'CI not triggered after converting draft pull request to ready for review'
+  - 'Required status check never ran after marking PR ready — branch protection blocking merge'
+root_cause: |
+  The pull_request event with no explicit types: list defaults to the activity types
+  [opened, synchronize, reopened]. When a contributor converts a draft PR to ready
+  for review, GitHub fires the ready_for_review activity type, which is absent from
+  the default set. The workflow never executes for this state transition, leaving the
+  PR without the required CI status checks. Branch protection rules then block merging
+  until the next push re-triggers CI.
+
+  This is one of the most frequently reported CI surprises in GitHub Community discussions,
+  particularly for teams that rely on draft PRs for work-in-progress reviews.
+fix: |
+  Explicitly declare the types list on the pull_request trigger and add ready_for_review:
+fix_code:
+  - language: yaml
+    label: 'Add ready_for_review to pull_request types'
+    code: |
+      on:
+        pull_request:
+          types:
+            - opened
+            - synchronize
+            - reopened
+            - ready_for_review    # fires when a draft PR is marked ready for review
+
+      jobs:
+        ci:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+prevention:
+  - 'Always explicitly list pull_request types when your team uses draft PRs'
+  - 'Add ready_for_review when branch protection requires CI to pass before merge'
+  - 'Include converted_to_draft to re-trigger (or block) CI when PRs return to draft'
+  - 'Review required status check names after adding new trigger types to confirm they register'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request'
+    label: 'pull_request event types — GitHub Docs'
+  - url: 'https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request'
+    label: 'Changing the stage of a pull request — 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.66",
+  "version": "1.0.68",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",