@htekdev/actions-debugger 1.0.89 → 1.0.91

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

@@ -0,0 +1,86 @@
+id: caching-artifacts-051
+title: 'download-artifact@v4 places each artifact in a named subdirectory, breaking v3 flat path assumption'
+category: caching-artifacts
+severity: silent-failure
+tags:
+  - download-artifact
+  - v4-migration
+  - directory-structure
+  - breaking-change
+  - path
+patterns:
+  - regex: 'Downloading artifact.*to.*'
+    flags: 'i'
+  - regex: 'ENOENT.*no such file or directory'
+    flags: 'i'
+  - regex: 'no such file or directory.*dist\/'
+    flags: 'i'
+error_messages:
+  - "Downloading artifact: my-artifact to /home/runner/work/repo/dist"
+  - "Error: ENOENT: no such file or directory, open 'dist/index.js'"
+  - "Error: Cannot find module '/home/runner/work/repo/dist/index.js'"
+  - "cp: cannot stat 'dist/main.js': No such file or directory"
+root_cause: |
+  In actions/download-artifact@v3, downloading a named artifact with `path: dist`
+  placed files directly inside the `dist/` directory (flat layout). In v4,
+  the action changed to place each artifact in a subdirectory named after the
+  artifact: files land at `dist/<artifact-name>/filename` instead of `dist/filename`.
+
+  This is a silent failure: the `download-artifact` step succeeds with exit code 0
+  and emits no warning about the path change. Downstream steps that reference
+  `dist/index.js` fail with "no such file" errors — the file is actually at
+  `dist/my-artifact/index.js`. The behavior is especially confusing in matrix
+  workflows where each job uploads an artifact with a unique name, and the
+  consuming job downloads all artifacts into a single `path:`.
+
+  The change was made to support downloading multiple artifacts into the same
+  `path:` without name collisions, but it breaks any workflow that migrated from
+  v3 without adjusting downstream path references.
+fix: |
+  Option 1 (recommended): Set the `path:` to a staging directory and reference
+  files using the artifact subdirectory path, or use `merge-multiple: true` to
+  flatten all artifacts into the `path:` directory.
+
+  Option 2: Name the artifact the same as the target directory and download into
+  the parent, so the subdirectory becomes the expected location.
+
+  Option 3: Add a step to move the artifact contents up one level after download.
+fix_code:
+  - language: yaml
+    label: 'Use merge-multiple: true to restore v3 flat behavior for single artifact'
+    code: |
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist-bundle
+          path: dist
+          merge-multiple: true   # Flattens into dist/ directly, matching v3 behavior
+  - language: yaml
+    label: 'Adjust downstream path to include artifact subdirectory'
+    code: |
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist-bundle
+          path: staging
+
+      # Files land at staging/dist-bundle/index.js — reference accordingly
+      - run: node staging/dist-bundle/index.js
+  - language: yaml
+    label: 'Download all matrix artifacts and merge into one directory'
+    code: |
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: build-*        # Matches all matrix artifacts
+          path: dist
+          merge-multiple: true   # All files merged flat into dist/
+prevention:
+  - "When migrating from download-artifact@v3 to v4, audit all `path:` references and downstream file access patterns"
+  - "Use `merge-multiple: true` if you need the v3 flat download behavior for a single named artifact"
+  - "Set `path:` to a staging directory and explicitly reference the `path/<artifact-name>/` subdirectory in downstream steps"
+  - "Run the workflow once after migrating and check the action log for 'Downloading artifact: X to Y' to verify the actual destination path"
+docs:
+  - url: 'https://github.com/actions/download-artifact/blob/main/docs/migration-guide.md'
+    label: 'download-artifact migration guide: v3 to v4 breaking changes'
+  - url: 'https://github.com/actions/download-artifact?tab=readme-ov-file#inputs'
+    label: 'download-artifact@v4 inputs reference — merge-multiple option'
+  - url: 'https://github.com/actions/upload-artifact/discussions/562'
+    label: 'Community discussion: v4 directory structure change from v3'

package/errors/concurrency-timing/concurrency-timing-044.yml

@@ -0,0 +1,95 @@
+id: concurrency-timing-044
+title: 'Matrix jobs with a static concurrency group key serialize instead of running in parallel'
+category: concurrency-timing
+severity: silent-failure
+tags:
+  - matrix
+  - concurrency
+  - parallelism
+  - group-key
+  - strategy
+patterns:
+  - regex: 'Waiting for a pending job to finish'
+    flags: 'i'
+  - regex: 'This workflow is waiting for a pending job to complete'
+    flags: 'i'
+error_messages:
+  - 'Waiting for a pending job to finish — concurrency: ci-deploy'
+root_cause: |
+  When a workflow-level or job-level concurrency group is configured with a static
+  key that does not include the matrix dimension values, all matrix legs share the
+  same concurrency slot. GitHub Actions enforces that only one run occupies each
+  slot at a time, so instead of running N matrix legs in parallel, the legs queue
+  and execute one at a time — silently serializing a job strategy that was intended
+  to be parallel.
+
+  This can multiply workflow duration by the number of matrix dimensions (e.g., a
+  3-OS matrix that should finish in 10 minutes takes 30 minutes). The GitHub Actions
+  UI shows later matrix legs as "Waiting for a pending job to finish" which hints at
+  the problem, but developers often interpret this as runner resource contention rather
+  than a concurrency group misconfiguration.
+
+  Common patterns that trigger this:
+    concurrency:
+      group: ci-${{ github.ref }}    # all matrix legs share "ci-refs/heads/main"
+
+    concurrency:
+      group: ${{ github.workflow }}  # all legs share workflow name
+fix: |
+  Include the relevant matrix dimension values in the concurrency group key so that
+  each matrix leg gets a unique slot. If cancel-in-progress behavior is still needed,
+  it will apply per-matrix-leg rather than globally across all legs.
+
+  If you intentionally want to serialize matrix legs (e.g., sequential deploys to
+  environments), keep the static key but document the serialization intent.
+fix_code:
+  - language: yaml
+    label: 'Include matrix values in concurrency group key'
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              os: [ubuntu-latest, windows-latest, macos-latest]
+              node: [18, 20, 22]
+          runs-on: ${{ matrix.os }}
+          concurrency:
+            # Unique slot per matrix leg — allows full parallelism
+            group: ci-${{ github.ref }}-${{ matrix.os }}-${{ matrix.node }}
+            cancel-in-progress: true
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-node@v4
+              with:
+                node-version: ${{ matrix.node }}
+            - run: npm test
+  - language: yaml
+    label: 'Workflow-level concurrency must also include matrix values'
+    code: |
+      # BAD: workflow-level concurrency applies to ALL jobs, including matrix legs
+      # concurrency:
+      #   group: ci-${{ github.ref }}    # serializes all legs!
+      #   cancel-in-progress: true
+
+      # GOOD: set concurrency at the job level with matrix dimensions in the key
+      jobs:
+        build:
+          strategy:
+            matrix:
+              platform: [linux, windows, macos]
+          runs-on: ubuntu-latest
+          concurrency:
+            group: build-${{ github.ref }}-${{ matrix.platform }}
+            cancel-in-progress: true
+          steps:
+            - run: echo "Building for ${{ matrix.platform }}"
+prevention:
+  - 'Always include matrix dimension values in concurrency group keys: group: ci-${{ github.ref }}-${{ matrix.os }}'
+  - 'Check workflow execution time after adding concurrency groups — unexpected serialization increases total duration'
+  - 'Use workflow-level concurrency only for single-job workflows; for matrix jobs, always configure concurrency at the job level'
+  - 'Verify parallelism by checking the GitHub Actions timeline view — all matrix legs should show overlapping execution'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-concurrency'
+    label: 'Using concurrency in GitHub Actions'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymatrix'
+    label: 'Matrix strategy syntax reference'

package/errors/known-unsolved/known-unsolved-052.yml

@@ -0,0 +1,119 @@
+id: known-unsolved-052
+title: 'GitHub-hosted runner IP addresses change on every workflow run — static IP allowlisting unreliable'
+category: known-unsolved
+severity: limitation
+tags:
+  - runner
+  - ip-address
+  - firewall
+  - allowlist
+  - network
+  - hosted-runner
+patterns:
+  - regex: 'Connection refused|Connection timed out|Unable to connect'
+    flags: 'i'
+  - regex: 'connect ECONNREFUSED|ECONNRESET|ETIMEDOUT'
+    flags: 'i'
+  - regex: 'blocked by firewall|access denied.*firewall|ip.*not.*allowed'
+    flags: 'i'
+error_messages:
+  - 'Error: connect ECONNREFUSED 10.0.0.5:5432'
+  - 'curl: (7) Failed to connect to internal-api.company.com port 443: Connection refused'
+  - 'Error: connect ETIMEDOUT'
+root_cause: |
+  GitHub-hosted runners are allocated from a large, rotating pool of virtual machines.
+  The IP address assigned to each run is drawn from GitHub's published CIDR ranges
+  (available via https://api.github.com/meta under "actions") but changes on every
+  workflow run — there is no way to obtain a stable, predictable IP for a GitHub-hosted
+  runner in advance.
+
+  GitHub publishes these IP ranges for documentation purposes, but:
+  1. The ranges are broad (/20 or larger) and overlap with other GitHub services
+  2. The specific IP within the range cannot be predicted before the run starts
+  3. The ranges update periodically, requiring allowlist maintenance
+  4. On each run, the runner's IP can be any address in the published ranges
+
+  This makes static IP allowlisting in external firewalls, database security groups
+  (AWS RDS, Azure SQL, Cloudflare), or on-premise systems unreliable. Allowlisting the
+  entire published range exposes hundreds of thousands of IP addresses and violates
+  least-privilege security principles.
+
+  This is a fundamental architecture constraint of GitHub-hosted runners and has no
+  perfect solution — only workarounds.
+fix: |
+  There is no way to guarantee a stable IP for GitHub-hosted runners. Use one of these
+  patterns instead of IP allowlisting:
+
+  1. OIDC (preferred): Use OIDC tokens to authenticate to cloud providers (AWS, Azure,
+     GCP) rather than network-level access controls. No IP allowlisting needed.
+
+  2. Self-hosted runners: Deploy runners on your network with known, stable IPs.
+
+  3. Dynamic allowlisting: At workflow start, call your cloud provider API to add the
+     runner's current IP to the security group; remove it at workflow end. Brittle but
+     workable for database access.
+
+  4. VPN/tunnel action: Use actions like cloudflare/cloudflare-warp-action or a
+     WireGuard setup action to tunnel runner traffic through a fixed gateway IP.
+
+  5. Private hosted runners (GitHub Enterprise): If on GHEC, configure static IP ranges
+     via network configurations for GitHub-hosted runners.
+fix_code:
+  - language: yaml
+    label: 'Use OIDC authentication instead of IP allowlisting (AWS example)'
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write
+            contents: read
+          steps:
+            - uses: aws-actions/configure-aws-credentials@v4
+              with:
+                role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsRole
+                aws-region: us-east-1
+                # No IP allowlisting needed — OIDC validates the token, not the IP
+            - run: aws rds describe-db-instances
+  - language: yaml
+    label: 'Dynamic security group allowlisting (temporary, for legacy systems)'
+    code: |
+      jobs:
+        test-with-db:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Get runner IP
+              id: ip
+              run: echo "ip=$(curl -s https://api.ipify.org)" >> $GITHUB_OUTPUT
+
+            - name: Add runner IP to DB security group
+              run: |
+                aws ec2 authorize-security-group-ingress \
+                  --group-id sg-0abc123 \
+                  --protocol tcp \
+                  --port 5432 \
+                  --cidr "${{ steps.ip.outputs.ip }}/32"
+
+            - name: Run tests
+              run: npm test
+
+            - name: Remove runner IP from security group
+              if: always()
+              run: |
+                aws ec2 revoke-security-group-ingress \
+                  --group-id sg-0abc123 \
+                  --protocol tcp \
+                  --port 5432 \
+                  --cidr "${{ steps.ip.outputs.ip }}/32"
+prevention:
+  - 'Design CI pipelines to use token-based authentication (OIDC, API keys, mTLS) rather than IP allowlisting from the start'
+  - 'For AWS: use IAM roles with OIDC (aws-actions/configure-aws-credentials); for Azure: use azure/login with OIDC; for GCP: use google-github-actions/auth with Workload Identity Federation'
+  - 'If IP allowlisting is unavoidable, use GitHub Enterprise Cloud with a configured network allowing stable egress IPs'
+  - 'Subscribe to GitHub changelog for updates to runner IP range publications — the ranges do expand over time'
+docs:
+  - url: 'https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#ip-addresses'
+    label: 'GitHub-hosted runner IP addresses'
+  - url: 'https://api.github.com/meta'
+    label: 'GitHub meta API — published actions IP ranges'
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-cloud-providers'
+    label: 'Configuring OIDC in cloud providers'

package/errors/permissions-auth/permissions-auth-051.yml

@@ -0,0 +1,103 @@
+id: permissions-auth-051
+title: 'GITHUB_TOKEN push blocked by repository ruleset despite contents: write permission'
+category: permissions-auth
+severity: error
+tags:
+  - github-token
+  - rulesets
+  - contents-write
+  - branch-protection
+  - bypass-list
+patterns:
+  - regex: 'GH013: Repository rule violations found for refs\/'
+    flags: 'i'
+  - regex: 'remote: error: Changes must be made through a pull request'
+    flags: 'i'
+  - regex: 'refusing to allow.*to create or update'
+    flags: 'i'
+error_messages:
+  - "remote: error: GH013: Repository rule violations found for refs/heads/main."
+  - "remote: error: GH013: Repository rule violations found for refs/tags/v1.0.0."
+  - "remote: error: Changes must be made through a pull request."
+  - "error: failed to push some refs to 'https://github.com/ORG/REPO.git'"
+  - "refusing to allow a GitHub App to create or update file"
+root_cause: |
+  GitHub Rulesets (generally available January 2025) allow organization and repository
+  administrators to define push rules that enforce requirements such as "all pushes
+  must come through a pull request", "signed commits required", or "tag patterns
+  must match a format". Unlike legacy branch protection rules, rulesets apply to
+  ALL actors including GitHub Apps and the GITHUB_TOKEN by default — regardless of
+  the `contents: write` permission granted in the workflow's `permissions:` block.
+
+  The `contents: write` permission only controls whether the token is *authorized*
+  to make write API calls; it does not grant exemption from repository rulesets.
+  Rulesets have a separate "bypass list" in Settings > Rules > Rulesets that must
+  explicitly include "GitHub Actions" (or a specific GitHub App) to allow workflow
+  pushes to bypass ruleset restrictions.
+
+  This error affects workflows that push commits directly (e.g., auto-format,
+  changelog generation, version bump commits) or push tags (e.g., release tagging)
+  to branches or tags governed by a ruleset.
+fix: |
+  Option 1 (recommended): Add GitHub Actions to the ruleset bypass list.
+  Go to Settings > Rules > Rulesets > (select the ruleset) > Bypass list >
+  Add bypass > select "GitHub Actions". This allows workflow GITHUB_TOKEN
+  pushes to bypass the ruleset.
+
+  Option 2: Use a Personal Access Token (PAT) or GitHub App token from a user
+  account that is in the bypass list. Pass the token via a secret and use it
+  in the push step.
+
+  Option 3: Restructure the workflow to push via a pull request instead of
+  directly to the protected branch, satisfying the "PR required" ruleset rule.
+fix_code:
+  - language: yaml
+    label: 'Use a PAT secret to push when GITHUB_TOKEN is blocked by rulesets'
+    code: |
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                token: ${{ secrets.RELEASE_PAT }}  # PAT from bypass-listed account
+                fetch-depth: 0
+
+            # ... version bump or commit steps ...
+
+            - name: Push release commit and tag
+              env:
+                GITHUB_TOKEN: ${{ secrets.RELEASE_PAT }}
+              run: |
+                # Use the PAT-authenticated remote for push
+                echo "Push authorized via PAT from bypass-listed account"
+  - language: yaml
+    label: 'Use a GitHub App token with bypass list membership'
+    code: |
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/create-github-app-token@v2
+              id: app-token
+              with:
+                app-id: ${{ vars.RELEASE_APP_ID }}
+                private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+
+            - uses: actions/checkout@v4
+              with:
+                token: ${{ steps.app-token.outputs.token }}
+
+            # Push step uses the App token — ensure the App is in bypass list
+prevention:
+  - "When enabling rulesets on a repository or organization, immediately check CI/CD workflows that push directly to protected branches or tags"
+  - "Add GitHub Actions to ruleset bypass lists proactively when creating rulesets that restrict direct pushes"
+  - "Prefer pushing via pull requests (open PR, auto-merge) over direct commits in automated workflows — this satisfies 'PR required' rules and avoids bypass list management"
+  - "Audit existing legacy branch protection rules when migrating to rulesets — bypass behavior differs: branch protection 'Restrict who can push' exempts admins by default; rulesets do not"
+docs:
+  - url: 'https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets'
+    label: 'GitHub Docs: Available rules for rulesets'
+  - url: 'https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/creating-rulesets-for-a-repository#granting-bypass-permissions-for-your-ruleset'
+    label: 'GitHub Docs: Granting bypass permissions for a ruleset'
+  - url: 'https://github.blog/changelog/2025-01-29-github-rulesets-are-generally-available/'
+    label: 'GitHub Changelog: Rulesets generally available — January 2025'

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

@@ -0,0 +1,92 @@
+id: runner-environment-157
+title: 'setup-python EOL Python version triggers slow pyenv compilation on ubuntu-24.04'
+category: runner-environment
+severity: warning
+tags:
+  - setup-python
+  - pyenv
+  - ubuntu-24.04
+  - python-version
+  - toolcache
+  - build-time
+patterns:
+  - regex: 'Version \d+\.\d+\.\d+ was not found in the local cache'
+    flags: 'i'
+  - regex: 'pyenv install python-\d+\.\d+\.\d+'
+    flags: 'i'
+  - regex: 'python-build: .*not installed'
+    flags: 'i'
+error_messages:
+  - "Version 3.8.20 was not found in the local cache"
+  - "Version 3.9.19 was not found in the local cache"
+  - "pyenv install python-3.8.20"
+  - "python-build: python not found in PATH"
+  - "Successfully installed cpython: 3.9.18 (took: 523.19 seconds)"
+root_cause: |
+  ubuntu-24.04 runners ship with Python 3.11, 3.12, and 3.13 in the pre-installed
+  toolcache. Python 3.8 (EOL October 2024), 3.9, and 3.10 were removed from the
+  ubuntu-24.04 toolcache entirely. When actions/setup-python requests one of these
+  versions, it cannot find a cached build and falls back to compiling Python from
+  source via pyenv. The compilation process — downloading Python source, running
+  ./configure, make, make install with GCC — typically takes 5–10 minutes and can
+  exhaust the default 6-hour job timeout in heavily parallelized pipelines or
+  cause unexpectedly slow CI on free-tier runners. The warning "Version X was not
+  found in the local cache" is emitted but easy to miss in long logs, and the
+  action still exits 0 on success, making the slowdown invisible until CI bills
+  or timeout failures appear.
+fix: |
+  Option 1 (recommended): Upgrade to a Python version pre-installed on ubuntu-24.04
+  (3.11, 3.12, or 3.13). These are available instantly from the toolcache.
+
+  Option 2: Pin the runner to ubuntu-22.04, which retains Python 3.9 and 3.10
+  in the toolcache through its support window.
+
+  Option 3: Add the deadsnakes PPA before calling setup-python to provide fast
+  pre-built binaries for older Python versions on ubuntu-24.
+
+  Option 4: Use a container image that pre-bundles your Python version to avoid
+  the toolcache entirely.
+fix_code:
+  - language: yaml
+    label: 'Upgrade to a toolcache-available Python version'
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'   # Pre-installed on ubuntu-24.04; no pyenv fallback
+  - language: yaml
+    label: 'Use ubuntu-22.04 runner if 3.9 or 3.10 is required'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-22.04    # Retains Python 3.9/3.10 in toolcache
+          steps:
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.10'
+  - language: yaml
+    label: 'Deadsnakes PPA for fast pre-built older Python on ubuntu-24.04'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-24.04
+          steps:
+            - name: Add deadsnakes PPA
+              run: |
+                sudo add-apt-repository ppa:deadsnakes/ppa
+                sudo apt-get update
+                sudo apt-get install -y python3.9 python3.9-venv python3.9-dev
+            - uses: actions/setup-python@v5
+              with:
+                python-version: '3.9'
+prevention:
+  - "Avoid pinning `python-version` to EOL releases (3.8 EOL Oct 2024, 3.9 EOL Oct 2025)"
+  - "Check the ubuntu-24.04 runner toolcache inventory at github.com/actions/runner-images for available Python versions"
+  - "Use `python-version-file: .python-version` or `pyproject.toml` to track the project's minimum supported version and update it when runners drop EOL toolcache entries"
+  - "Set a `timeout-minutes` on the job so pyenv compilation failures surface quickly rather than running for hours"
+docs:
+  - url: 'https://github.com/actions/setup-python/issues/726'
+    label: 'setup-python: Python 3.8/3.9 not found in toolcache on ubuntu-24.04'
+  - url: 'https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md'
+    label: 'ubuntu-24.04 runner image readme — pre-installed Python versions'
+  - url: 'https://devguide.python.org/versions/'
+    label: 'Python release lifecycle — EOL dates by version'

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

@@ -0,0 +1,69 @@
+id: silent-failures-085
+title: 'actions/checkout does not initialize submodules by default — empty submodule directories silently break builds'
+category: silent-failures
+severity: silent-failure
+tags:
+  - checkout
+  - submodules
+  - git-submodule
+  - empty-directory
+  - build-failure
+patterns:
+  - regex: 'fatal: not a git repository'
+    flags: 'i'
+  - regex: 'No such file or directory'
+    flags: 'i'
+  - regex: 'cannot open.*No such file or directory'
+    flags: 'i'
+error_messages:
+  - 'fatal: not a git repository (or any of the parent directories): .git'
+  - 'CMake Error: The source directory "/home/runner/work/repo/vendor/lib" does not appear to contain CMakeLists.txt.'
+  - 'error: cannot open include file: ../vendor/lib/include/lib.h: No such file or directory'
+root_cause: |
+  actions/checkout defaults to submodules: false, meaning any Git submodules
+  defined in .gitmodules are NOT cloned — they appear as empty directories in the
+  workspace. There is no warning or error in the checkout step output; it completes
+  successfully with exit code 0.
+
+  Downstream build steps that depend on submodule content then fail with generic
+  "file not found" or "not a git repository" errors that point to the submodule
+  directory, not to the checkout configuration. This mismatch between where the error
+  appears (the build step) and its root cause (the checkout step) makes it
+  time-consuming to diagnose, especially for contributors unfamiliar with the repo's
+  submodule structure.
+
+  Affected scenarios include:
+  - CMake projects with vendored dependencies as submodules
+  - Projects using git submodule for shared library code
+  - Repos with submodules for test fixtures or documentation themes
+fix: |
+  Add submodules: true (or submodules: 'recursive' for nested submodules) to your
+  actions/checkout step. For private submodules, you may also need to set
+  token: with a PAT that has access to the submodule repositories — the default
+  GITHUB_TOKEN only has access to the current repository.
+fix_code:
+  - language: yaml
+    label: 'Initialize submodules during checkout'
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          submodules: true          # 'true' for one level, 'recursive' for nested
+          # For private submodule repos, provide a PAT with access:
+          # token: ${{ secrets.SUBMODULE_PAT }}
+  - language: yaml
+    label: 'Recursive submodules for nested submodule trees'
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          submodules: 'recursive'
+          fetch-depth: 0            # Full history if submodule pinning requires it
+prevention:
+  - 'Add submodules: true to actions/checkout in all workflows that build code depending on submodule content'
+  - 'Add a verification step after checkout to confirm critical submodule paths are non-empty: test -f vendor/lib/README.md'
+  - 'Document submodule requirements in your repo README and CONTRIBUTING.md'
+  - 'If the submodule repo is private, use a GitHub App token or fine-grained PAT — the default GITHUB_TOKEN cannot access other repositories'
+docs:
+  - url: 'https://github.com/actions/checkout#usage'
+    label: 'actions/checkout — submodules input reference'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-submodules-in-workflows'
+    label: 'Using submodules in GitHub Actions workflows'

package/errors/triggers/triggers-060.yml

@@ -0,0 +1,86 @@
+id: triggers-060
+title: 'pull_request workflow not re-triggered when PR title or description is edited'
+category: triggers
+severity: silent-failure
+tags:
+  - pull_request
+  - edited
+  - pr-title
+  - types
+  - conventional-commits
+  - status-check
+patterns:
+  - regex: 'on:\s*\n\s*pull_request:\s*\n(?:(?!\s*types:).*\n)*'
+    flags: 'ms'
+error_messages: []
+root_cause: |
+  The default pull_request event types are [opened, synchronize, reopened]. The
+  "edited" activity type — which fires when the PR title, body, or base branch is
+  changed — is NOT included in the default set. Workflows that validate PR titles
+  (e.g., enforcing Conventional Commits format, ticket-number requirements, or length
+  limits) will never re-run when a contributor fixes the PR title after an initial
+  failure.
+
+  This creates a persistent UX problem: the required status check shows as failed
+  after the title is corrected, and the PR cannot be merged without manually
+  re-running the workflow or pushing a new commit. The fix is visible in the GitHub
+  UI and source, but the root cause is non-obvious — nothing in the failure log
+  indicates the workflow won't respond to a title edit.
+fix: |
+  Add "edited" to the pull_request types list for any workflow that validates PR
+  metadata (title, description, or target branch). The "edited" type also fires on
+  body changes and base branch changes, which is typically harmless for title-checking
+  workflows. Do not add "edited" to workflows that trigger expensive CI operations
+  unless you intend them to run on every title/body change.
+fix_code:
+  - language: yaml
+    label: 'Add edited type to re-run on PR title changes'
+    code: |
+      on:
+        pull_request:
+          types:
+            - opened
+            - synchronize
+            - reopened
+            - edited  # Re-run when PR title or description is changed
+
+      jobs:
+        lint-pr-title:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: amannn/action-semantic-pull-request@v5
+              env:
+                GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  - language: yaml
+    label: 'Conditional execution — only validate title on edited events'
+    code: |
+      on:
+        pull_request:
+          types: [opened, synchronize, reopened, edited]
+
+      jobs:
+        check-title:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Validate PR title format
+              if: >
+                github.event_name == 'pull_request' &&
+                (github.event.action == 'opened' ||
+                 github.event.action == 'edited' ||
+                 github.event.action == 'reopened')
+              run: |
+                TITLE="${{ github.event.pull_request.title }}"
+                if ! echo "$TITLE" | grep -qP '^(feat|fix|docs|chore|refactor|test|ci)(\(.+\))?: .+'; then
+                  echo "PR title does not follow Conventional Commits format: $TITLE"
+                  exit 1
+                fi
+prevention:
+  - 'Always include "edited" in pull_request types when the workflow validates PR title or description format'
+  - 'Test that your PR title validation workflow re-runs when you edit the title — do not assume it does'
+  - 'Document required PR title format in CONTRIBUTING.md so contributors know title edits (not just new commits) trigger re-checks'
+  - 'Consider adding a job summary or annotation with the exact format requirement when validation fails'
+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 — activity types reference'
+  - url: 'https://github.com/amannn/action-semantic-pull-request'
+    label: 'action-semantic-pull-request (popular PR title lint action)'

package/errors/yaml-syntax/yaml-syntax-057.yml

@@ -0,0 +1,93 @@
+id: yaml-syntax-057
+title: 'needs: referencing undefined job ID causes instant workflow validation failure'
+category: yaml-syntax
+severity: error
+tags:
+  - needs
+  - job-id
+  - validation
+  - typo
+  - workflow-syntax
+patterns:
+  - regex: "Job '.*' depends on unknown job '.*'"
+    flags: 'i'
+  - regex: "A job named '.*' does not exist in this workflow"
+    flags: 'i'
+  - regex: 'The workflow is not valid.*depends on unknown job'
+    flags: 'i'
+error_messages:
+  - "The workflow is not valid. .github/workflows/ci.yml (Line 42, Col 14): Job 'deploy' depends on unknown job 'biuld'."
+  - "A job named 'biuld' does not exist in this workflow."
+  - "Job 'release' depends on unknown job 'test-and-build'."
+  - "The workflow is not valid. .github/workflows/release.yml: Job 'publish' depends on unknown job 'build_and_test'."
+root_cause: |
+  The `needs:` key in a job definition must exactly reference the IDs of other jobs
+  defined under `jobs:` in the same workflow file. Job IDs are the YAML map keys
+  (e.g., `jobs.build:`, `jobs.test:`), not the `name:` display values.
+
+  A typo in a `needs:` value (e.g., `needs: [biuld]` instead of `needs: [build]`,
+  or `needs: test-and-build` when the job is named `test_and_build`) causes GitHub
+  Actions to reject the entire workflow at parse time with a validation error.
+  No jobs run — the workflow fails before any step executes.
+
+  This error is particularly common after renaming jobs, since the `name:` field
+  (display name in the UI) can be changed without affecting the job ID used in
+  `needs:`. Developers who update `name:` but forget to update downstream `needs:`
+  references see the workflow fail immediately on next push with no prior warning.
+fix: |
+  Ensure every value in `needs:` exactly matches a job ID key defined at the
+  same level under `jobs:`. Job IDs are case-sensitive and use the exact YAML key
+  name — not the `name:` display value.
+
+  Use `actionlint` locally or in pre-commit hooks to catch unknown `needs:` references
+  before pushing.
+fix_code:
+  - language: yaml
+    label: 'Correct needs: to match the exact job ID key'
+    code: |
+      jobs:
+        build:          # <-- This is the job ID (the YAML key)
+          name: Build and Test   # This is the display name — NOT used in needs:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "building"
+
+        deploy:
+          needs: [build]   # Must reference the job ID key, not the name: value
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "deploying"
+  - language: yaml
+    label: 'Rename both job ID and needs: reference after a job rename'
+    code: |
+      # WRONG — job was renamed from 'build' to 'build-and-test' but needs: not updated
+      # jobs:
+      #   build-and-test:
+      #     ...
+      #   deploy:
+      #     needs: [build]   # Error: 'build' no longer exists
+
+      # CORRECT — update needs: to match the new job ID
+      jobs:
+        build-and-test:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "building"
+
+        deploy:
+          needs: [build-and-test]   # Updated to match renamed job ID
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "deploying"
+prevention:
+  - "Use `actionlint` (rhysd/actionlint) locally or as a pre-commit hook — it validates `needs:` references against defined job IDs at lint time"
+  - "Keep job IDs short and stable (e.g., `build`, `test`, `deploy`); use the `name:` field for human-readable display names that can be changed freely"
+  - "When renaming a job ID, search the entire workflow file for all `needs:` references to that ID before committing"
+  - "Enable the actionlint GitHub Actions workflow check in your repository to catch validation errors in PRs before merge"
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idneeds'
+    label: 'GitHub Docs: jobs.<job_id>.needs syntax'
+  - url: 'https://rhysd.github.io/actionlint/'
+    label: 'actionlint — static checker for GitHub Actions workflow files'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idname'
+    label: 'GitHub Docs: jobs.<job_id>.name vs job ID distinction'

package/package.json

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