@htekdev/actions-debugger 1.0.82 → 1.0.83

package/errors/known-unsolved/step-log-output-truncated-64kb.yml

@@ -0,0 +1,88 @@
+id: known-unsolved-049
+title: 'GitHub Actions step log output silently truncated after 64 KB — tail of large logs invisible'
+category: known-unsolved
+severity: limitation
+tags:
+  - logging
+  - truncation
+  - debug
+  - large-output
+  - verbose-build
+
+patterns:
+  - regex: 'Log upload failed|Error uploading logs'
+    flags: 'i'
+  - regex: 'log size exceeds'
+    flags: 'i'
+
+error_messages:
+  - "##[warning]The log file exceeds the limit."
+  - "##[warning]Some log data was not captured."
+
+root_cause: |
+  GitHub Actions truncates the visible log output for each step at approximately
+  64 KB (65,536 bytes). Steps that produce large stdout or stderr — verbose builds,
+  test suites with thousands of tests, dependency installation logs, or debug-mode
+  tools — have their logs silently cut off at the truncation limit.
+
+  When logs are truncated, the last portion of the output (which often contains
+  the most important information — the actual error or failure message) becomes
+  invisible in the GitHub Actions UI. There is no prominent warning that truncation
+  occurred; only a small warning annotation may appear.
+
+  Common triggers:
+  - `npm install` with many packages in verbose mode
+  - Maven/Gradle builds with `--info` or `--debug` flags
+  - Test runners printing results for thousands of test cases
+  - CMake or Make with verbose output enabled
+  - Custom scripts that echo large data structures for debugging
+
+fix: |
+  GitHub has no setting to increase the per-step log limit. The workarounds
+  involve reducing log volume or capturing overflow output to an artifact file.
+
+  Option 1 — Reduce log verbosity: Remove `--verbose`, `--debug`, or `--info`
+  flags from build/install commands that produce excessive output.
+
+  Option 2 — Redirect overflow to artifact: Pipe output to a file and upload it
+  as an artifact. The complete log is preserved and downloadable.
+
+  Option 3 — Split the step: Break one large step into multiple smaller steps
+  so each step's output stays under the limit.
+
+fix_code:
+  - language: yaml
+    label: 'Redirect large output to artifact file'
+    code: |
+      - name: Run verbose build (output to file)
+        run: |
+          # Tee output: display live AND capture to file for artifact upload
+          set -o pipefail
+          make build 2>&1 | tee build-output.log
+
+      - name: Upload full build log as artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-log
+          path: build-output.log
+          retention-days: 7
+  - language: yaml
+    label: 'Reduce log verbosity at build tool level'
+    code: |
+      - name: Install dependencies (quiet)
+        run: npm install --silent   # suppress per-package progress output
+
+      - name: Build (no verbose)
+        run: make build   # omit -v or VERBOSE=1
+
+prevention:
+  - 'Avoid passing `--verbose`, `--debug`, or `--info` flags to build tools in CI unless actively debugging a specific failure.'
+  - 'Use `2>&1 | tee output.log` with artifact upload for any step expected to produce large output.'
+  - 'Split long-running steps into smaller focused steps so each stays well under the 64 KB log limit.'
+
+docs:
+  - url: 'https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/monitoring-workflows/using-the-github-actions-debugger'
+    label: 'Using the GitHub Actions debugger — GitHub Docs'
+  - url: 'https://github.com/actions/upload-artifact'
+    label: 'actions/upload-artifact — GitHub Actions'

package/errors/runner-environment/git-commit-author-identity-unknown.yml

@@ -0,0 +1,83 @@
+id: runner-environment-149
+title: '`git commit` fails with "Author identity unknown" — actions/checkout does not configure git user identity'
+category: runner-environment
+severity: error
+tags:
+  - checkout
+  - identity
+  - commit
+  - user-email
+  - author-identity
+  - automation
+
+patterns:
+  - regex: 'Author identity unknown'
+    flags: 'i'
+  - regex: 'please tell me who you are'
+    flags: 'i'
+  - regex: 'user\.email not configured'
+    flags: 'i'
+
+error_messages:
+  - "Author identity unknown"
+  - "*** Please tell me who you are."
+  - "fatal: empty ident name (for <>) not allowed"
+  - "error: empty ident name (for <>) not allowed"
+
+root_cause: |
+  `actions/checkout` sets up the repository and configures a `GITHUB_TOKEN`-based
+  credential helper for pushing, but it does NOT configure a git user identity
+  (`user.email` and `user.name`). When a workflow step subsequently creates a
+  commit, git requires committer identity to record in the commit object.
+
+  GitHub-hosted runners have no system-level git identity configured. Without
+  an explicit configuration step, git rejects the commit with the error
+  "Author identity unknown" and prompts for `user.email` and `user.name`.
+
+  This is one of the most common errors in workflows that automate commits:
+  auto-formatting fixes, changelog updates, version bumps, license header
+  injection, and documentation generation workflows that write changes back
+  to the repository.
+
+fix: |
+  Add an identity configuration step immediately after `actions/checkout`.
+  GitHub provides an official `github-actions[bot]` identity with a documented
+  no-reply email address that is suitable for automated commits. This makes
+  automated commits clearly attributable in repository history.
+
+  The numeric user ID prefix in the email (`41898282+`) is the GitHub user ID
+  for the `github-actions[bot]` service account and ensures the commits are
+  linked to that identity in the GitHub UI.
+
+fix_code:
+  - language: yaml
+    label: 'Add identity configuration step after checkout'
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+          with:
+            token: ${{ secrets.GITHUB_TOKEN }}
+
+        - name: Set bot identity for automated commits
+          run: |
+            echo "Configuring identity for automated commits"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git config user.name "github-actions[bot]"
+
+        - name: Apply and commit changes
+          run: |
+            git add .
+            git commit -m "chore: automated update [skip ci]"
+            git push
+
+prevention:
+  - 'Add identity configuration as the first step after checkout in any job that creates commits.'
+  - 'Use the `github-actions[bot]` no-reply email to make automated commits attributable without a real user email.'
+  - 'Consider setting identity at workflow level using a reusable composite action so all jobs inherit it automatically.'
+  - 'Use `--global` flag if the workflow uses multiple checkouts or subdirectory checkouts that all need the same identity.'
+
+docs:
+  - url: 'https://github.com/actions/checkout'
+    label: 'actions/checkout — GitHub Actions'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-jobs-in-a-workflow'
+    label: 'Using jobs in a workflow — GitHub Docs'

package/errors/triggers/pull-request-closed-fires-for-unmerged-prs.yml

@@ -0,0 +1,79 @@
+id: triggers-057
+title: '`on.pull_request types: [closed]` fires for both merged AND unmerged PR closures — use `if: merged == true` guard'
+category: triggers
+severity: silent-failure
+tags:
+  - pull_request
+  - closed
+  - merged
+  - event-types
+  - deploy-on-merge
+
+patterns:
+  - regex: 'types:\s*\[.*closed.*\]'
+    flags: 'i'
+  - regex: 'on:\s*\n\s+pull_request:\s*\n\s+types:\s*\[.*closed'
+    flags: 'im'
+
+error_messages:
+  - "github.event.action: closed"
+  - "github.event.pull_request.merged: false"
+
+root_cause: |
+  The `pull_request` event `closed` type fires whenever a PR is closed — regardless
+  of whether it was merged or simply closed without merging. GitHub does not provide
+  a `merged` type for the `pull_request` event.
+
+  Developers commonly use `types: [closed]` to trigger deployment or post-merge
+  workflows, assuming `closed` is equivalent to "merged into the base branch". In
+  reality, a PR can be closed (abandoned, rejected) without being merged, and the
+  `closed` event fires in both cases.
+
+  The distinction is only available via `github.event.pull_request.merged` (a
+  boolean) or `github.event.pull_request.merge_commit_sha` (non-null if merged).
+  Without an explicit check, workflows using `types: [closed]` will run on
+  abandoned PRs, causing spurious deployments, incorrect release triggers, or
+  unnecessary job runs.
+
+fix: |
+  Add an `if:` condition to the job or workflow that checks
+  `github.event.pull_request.merged == true` to ensure the workflow only
+  proceeds when the PR was actually merged.
+
+fix_code:
+  - language: yaml
+    label: 'Guard job with merged == true check'
+    code: |
+      on:
+        pull_request:
+          types: [closed]
+
+      jobs:
+        deploy:
+          # Only run when PR was merged, not when simply closed
+          if: github.event.pull_request.merged == true
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./deploy.sh
+  - language: yaml
+    label: 'Equivalent guard using merge_commit_sha'
+    code: |
+      jobs:
+        notify:
+          if: github.event.pull_request.merge_commit_sha != ''
+          runs-on: ubuntu-latest
+          steps:
+            - name: Notify on merge
+              run: echo "PR merged at ${{ github.event.pull_request.merge_commit_sha }}"
+
+prevention:
+  - 'Never use `types: [closed]` without an `if: github.event.pull_request.merged == true` guard for merge-triggered workflows.'
+  - 'Remember: there is no `merged` event type for `pull_request` — `closed` is the closest type, but it requires the merged guard.'
+  - 'Test your workflow by manually closing a PR without merging and verifying the workflow does not run (or is skipped).'
+
+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 — GitHub Docs'
+  - url: 'https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request'
+    label: 'pull_request webhook payload — GitHub Docs'

package/errors/yaml-syntax/reusable-workflow-with-secrets-context-rejected.yml

@@ -0,0 +1,98 @@
+id: yaml-syntax-052
+title: '`secrets` context not available in `with:` inputs for reusable workflow calls — use `secrets:` block instead'
+category: yaml-syntax
+severity: error
+tags:
+  - reusable-workflows
+  - secrets
+  - with
+  - workflow-call
+  - secrets-context
+
+patterns:
+  - regex: 'Context access might be invalid: secrets'
+    flags: 'i'
+  - regex: 'secrets\.[A-Z_][A-Z0-9_]*'
+    flags: 'i'
+
+error_messages:
+  - "Context access might be invalid: secrets"
+  - "The workflow is not valid. .github/workflows/caller.yml: Unrecognized named-value: 'secrets'"
+  - "Unrecognized named-value: 'secrets'. Located at position 1 within expression: secrets.MY_TOKEN"
+
+root_cause: |
+  When calling a reusable workflow, the `with:` key (which passes inputs) does NOT
+  have access to the `secrets` context. The `secrets` context is intentionally
+  restricted to the `secrets:` block of the reusable workflow call to prevent
+  secrets from being accidentally exposed as plain-text input values.
+
+  This restriction applies ONLY to reusable workflow calls (`jobs.<id>.uses:`).
+  Regular action steps (`steps.<id>.uses:`) DO allow `${{ secrets.MY_SECRET }}`
+  in their `with:` blocks.
+
+  Attempting to pass a secret via `with:` in a reusable workflow call results in
+  an actionlint error or a runtime error: "Context access might be invalid: secrets".
+  Even if it were allowed, passing secrets as `with:` inputs would expose the
+  secret value in the workflow logs as a plain-text input.
+
+  The correct mechanism is the `secrets:` mapping on the calling job, which
+  explicitly maps caller secrets to the callee's declared `on.workflow_call.secrets`
+  parameters. This preserves masking and audit trail.
+
+fix: |
+  Move secret values from `with:` to the `secrets:` block of the reusable
+  workflow call. Ensure the callee workflow declares the secret under
+  `on.workflow_call.secrets` with a matching name.
+
+fix_code:
+  - language: yaml
+    label: 'Caller workflow — pass secrets via secrets: not with:'
+    code: |
+      # BAD: secrets context not available in with:
+      # jobs:
+      #   call:
+      #     uses: ./.github/workflows/deploy.yml
+      #     with:
+      #       token: ${{ secrets.DEPLOY_TOKEN }}   # Error: secrets context invalid here
+
+      # GOOD: pass secrets via secrets: block
+      jobs:
+        call:
+          uses: ./.github/workflows/deploy.yml
+          with:
+            environment: production   # non-secret inputs go here
+          secrets:
+            deploy-token: ${{ secrets.DEPLOY_TOKEN }}   # secrets go here
+  - language: yaml
+    label: 'Callee workflow — declare secrets under on.workflow_call.secrets'
+    code: |
+      # .github/workflows/deploy.yml
+      on:
+        workflow_call:
+          inputs:
+            environment:
+              type: string
+              required: true
+          secrets:
+            deploy-token:
+              required: true
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Use the secret
+              env:
+                TOKEN: ${{ secrets.deploy-token }}
+              run: echo "Deploying to ${{ inputs.environment }}"
+
+prevention:
+  - 'Never use `${{ secrets.* }}` inside `with:` of a reusable workflow call — the `secrets` context is blocked there.'
+  - 'Declare all required secrets in the callee under `on.workflow_call.secrets:` and pass them via `secrets:` in the caller.'
+  - 'Run actionlint in CI to catch `secrets` context misuse before it reaches runtime.'
+
+docs:
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#using-inputs-and-secrets-in-a-reusable-workflow'
+    label: 'Using inputs and secrets in a reusable workflow — GitHub Docs'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#passing-secrets-to-called-workflows'
+    label: 'Passing secrets to called workflows — GitHub Docs'

package/package.json

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