@htekdev/actions-debugger 1.0.84 → 1.0.86

package/errors/caching-artifacts/docker-buildx-gha-cache-mode-min-partial-layers.yml

@@ -0,0 +1,91 @@
+id: caching-artifacts-049
+title: 'Docker buildx GHA cache mode:min only caches final layer — rebuilds remain slow'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - docker
+  - buildx
+  - gha-cache
+  - layer-cache
+  - mode-min
+  - silent-failure
+patterns:
+  - regex: 'cache-to.*type=gha'
+    flags: 'i'
+  - regex: 'importing\s+cache\s+manifest\s+from\s+ghcr\.io'
+    flags: 'i'
+  - regex: 'exporting\s+cache\s+.*\s+type=gha'
+    flags: 'i'
+error_messages:
+  - 'cache-to: type=gha'
+  - 'exporting cache to GitHub Actions Cache Service'
+  - 'CACHED [stage 2/4]'
+root_cause: |
+  docker/build-push-action uses cache-to: type=gha with mode=min by default when
+  no explicit mode is specified. In min mode, BuildKit exports ONLY the layers of
+  the final image (the last build stage), discarding all intermediate layer cache
+  data. This means:
+
+  - Multi-stage Dockerfiles get no benefit from the GHA cache for base/dependency
+    stages (the expensive ones) — only the final artifact stage is cached.
+  - Subsequent runs re-execute all intermediate stages from scratch while the
+    cache appears to "work" (export/import steps succeed in the logs).
+  - Developers see 80-90% cache miss rates and slow builds despite believing the
+    GHA cache is active.
+
+  The silent aspect: the workflow logs show cache export and import succeeding,
+  and BuildKit reports "CACHED" for layers it finds, with no warning that intermediate
+  stages were excluded from the cache.
+fix: |
+  Explicitly set mode=max on the cache-to option. This instructs BuildKit to export
+  ALL layer metadata — including every intermediate build stage — into the GHA cache.
+  Combined with cache-from: type=gha, all previously-built stages will be restored
+  on the next run.
+
+  Note: mode=max requires more GHA cache storage (subject to the 10 GB repository
+  limit). Use separate cache scopes per Dockerfile or build target to prevent
+  cross-contamination and LRU eviction pressure.
+fix_code:
+  - language: yaml
+    label: 'Set mode=max for full layer caching in multi-stage builds'
+    code: |
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ghcr.io/${{ github.repository }}:latest
+          cache-from: type=gha,scope=main
+          cache-to: type=gha,scope=main,mode=max
+  - language: yaml
+    label: 'Use separate scopes per Dockerfile to isolate caches'
+    code: |
+      - name: Build API image
+        uses: docker/build-push-action@v6
+        with:
+          context: ./api
+          push: true
+          tags: ghcr.io/${{ github.repository }}/api:latest
+          cache-from: type=gha,scope=api
+          cache-to: type=gha,scope=api,mode=max
+
+      - name: Build Frontend image
+        uses: docker/build-push-action@v6
+        with:
+          context: ./frontend
+          push: true
+          tags: ghcr.io/${{ github.repository }}/frontend:latest
+          cache-from: type=gha,scope=frontend
+          cache-to: type=gha,scope=frontend,mode=max
+prevention:
+  - 'Always explicitly set mode=max in cache-to: type=gha for multi-stage Dockerfiles'
+  - 'Use the scope= parameter to isolate caches per Dockerfile or build target'
+  - 'Monitor cache size with the GitHub Actions Cache API if approaching the 10 GB repository limit'
+  - 'Verify cache effectiveness by checking that intermediate build stages show CACHED in buildx output'
+docs:
+  - url: 'https://docs.docker.com/build/cache/backends/gha/'
+    label: 'Docker BuildKit — GitHub Actions cache backend'
+  - url: 'https://github.com/docker/build-push-action#cache'
+    label: 'docker/build-push-action — Cache inputs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#usage-limits-and-eviction-policy'
+    label: 'GitHub Actions — Cache usage limits and eviction policy'

package/errors/caching-artifacts/upload-artifact-storage-quota-exceeded.yml

@@ -0,0 +1,76 @@
+id: caching-artifacts-050
+title: "upload-artifact@v4 fails when artifact storage quota is exceeded"
+category: caching-artifacts
+severity: error
+tags:
+  - upload-artifact
+  - storage-quota
+  - v4
+  - billing
+  - artifact-cleanup
+patterns:
+  - regex: 'Artifact storage quota has been hit'
+    flags: i
+  - regex: 'unable to upload any new artifacts'
+    flags: i
+  - regex: 'storage limit.*exceeded'
+    flags: i
+error_messages:
+  - "Artifact storage quota has been hit, unable to upload any new artifacts. Please remove some old artifacts or increase storage for the repo."
+root_cause: |
+  GitHub Actions artifact storage has per-account limits (500 MB for free plans, 2 GB for Pro,
+  50 GB for Teams, and custom limits for Enterprise). Unlike actions/upload-artifact@v3 which
+  used a legacy backend, v4 strictly enforces storage quotas and fails hard when the limit
+  is exceeded. Old artifacts from previous workflow runs accumulate over time and are not
+  automatically purged unless a retention policy is set. Once the quota is hit, all subsequent
+  artifact uploads fail immediately with no partial upload.
+fix: |
+  1. Set retention-days on all upload-artifact steps to automatically expire old artifacts.
+  2. Delete old artifacts programmatically using the GitHub REST API via actions/github-script.
+  3. Increase artifact and log storage in GitHub billing settings (Org/User Settings -> Billing -> Storage).
+  4. Audit artifact size — only upload what is necessary for debugging or downstream jobs.
+fix_code:
+  - language: yaml
+    label: "Set retention-days to auto-expire artifacts"
+    code: |
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: dist/
+          retention-days: 7   # auto-delete after 7 days; default is 90
+
+  - language: yaml
+    label: "Delete artifacts older than 30 days via GitHub API script"
+    code: |
+      - name: Clean up old artifacts
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const cutoff = new Date();
+            cutoff.setDate(cutoff.getDate() - 30);
+            const artifacts = await github.paginate(
+              github.rest.actions.listArtifactsForRepo,
+              { owner: context.repo.owner, repo: context.repo.repo, per_page: 100 }
+            );
+            for (const artifact of artifacts) {
+              if (new Date(artifact.created_at) < cutoff) {
+                await github.rest.actions.deleteArtifact({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  artifact_id: artifact.id,
+                });
+              }
+            }
+prevention:
+  - "Always set retention-days on upload-artifact steps — default is 90 days which fills storage quickly"
+  - "Upload only the minimum files needed for debugging or downstream jobs, not entire build directories"
+  - "Add a weekly scheduled workflow to delete artifacts older than your retention window"
+  - "Monitor storage usage under GitHub Settings -> Billing & plans -> Storage"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-workflow-data-as-artifacts#configuring-a-custom-artifact-retention-period"
+    label: "GitHub Docs: Custom artifact retention period"
+  - url: "https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-actions/about-billing-for-github-actions#included-storage-and-minutes"
+    label: "GitHub Docs: Included storage and minutes"
+  - url: "https://github.com/actions/upload-artifact/issues/577"
+    label: "actions/upload-artifact#577: Storage quota exceeded on v4"

package/errors/concurrency-timing/schedule-cron-no-concurrency-run-overlap.yml

@@ -0,0 +1,87 @@
+id: concurrency-timing-043
+title: 'Scheduled cron jobs overlap when no concurrency group is configured'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - schedule
+  - cron
+  - overlap
+  - race-condition
+  - concurrency
+  - data-corruption
+patterns:
+  - regex: 'on:\s*schedule'
+    flags: 'i'
+  - regex: 'triggered by:\s*schedule'
+    flags: 'i'
+error_messages:
+  - 'Multiple workflow runs triggered by schedule are running concurrently'
+  - 'triggered by: schedule'
+root_cause: |
+  When a scheduled workflow has no concurrency group configured, GitHub Actions
+  starts a new run at each scheduled time regardless of whether a previous run is
+  still in progress. Two conditions make this especially common:
+
+  1. The job takes longer than the cron interval (e.g., a 10-minute job on a
+     every-5-minute schedule).
+  2. GitHub's scheduler fires queued runs in rapid succession after a platform
+     outage or maintenance window, catching up on missed intervals.
+
+  Both scenarios result in multiple simultaneous runs sharing external resources—
+  databases, S3 buckets, deployment targets, or branch state—causing race
+  conditions, duplicate data writes, and data corruption. No error is surfaced
+  in the workflow logs; the runs both appear green while the downstream system
+  silently degrades.
+fix: |
+  Add a concurrency group to the scheduled workflow. The correct cancel-in-progress
+  value depends on whether the job is idempotent:
+
+  - Non-idempotent jobs (database migrations, state mutations): set
+    cancel-in-progress: false to queue runs sequentially.
+  - Idempotent jobs (report generation, cache refreshes): set
+    cancel-in-progress: true to drop stale queued runs and keep only the latest.
+fix_code:
+  - language: yaml
+    label: 'Queue scheduled runs for non-idempotent jobs (e.g., database migrations)'
+    code: |
+      on:
+        schedule:
+          - cron: '*/5 * * * *'
+
+      concurrency:
+        group: ${{ github.workflow }}-scheduled
+        cancel-in-progress: false
+
+      jobs:
+        migrate:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./scripts/db-migrate.sh
+  - language: yaml
+    label: 'Cancel stale runs for idempotent jobs (e.g., report generation)'
+    code: |
+      on:
+        schedule:
+          - cron: '*/5 * * * *'
+
+      concurrency:
+        group: ${{ github.workflow }}-scheduled
+        cancel-in-progress: true
+
+      jobs:
+        report:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./scripts/generate-report.sh
+prevention:
+  - 'Add a concurrency group to every workflow with an on.schedule trigger'
+  - 'For jobs longer than the cron interval, always use cancel-in-progress: false to serialize execution'
+  - 'Monitor the Actions tab for multiple simultaneous scheduled runs as an early warning sign'
+  - 'Use actionlint to audit workflows that have on.schedule but no concurrency group'
+docs:
+  - url: 'https://docs.github.com/en/actions/using-jobs/using-concurrency'
+    label: 'GitHub Actions — Using concurrency'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule'
+    label: 'GitHub Actions — Schedule event'

package/errors/permissions-auth/fine-grained-pat-resource-owner-mismatch.yml

@@ -0,0 +1,75 @@
+id: permissions-auth-050
+title: "Fine-grained PAT with wrong resource owner causes 'repository not found' in checkout"
+category: permissions-auth
+severity: error
+tags:
+  - fine-grained-pat
+  - checkout
+  - resource-owner
+  - PAT
+  - authentication
+patterns:
+  - regex: 'repository.*not found'
+    flags: i
+  - regex: 'remote: Repository not found'
+    flags: i
+  - regex: 'fatal: unable to access.*403'
+    flags: i
+error_messages:
+  - "fatal: repository 'https://github.com/org/repo.git/' not found"
+  - "remote: Repository not found."
+  - "Error: fatal: unable to access 'https://github.com/org/repo.git/': The requested URL returned error: 403"
+root_cause: |
+  Fine-grained personal access tokens (PATs) require selecting a resource owner when created —
+  either your personal account or a specific organization. A token scoped to a personal account
+  (e.g., user alice) cannot authenticate to repositories owned by an organization (e.g., myorg),
+  even if alice is a member of myorg with full access. Attempting to use such a PAT in
+  actions/checkout, actions/github-script REST calls, or any GitHub API call targeting the
+  organization's repos results in a misleading "repository not found" or HTTP 403 error. The
+  repository is accessible through the web UI because browser sessions use OAuth-based auth —
+  but the fine-grained PAT token is strictly limited to its configured resource owner scope.
+  Classic PATs (without granular resource scope) do not have this restriction, which is why
+  the problem only appears after migrating to fine-grained PATs.
+fix: |
+  Regenerate the fine-grained PAT selecting the correct resource owner — the organization or
+  user account that owns the target repository. If you need to access repositories across
+  multiple organizations, create one PAT per organization, or use a GitHub App installation
+  token which supports cross-repo access without resource-owner restrictions.
+fix_code:
+  - language: yaml
+    label: "Checkout org repo — PAT must have org as resource owner"
+    code: |
+      # The secret ORG_SCOPED_PAT must be a fine-grained PAT created with
+      # Resource owner = myorg (not your personal account)
+      - uses: actions/checkout@v4
+        with:
+          repository: myorg/private-repo
+          token: ${{ secrets.ORG_SCOPED_PAT }}
+
+  - language: yaml
+    label: "Use a GitHub App installation token to avoid resource-owner scope issues"
+    code: |
+      - name: Generate app installation token
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ vars.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+          owner: myorg
+
+      - uses: actions/checkout@v4
+        with:
+          repository: myorg/private-repo
+          token: ${{ steps.app-token.outputs.token }}
+prevention:
+  - "When creating a fine-grained PAT, verify the Resource owner dropdown matches the organization or user that OWNS the target repository"
+  - "Name secrets descriptively: ORG_SCOPED_PAT vs USER_SCOPED_PAT to avoid mixing tokens with different owners"
+  - "Prefer GitHub App installation tokens for multi-repo or cross-org access — they have no resource-owner scoping restriction"
+  - "Classic PATs (repo scope) remain an option if fine-grained token resource-owner scoping is causing confusion"
+docs:
+  - url: "https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token"
+    label: "GitHub Docs: Creating a fine-grained personal access token"
+  - url: "https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#about-fine-grained-personal-access-tokens"
+    label: "GitHub Docs: About fine-grained PATs and resource owner scope"
+  - url: "https://github.com/actions/checkout?tab=readme-ov-file#checkout-a-different-private-repository"
+    label: "actions/checkout: Checkout a different private repository"

package/errors/permissions-auth/github-token-no-cross-org-private-action-access.yml

@@ -0,0 +1,95 @@
+id: permissions-auth-049
+title: 'GITHUB_TOKEN cannot resolve private actions from a different organization'
+category: permissions-auth
+severity: error
+tags:
+  - github-token
+  - cross-org
+  - private-action
+  - enterprise
+  - repository-not-found
+patterns:
+  - regex: 'Unable to resolve action .* repository not found'
+    flags: 'i'
+  - regex: 'Error: Unable to resolve action `[^`]+`'
+    flags: 'i'
+  - regex: 'remote: Repository not found'
+    flags: 'i'
+error_messages:
+  - "Error: Unable to resolve action `other-org/private-action@v1`, repository not found."
+  - "Error: remote: Repository not found."
+  - "fatal: repository 'https://github.com/other-org/private-action/' not found"
+root_cause: |
+  GITHUB_TOKEN is automatically scoped to the repository where the workflow runs.
+  It cannot authenticate against repositories in a different GitHub organization,
+  even when both organizations are in the same GitHub Enterprise instance.
+
+  When a workflow references a private action from a different org
+  (e.g., uses: other-org/my-action@v1), the Actions runner attempts to clone
+  that action repository during the job setup phase using GITHUB_TOKEN. The
+  clone fails with "repository not found" because the token has no cross-org
+  read access. This is not a permissions: block misconfiguration — no amount of
+  permissions granted in the workflow YAML will fix it, since the token is
+  fundamentally scoped to the calling org.
+
+  This also affects actions/checkout when checking out code from a private repo
+  in another org unless a suitable alternative token is provided.
+fix: |
+  Choose the appropriate strategy based on your setup:
+
+  1. Make the action repository public — simplest if the action contains no secrets.
+  2. Vendor the action into your organization — copy the action code into a repo
+     in the same org or into .github/actions/ in the calling repo and reference it
+     as a local path action.
+  3. Use a GitHub App installation token with cross-org permissions for
+     actions/checkout calls to cross-org repos (does NOT fix job-level uses: loading).
+  4. Use a Personal Access Token (PAT) with access to both orgs for checkout
+     (same limitation: cannot fix uses: loading, only checkout steps).
+
+  Note: The uses: field at the job-steps level (for external actions) is resolved
+  before the workflow starts executing, so token injection via steps is not possible
+  for the action loading stage — vendoring or making the action public is the only
+  reliable fix for job-level uses:.
+fix_code:
+  - language: yaml
+    label: 'Vendor private action as a local path action'
+    code: |
+      # Copy the action code to .github/actions/my-action/ in your repo.
+      # Then reference it as a local action — no cross-org token required:
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: ./.github/actions/my-action
+              with:
+                param: value
+  - language: yaml
+    label: 'Use GitHub App token for cross-org repository checkout (not uses: loading)'
+    code: |
+      jobs:
+        cross-org-checkout:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/create-github-app-token@v2
+              id: app-token
+              with:
+                app-id: ${{ vars.APP_ID }}
+                private-key: ${{ secrets.APP_PRIVATE_KEY }}
+                owner: other-org
+            - uses: actions/checkout@v4
+              with:
+                repository: other-org/private-repo
+                token: ${{ steps.app-token.outputs.token }}
+prevention:
+  - 'Prefer public actions for shared tooling to avoid cross-org token scope issues'
+  - 'Vendor private cross-org actions into .github/actions/ in the calling repo'
+  - 'Create an internal shared-actions org accessible to all teams where GITHUB_TOKEN works'
+  - 'Document which repos depend on cross-org private actions and track them for access reviews'
+docs:
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token'
+    label: 'GitHub Actions — Automatic token authentication permissions'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/creating-actions/sharing-actions-and-workflows-with-your-organization'
+    label: 'GitHub Actions — Sharing actions with your organization'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsuses'
+    label: 'GitHub Actions — Workflow syntax for uses'

package/errors/runner-environment/github-script-require-relative-path-cwd.yml

@@ -0,0 +1,74 @@
+id: runner-environment-150
+title: "actions/github-script relative require() fails — CWD is not GITHUB_WORKSPACE"
+category: runner-environment
+severity: error
+tags:
+  - github-script
+  - require
+  - nodejs
+  - working-directory
+  - module-not-found
+patterns:
+  - regex: 'Cannot find module'
+    flags: i
+  - regex: 'MODULE_NOT_FOUND'
+    flags: ''
+error_messages:
+  - "Error: Cannot find module './my-helper'"
+  - "Error: Cannot find module '../utils/helper'"
+  - "{ code: 'MODULE_NOT_FOUND' }"
+root_cause: |
+  The actions/github-script action evaluates the script: block in a Node.js context where the
+  current working directory (CWD) is a temporary internal directory used by the action runtime —
+  NOT $GITHUB_WORKSPACE. As a result, relative require() calls like require('./helpers/my-util')
+  fail with "Cannot find module" even when the file exists in the repository workspace. This
+  surprises developers who assume the script evaluates from the repository root directory.
+  Note: This is distinct from missing npm packages (runner-environment-136) — the file exists
+  on disk but is not found because Node.js resolves the relative path from the wrong base directory.
+fix: |
+  Construct an absolute path using process.env.GITHUB_WORKSPACE before calling require(). The
+  GITHUB_WORKSPACE environment variable is always set to the repository root in hosted runners.
+  Alternatively, use the recommended pattern from the actions/github-script docs: point to the
+  absolute path via a template literal.
+fix_code:
+  - language: yaml
+    label: "Use absolute path via process.env.GITHUB_WORKSPACE"
+    code: |
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const myHelper = require(`${process.env.GITHUB_WORKSPACE}/scripts/my-helper.js`);
+            await myHelper.run(github, context);
+
+  - language: yaml
+    label: "Pass workspace as env var for explicit clarity"
+    code: |
+      - uses: actions/github-script@v7
+        env:
+          WORKSPACE: ${{ github.workspace }}
+        with:
+          script: |
+            const helper = require(`${process.env.WORKSPACE}/scripts/helper.js`);
+            const result = helper.compute();
+            core.setOutput('result', result);
+
+  - language: yaml
+    label: "Use path.resolve for cross-platform safety"
+    code: |
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const path = require('path');
+            const utils = require(path.resolve(process.env.GITHUB_WORKSPACE, 'lib', 'utils.js'));
+            utils.run();
+prevention:
+  - "Never use relative require() paths in github-script — always construct absolute paths with process.env.GITHUB_WORKSPACE"
+  - "Print process.cwd() in debug runs to confirm the actual CWD — it will not be your repo root"
+  - "For complex shared logic, consider a composite action or a dedicated JS action that has proper module resolution"
+docs:
+  - url: "https://github.com/actions/github-script?tab=readme-ov-file#run-a-separate-file"
+    label: "actions/github-script: Run a separate file (recommended pattern)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables"
+    label: "GitHub Docs: GITHUB_WORKSPACE default environment variable"
+  - url: "https://github.com/actions/github-script/issues/390"
+    label: "actions/github-script#390: Cannot find module with relative path"

package/errors/silent-failures/checkout-path-github-workspace-unchanged.yml

@@ -0,0 +1,91 @@
+id: silent-failures-079
+title: "actions/checkout path: input doesn't change GITHUB_WORKSPACE — subsequent steps use wrong directory"
+category: silent-failures
+severity: silent-failure
+tags:
+  - checkout
+  - path
+  - GITHUB_WORKSPACE
+  - working-directory
+  - subdirectory
+patterns:
+  - regex: 'No such file or directory'
+    flags: i
+  - regex: 'ENOENT.*no such file'
+    flags: i
+error_messages:
+  - "No such file or directory"
+  - "ENOENT: no such file or directory"
+root_cause: |
+  When actions/checkout is used with a path: input (e.g., path: app), the repository is
+  checked out into $GITHUB_WORKSPACE/app. However, the GITHUB_WORKSPACE environment variable
+  continues to point to the root workspace directory (/home/runner/work/repo-name/repo-name),
+  not to the path: subdirectory. Any subsequent run: steps that use ${{ github.workspace }}
+  or rely on the default working directory will NOT operate inside the checkout subdirectory.
+  This causes file-not-found errors that are hard to debug because the checkout step succeeds
+  and the files do exist — just not at the location subsequent steps expect. This is a
+  particularly common footgun when checking out multiple repositories into different subdirs.
+fix: |
+  Explicitly specify working-directory on all run: steps that operate on the checked-out code,
+  OR set a job-level defaults.run.working-directory. Alternatively, avoid path: unless you
+  need multiple checkouts — the default checkout places files directly at $GITHUB_WORKSPACE.
+fix_code:
+  - language: yaml
+    label: "Use working-directory to point to the checkout subdirectory"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          path: app
+
+      - name: Build
+        working-directory: ${{ github.workspace }}/app
+        run: npm install && npm run build
+
+  - language: yaml
+    label: "Set job-level default working-directory"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          defaults:
+            run:
+              working-directory: ./app
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                path: app
+            - run: npm install && npm run build
+
+  - language: yaml
+    label: "Multiple checkouts — use explicit paths for each"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+          with:
+            repository: myorg/frontend
+            path: frontend
+
+        - uses: actions/checkout@v4
+          with:
+            repository: myorg/backend
+            path: backend
+
+        - name: Build frontend
+          working-directory: frontend
+          run: npm ci && npm run build
+
+        - name: Build backend
+          working-directory: backend
+          run: go build ./...
+prevention:
+  - "Prefer the default checkout (no path:) unless checking out multiple repos in the same job"
+  - "When path: is used, always add defaults.run.working-directory at the job level"
+  - "Never use ${{ github.workspace }} to reference files from a path:-redirected checkout without appending the path value"
+  - "Use echo $GITHUB_WORKSPACE and ls $GITHUB_WORKSPACE in debug steps to verify directory contents"
+docs:
+  - url: "https://github.com/actions/checkout?tab=readme-ov-file#usage"
+    label: "actions/checkout: path input documentation"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_iddefaultsrun"
+    label: "GitHub Docs: jobs.defaults.run.working-directory"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables"
+    label: "GitHub Docs: GITHUB_WORKSPACE default environment variable"

package/errors/yaml-syntax/step-output-boolean-string-coercion-if-condition.yml

@@ -0,0 +1,100 @@
+id: yaml-syntax-053
+title: 'Step output boolean string coercion — comparing to bare true/false silently never matches'
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - step-outputs
+  - GITHUB_OUTPUT
+  - boolean
+  - string-coercion
+  - if-condition
+  - silent-failure
+patterns:
+  - regex: 'outputs\.[a-z_][a-z0-9_]*\s*==\s*true\b'
+    flags: 'i'
+  - regex: 'outputs\.[a-z_][a-z0-9_]*\s*==\s*false\b'
+    flags: 'i'
+  - regex: 'needs\.[a-z_][a-z0-9_-]*\.outputs\.[a-z_]+ ==\s*(true|false)\b'
+    flags: 'i'
+error_messages:
+  - "if: steps.check.outputs.changed == true"
+  - "if: needs.build.outputs.has_changes == false"
+  - "if: steps.detect.outputs.skip == true"
+root_cause: |
+  All values written to GITHUB_OUTPUT (via echo "key=value" >> $GITHUB_OUTPUT) are
+  stored and transmitted as strings, regardless of the intended type. When a step
+  outputs a boolean-like value such as echo "changed=true" >> $GITHUB_OUTPUT, the
+  output steps.id.outputs.changed is the string 'true', not the boolean true.
+
+  In GitHub Actions expression syntax, type comparison is strict:
+  - 'true' == true  → false  (string 'true' does not equal boolean true)
+  - 'false' == false → false  (string 'false' does not equal boolean false)
+  - '' == false → true  (empty string does equal boolean false — a separate gotcha)
+
+  This means if: steps.check.outputs.changed == true silently evaluates to false
+  even when the output is the string "true", and the step is silently skipped with
+  no error. The workflow log shows the step as skipped with no indication that the
+  condition evaluation was the cause.
+
+  The same pattern applies to job outputs (needs.job.outputs.flag) passed between
+  jobs via the outputs: block.
+fix: |
+  Always compare step and job outputs as strings using single-quoted string literals:
+  - For true check:  == 'true'
+  - For false check: != 'true'  (preferred over == 'false' because empty string also needs handling)
+  - For numeric outputs: use fromJSON() to parse before arithmetic comparison
+
+  For boolean output authors: document that consumers must compare as strings, or
+  use '1'/'0' string conventions to make the string nature explicit.
+fix_code:
+  - language: yaml
+    label: 'Correct: compare step outputs as strings'
+    code: |
+      steps:
+        - id: check
+          run: echo "changed=true" >> $GITHUB_OUTPUT
+
+        # WRONG — silently skipped because 'true' != true (string != boolean)
+        # - if: steps.check.outputs.changed == true
+        #   run: echo "This never runs"
+
+        # CORRECT — compare output string to string literal
+        - if: steps.check.outputs.changed == 'true'
+          run: echo "Files changed, running deploy"
+
+        # CORRECT — inverse check
+        - if: steps.check.outputs.changed != 'true'
+          run: echo "No changes, skipping deploy"
+  - language: yaml
+    label: 'Job-to-job boolean output — compare as string in downstream job'
+    code: |
+      jobs:
+        detect:
+          outputs:
+            has_changes: ${{ steps.diff.outputs.has_changes }}
+          runs-on: ubuntu-latest
+          steps:
+            - id: diff
+              run: |
+                # Output is always a string
+                echo "has_changes=true" >> $GITHUB_OUTPUT
+
+        deploy:
+          needs: detect
+          # CORRECT: compare job output as string literal
+          if: needs.detect.outputs.has_changes == 'true'
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying"
+prevention:
+  - "Always use single-quoted string literals in if: conditions when comparing step or job outputs: == 'true' not == true"
+  - 'Use fromJSON() to parse numeric step outputs before arithmetic or numeric comparisons'
+  - 'Audit workflows for bare == true or == false comparisons on steps.*.outputs.* and needs.*.outputs.*'
+  - 'Use actionlint — it detects type mismatches in expression comparisons involving outputs'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/passing-information-between-jobs'
+    label: 'GitHub Actions — Passing information between jobs'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#literals'
+    label: 'GitHub Actions — Expression literals and type coercion'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/setting-an-output-parameter'
+    label: 'GitHub Actions — Setting an output parameter'

package/package.json

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