@htekdev/actions-debugger 1.0.92 → 1.0.93

package/errors/permissions-auth/github-models-missing-models-read-permission.yml

@@ -0,0 +1,115 @@
+id: permissions-auth-052
+title: 'GitHub Models API in Actions requires models: read permission — not in default GITHUB_TOKEN scopes'
+category: permissions-auth
+severity: error
+tags:
+  - models
+  - github-models
+  - ai
+  - permissions
+  - GITHUB_TOKEN
+  - 403
+  - inference
+patterns:
+  - regex: 'models:\s*read'
+    flags: 'i'
+  - regex: 'Resource not accessible by integration.*model'
+    flags: 'i'
+  - regex: 'models.*permission.*required|permission.*models.*required'
+    flags: 'i'
+  - regex: '403.*github\.com/models|github\.com/models.*403'
+    flags: 'i'
+error_messages:
+  - 'Error: Resource not accessible by integration'
+  - '403 Forbidden — models: read permission is required'
+  - 'HttpError: 403 Resource not accessible by integration'
+  - 'Error: The models permission is required to use the GitHub Models API'
+root_cause: |
+  GitHub Models (launched in 2024) provides access to AI inference models (GPT-4o,
+  Claude, Llama, etc.) via the GitHub Models API at https://models.inference.ai.azure.com
+  and via the GitHub REST API at api.github.com/models. When workflows use these
+  endpoints with the GITHUB_TOKEN (for example, via `actions/ai-inference` or via
+  `actions/github-script` calling `github.rest.models.*`), the token must have the
+  `models: read` permission explicitly declared.
+
+  The `models: read` permission was introduced as a new GITHUB_TOKEN scope alongside
+  the GitHub Models feature. It is NOT included in the default GITHUB_TOKEN permissions
+  and is NOT implied by any other existing permission (not `contents: read`, not
+  `packages: read`, not `id-token: write`).
+
+  Common failure patterns:
+  1. Adding an AI inference step or action to an existing workflow that has a
+     permissions: block — the block narrows all unspecified permissions to none,
+     and models: read was never added.
+  2. Using GitHub Models for the first time in a workflow that relies on the
+     repository's default "Read and write" permissions — models: read is not
+     included even in the broadest default permission set.
+  3. Reusable workflow callers that use `secrets: inherit` but do NOT pass through
+     permissions — the called workflow must declare its own `models: read`.
+  4. Fine-grained PATs used as a token override: the PAT must have the "Models: read"
+     resource permission enabled for the target repository or organization.
+
+  The error message "Resource not accessible by integration" is the same 403 error
+  used for other missing permissions, making it hard to identify models: read as the
+  specific missing scope without checking the API response body.
+fix: |
+  Add `models: read` to the `permissions:` block of the job (or workflow) that calls
+  the GitHub Models API. If using a fine-grained PAT instead of GITHUB_TOKEN, ensure
+  the PAT has the "Models" permission enabled.
+fix_code:
+  - language: yaml
+    label: 'Add models: read to job permissions for AI inference steps'
+    code: |
+      jobs:
+        ai-analysis:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: read
+            models: read   # Required for GitHub Models API access
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run AI inference via GitHub Models
+              uses: actions/ai-inference@v1
+              with:
+                model: openai/gpt-4o
+                system-prompt: 'You are a code reviewer. Be concise.'
+                user-prompt: 'Review the changes in this PR for security issues.'
+  - language: yaml
+    label: 'Workflow with multiple permissions including models: read'
+    code: |
+      on:
+        pull_request:
+
+      permissions:
+        contents: read
+        pull-requests: write
+        models: read   # Required for any AI model inference step
+
+      jobs:
+        review:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: AI code review
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  // github.rest.models requires models: read permission
+                  const response = await github.request('POST /repos/{owner}/{repo}/actions/generate-summary', {
+                    owner: context.repo.owner,
+                    repo: context.repo.repo
+                  });
+prevention:
+  - "Always add `models: read` to the permissions block when using GitHub Models API, AI inference actions, or any `github.rest.models.*` API calls"
+  - "The `models: read` scope is not inherited, implied, or included in any default permission set — it must be declared explicitly"
+  - "When upgrading a workflow to add AI features, audit the existing permissions: block and add models: read before deploying"
+  - "Fine-grained PATs used as token overrides must explicitly include the Models permission for the relevant repositories"
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token'
+    label: 'GitHub Docs: Controlling permissions for GITHUB_TOKEN — available scopes'
+  - url: 'https://docs.github.com/en/github-models/use-github-models/integrating-ai-models-into-your-application'
+    label: 'GitHub Docs: Using GitHub Models — authentication and permissions'
+  - url: 'https://github.com/actions/ai-inference'
+    label: 'actions/ai-inference — GitHub Models inference action'
+  - url: 'https://github.com/marketplace/actions/ai-inference'
+    label: 'GitHub Marketplace: AI Inference action'

package/errors/runner-environment/setup-go-gotoolchain-auto-download.yml

@@ -0,0 +1,122 @@
+id: runner-environment-159
+title: 'setup-go@v5 with Go 1.21+ toolchain directive — GOTOOLCHAIN=auto downloads newer Go toolchain mid-CI'
+category: runner-environment
+severity: warning
+tags:
+  - setup-go
+  - go
+  - gotoolchain
+  - toolchain-directive
+  - go-version
+  - network
+  - go-mod
+patterns:
+  - regex: 'go: downloading go1\.\d+\.\d+ \(linux/amd64\)'
+    flags: 'i'
+  - regex: 'go: module requires GOTOOLCHAIN at least go1\.'
+    flags: 'i'
+  - regex: 'go: toolchain.*not available'
+    flags: 'i'
+  - regex: 'toolchain go1\.\d+\.\d+ required, have go1\.'
+    flags: 'i'
+error_messages:
+  - 'go: downloading go1.22.3 (linux/amd64)'
+  - 'go: module requires GOTOOLCHAIN at least go1.22.0'
+  - 'go: toolchain download not available: dial tcp: lookup proxy.golang.org: no such host'
+  - 'toolchain go1.22.3 required, have go1.21.13'
+root_cause: |
+  Go 1.21 introduced the `toolchain` directive in `go.mod` and `go.sum`, along with the
+  `GOTOOLCHAIN` environment variable that controls toolchain version management. The default
+  value `GOTOOLCHAIN=auto` causes the Go runtime to automatically download a newer Go
+  toolchain if the installed version is older than the version specified by the `toolchain`
+  directive (or the `go` directive when no explicit `toolchain` key exists).
+
+  When `actions/setup-go@v5` installs Go 1.21.x but the project's `go.mod` contains:
+    toolchain go1.22.3
+  Go will automatically attempt to download the go1.22.3 toolchain from proxy.golang.org
+  at runtime — during `go build`, `go test`, or any go command. This download adds
+  15-120 seconds to CI jobs and can fail entirely in:
+  - Self-hosted runners in air-gapped or network-restricted environments
+  - Runners with strict egress firewall rules blocking proxy.golang.org
+  - Flaky network conditions during toolchain resolution
+
+  The behavior is often invisible in logs because the download proceeds silently before
+  each `go` invocation. The symptom is slower-than-expected build times or a cryptic
+  `dial tcp: lookup proxy.golang.org: no such host` error that appears unrelated to
+  the Go version.
+
+  Note: This is distinct from the Go 1.23 telemetry cache tar collision
+  (runner-environment-041). That is a cache restore bug; this is an unexpected network
+  download triggered by the toolchain directive.
+fix: |
+  Option 1 (recommended): Set `GOTOOLCHAIN=local` to prevent auto-downloads and fail fast
+  if the installed version doesn't satisfy the toolchain directive. Then configure
+  `actions/setup-go@v5` to install exactly the required Go version.
+
+  Option 2: Use `go-version-file: go.mod` so that setup-go installs the exact Go version
+  matching the `go` line in go.mod — ensure this matches or exceeds the `toolchain`
+  directive to prevent downloads.
+
+  Option 3: Remove the `toolchain` directive from `go.mod` if it is not intentionally
+  pinning a minimum toolchain version. The directive was added automatically by
+  `go mod tidy` in Go 1.21+ and many projects don't need it.
+fix_code:
+  - language: yaml
+    label: 'Set GOTOOLCHAIN=local to prevent mid-CI toolchain downloads'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          env:
+            GOTOOLCHAIN: local   # Never auto-download; use only the installed toolchain
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-go@v5
+              with:
+                go-version: '1.22.x'   # Install the exact version needed by go.mod
+                cache: true
+            - run: go build ./...
+  - language: yaml
+    label: 'Use go-version-file to pin version from go.mod'
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          env:
+            GOTOOLCHAIN: local
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-go@v5
+              with:
+                go-version-file: go.mod   # Reads 'go' directive from go.mod
+                cache: true
+            # go.mod should specify 'go 1.22.3' matching or exceeding the toolchain directive
+            - run: go build ./...
+  - language: yaml
+    label: 'Remove toolchain directive from go.mod to avoid the download trigger'
+    code: |
+      # In go.mod, remove the toolchain line if your project does not require a
+      # minimum toolchain version beyond what setup-go installs:
+      # BEFORE (triggers GOTOOLCHAIN=auto download):
+      # go 1.21
+      # toolchain go1.22.3
+      #
+      # AFTER (no automatic download):
+      # go 1.22.3
+      # (no toolchain directive)
+      #
+      # Run `go mod tidy` with GOTOOLCHAIN=local after editing go.mod to clean up.
+prevention:
+  - "Set `GOTOOLCHAIN: local` as a job-level env var in all Go workflows to prevent unexpected toolchain downloads"
+  - "When upgrading Go versions, use `go-version-file: go.mod` in setup-go so CI always installs the correct version"
+  - "After running `go mod tidy` locally with Go 1.21+, check whether a `toolchain` directive was added to go.mod before committing"
+  - "In air-gapped environments, always set GOTOOLCHAIN=local and pre-bake the required toolchain into the self-hosted runner image"
+docs:
+  - url: 'https://go.dev/doc/toolchain'
+    label: 'Go Toolchains — official documentation for GOTOOLCHAIN and toolchain directive'
+  - url: 'https://go.dev/blog/toolchain'
+    label: 'Go Blog: Go Toolchains (Go 1.21 announcement)'
+  - url: 'https://github.com/actions/setup-go/blob/main/README.md'
+    label: 'actions/setup-go README — go-version-file input'
+  - url: 'https://pkg.go.dev/cmd/go#hdr-Go_toolchain_management'
+    label: 'go command: toolchain management — GOTOOLCHAIN environment variable'

package/errors/triggers/deployment-status-all-types-default.yml

@@ -0,0 +1,123 @@
+id: triggers-063
+title: 'on.deployment_status fires for all deployment lifecycle statuses by default — add types: to filter'
+category: triggers
+severity: warning
+tags:
+  - deployment_status
+  - deployment
+  - event-types
+  - trigger
+  - duplicate-runs
+  - types-filter
+patterns:
+  - regex: 'on:\s*\n\s*deployment_status:'
+    flags: 'ms'
+  - regex: 'deployment_status:\s*$'
+    flags: 'i'
+error_messages:
+  - '(no error — workflow fires unexpectedly multiple times per deployment)'
+root_cause: |
+  The `on.deployment_status` event fires whenever the status of a deployment changes.
+  A single end-to-end deployment lifecycle emits SIX distinct status events in sequence:
+    created → queued → in_progress → success (or failure / error)
+  Plus `inactive` when an older deployment is superseded by a new one.
+
+  When a workflow uses `on: deployment_status:` without a `types:` filter, it runs for
+  EVERY one of these status transitions. For a typical deployment:
+  - GitHub creates the deployment (fires `deployment_status` with state `created`)
+  - The deployment starts running (fires `in_progress`)
+  - The deployment completes (fires `success`)
+  - Any prior deployment for the same environment becomes inactive (fires `inactive`)
+
+  This causes a workflow to run 3-4 times per deployment. Common consequences:
+  - Post-deployment smoke tests run before the deployment is complete (`in_progress` run)
+  - Notification steps send duplicate Slack/email messages for each status transition
+  - Downstream `workflow_run` triggers fire multiple times, causing race conditions
+  - GitHub-billed Actions minutes are wasted on unwanted runs
+
+  The `deployment_status` event does not have sensible defaults for status filtering —
+  unlike `pull_request` (which defaults to `opened`, `synchronize`, `reopened`),
+  `deployment_status` has no default type filter and fires for everything.
+
+  Note: This is analogous to `on.pull_request_review` firing for all review types by
+  default (documented in triggers-062). Both events require explicit `types:` filters
+  to limit scope to meaningful actions.
+fix: |
+  Add a `types:` filter to `on.deployment_status` to limit which status transitions
+  trigger the workflow. For most use cases:
+  - Post-deployment tests: use `types: [success]`
+  - Deployment monitoring: use `types: [failure, error]`
+  - Full lifecycle tracking: use `types: [in_progress, success, failure, error]`
+
+  Additionally, add an `if:` condition using `github.event.deployment_status.state`
+  for fine-grained control when multiple types are needed.
+fix_code:
+  - language: yaml
+    label: 'Filter to success only — post-deployment smoke tests'
+    code: |
+      on:
+        deployment_status:
+          types:
+            - success   # Only runs when deployment reaches success state
+
+      jobs:
+        smoke-test:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Run smoke tests against deployed environment
+              run: |
+                ENV_URL="${{ github.event.deployment_status.environment_url }}"
+                echo "Testing $ENV_URL"
+                curl -f "$ENV_URL/health"
+  - language: yaml
+    label: 'Filter to failure and error — deployment monitoring'
+    code: |
+      on:
+        deployment_status:
+          types:
+            - failure
+            - error
+
+      jobs:
+        alert:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Notify on deployment failure
+              run: |
+                echo "Deployment failed: ${{ github.event.deployment_status.state }}"
+                echo "Environment: ${{ github.event.deployment.environment }}"
+  - language: yaml
+    label: 'Multiple types with runtime if: check for nuanced handling'
+    code: |
+      on:
+        deployment_status:
+          types:
+            - success
+            - failure
+            - error
+
+      jobs:
+        post-deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Run tests on success
+              if: github.event.deployment_status.state == 'success'
+              run: echo "Running post-deployment tests"
+
+            - name: Alert on failure
+              if: |
+                github.event.deployment_status.state == 'failure' ||
+                github.event.deployment_status.state == 'error'
+              run: echo "Alerting on deployment failure"
+prevention:
+  - "Always add `types:` to `on.deployment_status` — the default of no filter fires for all 6 status transitions"
+  - "Check `github.event.deployment_status.state` in workflow conditions when using multiple status types"
+  - "Use `environment_url` from `github.event.deployment_status` to target the correct environment in post-deployment tests"
+  - "Monitor your Actions run history after deploying — multiple runs per deployment indicates a missing types: filter"
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#deployment_status'
+    label: 'GitHub Docs: deployment_status event — activity types'
+  - url: 'https://docs.github.com/en/rest/deployments/statuses?apiVersion=2022-11-28'
+    label: 'GitHub REST API: Deployment statuses — state values'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#github-context'
+    label: 'GitHub Docs: github.event.deployment_status context fields'

package/errors/yaml-syntax/workflow-call-boolean-input-default-string.yml

@@ -0,0 +1,122 @@
+id: yaml-syntax-058
+title: 'on.workflow_call.inputs boolean default must be YAML boolean not a quoted string — default: ''true'' causes validation error'
+category: yaml-syntax
+severity: error
+tags:
+  - workflow-call
+  - reusable-workflow
+  - inputs
+  - boolean
+  - default
+  - validation-error
+  - type-mismatch
+patterns:
+  - regex: 'Unexpected\s+value\s+''true'''
+    flags: 'i'
+  - regex: 'Unexpected\s+value\s+''false'''
+    flags: 'i'
+  - regex: 'on\.workflow_call\.inputs\.[^.]+\.default.*''(?:true|false)'''
+    flags: 'i'
+  - regex: 'default:\s+''(?:true|false)'''
+    flags: 'i'
+error_messages:
+  - "Invalid workflow file: .github/workflows/deploy.yml: on.workflow_call.inputs.dry_run.default: Unexpected value 'true'"
+  - "Unexpected value 'true'"
+  - "Unexpected value 'false'"
+  - "on.workflow_call.inputs.X.default: Unexpected value 'true'"
+root_cause: |
+  In GitHub Actions, `on.workflow_call.inputs` supports three types: `string`, `boolean`,
+  and `number`. When declaring a `type: boolean` input, the `default:` value must be
+  a YAML boolean literal (`true` or `false`), NOT a quoted string (`'true'` or `'false'`).
+
+  Quoted strings ('true', 'false') are YAML string scalars. GitHub Actions validates
+  the `default:` value against the declared input `type:`, and when a string is given
+  where a boolean is expected, workflow validation fails with:
+    "on.workflow_call.inputs.X.default: Unexpected value 'true'"
+
+  This mistake is extremely common for two reasons:
+  1. Developers working with YAML often quote boolean-like values defensively to avoid
+     YAML parsing surprises — but in this specific field, the quotes cause the error.
+  2. The error message "Unexpected value 'true'" is confusing: `true` is expected, but
+     the quotes around it in the error output make it look like 'true' is a bad value,
+     not that the quotes themselves are the problem.
+
+  This is distinct from `silent-failures/workflow-call-boolean-input-string-coercion.yml`
+  which covers the receiving side: even when defaults are declared correctly, the called
+  workflow receives boolean input values as strings ('true'/'false') in the `inputs`
+  context and must compare using `== 'true'` not `== true`. This entry is about the
+  DECLARATION error before the workflow even runs.
+fix: |
+  Remove the quotes from the `default:` value for `type: boolean` inputs in
+  `on.workflow_call.inputs`. Use bare YAML booleans `true` and `false`.
+
+  If you want to document the type explicitly, add a `description:` field instead of
+  relying on the default value to communicate the type.
+fix_code:
+  - language: yaml
+    label: 'WRONG: quoted string default causes validation error'
+    code: |
+      # BROKEN: 'true' is a string, not a boolean — validation fails
+      on:
+        workflow_call:
+          inputs:
+            dry_run:
+              type: boolean
+              default: 'true'   # ERROR: Unexpected value 'true'
+              description: 'Run in dry-run mode'
+  - language: yaml
+    label: 'CORRECT: bare YAML boolean for default value'
+    code: |
+      # FIXED: true (no quotes) is a YAML boolean — validation passes
+      on:
+        workflow_call:
+          inputs:
+            dry_run:
+              type: boolean
+              default: true    # Correct YAML boolean literal
+              description: 'Run in dry-run mode (default: enabled)'
+            skip_tests:
+              type: boolean
+              default: false   # Correct YAML boolean literal
+              description: 'Skip test suite'
+  - language: yaml
+    label: 'Complete reusable workflow with correct boolean inputs'
+    code: |
+      # .github/workflows/deploy-reusable.yml
+      on:
+        workflow_call:
+          inputs:
+            environment:
+              type: string
+              required: true
+              description: 'Target environment: staging or production'
+            dry_run:
+              type: boolean
+              default: false    # bare boolean, no quotes
+              description: 'Perform a dry run without making changes'
+            notify:
+              type: boolean
+              default: true     # bare boolean, no quotes
+              description: 'Send Slack notification on completion'
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            # Note: inputs.dry_run arrives as the STRING 'true' or 'false'
+            # in the job body — compare with == 'true', not == true
+            - if: inputs.dry_run != 'true'
+              run: echo "Deploying to ${{ inputs.environment }}"
+prevention:
+  - "Never quote boolean default values in workflow_call inputs — use bare `true` or `false`"
+  - "Remember that while the DECLARATION requires bare booleans, the VALUE received by steps is always a string: compare with `== 'true'`, not `== true`"
+  - "Run `actionlint` locally to catch input type/default mismatches before pushing"
+  - "Validate workflow files with `gh workflow view` or push to a test branch to surface validation errors early"
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_call'
+    label: 'GitHub Docs: workflow_call inputs — supported types and default values'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#using-inputs-and-secrets-in-a-reusable-workflow'
+    label: 'GitHub Docs: Reusable workflow inputs'
+  - url: 'https://github.com/orgs/community/discussions/39357'
+    label: 'GitHub Community: workflow_call input type validation discussion'

package/package.json

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