@htekdev/actions-debugger 1.0.23 → 1.0.24

package/errors/yaml-syntax/composite-action-secrets-context-unavailable.yml

@@ -0,0 +1,99 @@
+id: yaml-syntax-025
+title: "secrets Context Unavailable Inside Composite Action Definitions"
+category: yaml-syntax
+severity: error
+tags:
+  - composite-actions
+  - secrets-context
+  - expression
+  - runner-validation
+  - context-availability
+  - action-yml
+patterns:
+  - regex: "Unrecognized named-value.*'?secrets'?"
+    flags: "i"
+  - regex: "Unexpected value.*secrets\\.\\w+"
+    flags: "i"
+error_messages:
+  - "Unrecognized named-value: 'secrets'. Located at position 1 within expression: secrets.MY_TOKEN"
+  - "Error: Unrecognized named-value: 'secrets'"
+  - "Invalid workflow file: .github/actions/my-action/action.yml (Line 12, Col 18): Unrecognized named-value: 'secrets'"
+root_cause: |
+  The `secrets` context is **not available inside composite action definitions** (`action.yml`).
+  When a developer writes `${{ secrets.MY_TOKEN }}` inside a composite action's steps or
+  expressions, runner validation rejects it with "Unrecognized named-value: 'secrets'".
+
+  This is a deliberate architectural restriction. Composite actions run in the calling
+  workflow's runner environment but do NOT receive the calling workflow's secrets context.
+  The `secrets` context is only available in:
+  - Regular workflow job steps (`jobs.<job_id>.steps.*`)
+  - Reusable workflows (`.github/workflows/*.yml` using `on: workflow_call`)
+
+  Composite actions (`action.yml` with `using: composite`) only receive values the calling
+  workflow explicitly passes as `inputs`. This differs from `vars` context rejection
+  (yaml-syntax-016) — both contexts are unavailable in composite actions, but the pattern
+  for passing secrets as inputs is worth documenting separately.
+
+  A common migration mistake: extracting workflow steps that reference `${{ secrets.GITHUB_TOKEN }}`
+  into a composite action and expecting them to continue working unchanged.
+fix: |
+  Declare an explicit `input` for each secret the composite action needs. The calling workflow
+  passes secrets at the `with:` level — where the secrets context IS available. Inside the
+  composite action, reference `${{ inputs.token }}` instead of `${{ secrets.MY_TOKEN }}`.
+
+  Never reference the secrets context directly inside `action.yml` regardless of runner version.
+fix_code:
+  - language: yaml
+    label: "action.yml — Replace secrets.* with an explicit input"
+    code: |
+      # ❌ BROKEN: secrets context not available in composite actions
+      # .github/actions/deploy/action.yml
+      name: Deploy
+      description: Deploy to production
+      runs:
+        using: composite
+        steps:
+          - name: Authenticate
+            shell: bash
+            run: |
+              # ❌ Will fail: Unrecognized named-value: 'secrets'
+              echo "${{ secrets.DEPLOY_TOKEN }}" | docker login ghcr.io -u user --password-stdin
+
+      ---
+
+      # ✅ CORRECT: accept token via explicit input
+      name: Deploy
+      description: Deploy to production
+      inputs:
+        deploy-token:
+          description: "Authentication token for container registry"
+          required: true
+      runs:
+        using: composite
+        steps:
+          - name: Authenticate
+            shell: bash
+            run: echo "${{ inputs.deploy-token }}" | docker login ghcr.io -u user --password-stdin
+  - language: yaml
+    label: "Calling workflow — pass secrets at the with: level"
+    code: |
+      # ✅ Caller resolves secrets context and passes value as composite action input
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: ./.github/actions/deploy
+              with:
+                deploy-token: ${{ secrets.DEPLOY_TOKEN }}  # secrets resolved in caller, not in composite
+prevention:
+  - "Never reference `secrets.*` directly inside composite action `action.yml` — require callers to pass secrets as explicit inputs."
+  - "When migrating workflow steps to a composite action, replace every `${{ secrets.X }}` with a declared input and update all callers."
+  - "Use `actionlint` to statically validate context access in composite actions before pushing."
+  - "Composite actions (composite) require explicit input passing for secrets; reusable workflows (workflow_call) support `secrets: inherit`."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#context-availability"
+    label: "GitHub Docs: Context availability by element type"
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action"
+    label: "GitHub Docs: Creating a composite action"
+  - url: "https://stackoverflow.com/questions/73821801/unable-to-use-secrets-in-workflow"
+    label: "SO#73821801 — Unrecognized named-value: 'secrets' in composite action (3,059 views)"

package/errors/yaml-syntax/github-script-octokit-renamed-to-github.yml

@@ -0,0 +1,130 @@
+id: yaml-syntax-026
+title: "actions/github-script: 'octokit' Not Defined — API Client Renamed to 'github'"
+category: yaml-syntax
+severity: error
+tags:
+  - github-script
+  - octokit
+  - javascript
+  - api-client
+  - breaking-change
+  - v4
+patterns:
+  - regex: "ReferenceError: octokit is not defined"
+    flags: "i"
+  - regex: "octokit is not defined"
+    flags: "i"
+  - regex: "TypeError: Cannot read propert(?:y|ies) of undefined.*octokit"
+    flags: "i"
+  - regex: "Error: Unhandled error: ReferenceError: octokit is not defined"
+    flags: "i"
+error_messages:
+  - "ReferenceError: octokit is not defined"
+  - "Error: Unhandled error: ReferenceError: octokit is not defined"
+  - "Error: Script failed with exit code 1 — ReferenceError: octokit is not defined"
+root_cause: |
+  In versions of `actions/github-script` prior to v4, the Octokit REST client
+  was injected into the script as a variable named `octokit`. The action was
+  refactored and the variable was renamed to `github` in v4 (released late 2020).
+
+  Many blog posts, Stack Overflow answers, older README examples, and community
+  discussions still use the original `octokit` variable name. Developers copying
+  these examples encounter `ReferenceError: octokit is not defined` at runtime
+  because the variable no longer exists.
+
+  Available variables injected into `actions/github-script` scripts (v4+):
+  - `github`   — authenticated Octokit REST + GraphQL client (replaces old `octokit`)
+  - `context`  — workflow run context (repo, sha, ref, event payload, etc.)
+  - `core`     — @actions/core (setOutput, setFailed, info, warning, etc.)
+  - `glob`     — @actions/glob (file globbing utility)
+  - `io`       — @actions/io (filesystem utilities)
+  - `exec`     — @actions/exec (run shell commands from script)
+  - `require`  — restricted require() for loading bundled modules
+
+  The variable `octokit` does not exist in any released version of
+  actions/github-script. It was never a stable public interface — the README
+  always showed `github`, but pre-release/alpha samples used `octokit`.
+
+  A secondary version of this error occurs with `github.rest` vs `github` API
+  surface: in v6+, REST methods moved to `github.rest.*` (e.g.,
+  `github.rest.issues.create()`). Scripts using `github.issues.create()` (v5
+  style) will fail with "TypeError: github.issues.create is not a function"
+  on v6+.
+fix: |
+  Replace every occurrence of `octokit` in your script with `github`:
+
+    Before (broken):  const result = await octokit.rest.issues.create({...})
+    After (correct):  const result = await github.rest.issues.create({...})
+
+  If you are using an older API surface (pre-v6), also update method paths:
+    Before (v5):  await github.issues.create({...})
+    After (v6+):  await github.rest.issues.create({...})
+
+  Check your github-script version — v6 is the current stable release (v7 is
+  also available with Node.js 20). Pin to a major version like @v7 rather than
+  a commit SHA to get bugfixes without breaking changes.
+fix_code:
+  - language: yaml
+    label: "Before (broken) vs After (correct) — replace octokit with github"
+    code: |
+      # BROKEN — uses old `octokit` variable name (throws ReferenceError):
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const { data: issue } = await octokit.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: 'Automated issue',
+              body: 'Created by workflow'
+            });
+
+      # CORRECT — use `github` (the injected Octokit client):
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const { data: issue } = await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: 'Automated issue',
+              body: 'Created by workflow'
+            });
+            console.log('Created issue #' + issue.number);
+  - language: yaml
+    label: "Common github-script v5 to v6+ migration — update method paths"
+    code: |
+      # v5 style (broken on v6+):
+      - uses: actions/github-script@v6
+        with:
+          script: |
+            await github.issues.addLabels({       # BROKEN: no github.issues
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              labels: ['bug']
+            });
+
+      # v6+ style (correct):
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.issues.addLabels({  # CORRECT: github.rest.*
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              labels: ['bug']
+            });
+prevention:
+  - "Always use `github` (not `octokit`) as the Octokit client variable in actions/github-script — `octokit` has never been a stable public interface."
+  - "Pin to a major version like `actions/github-script@v7` rather than copying scripts from undated blog posts or old Stack Overflow answers that may reference pre-release variable names."
+  - "Test scripts locally using the `@octokit/rest` npm package before embedding them in a workflow — you'll get clear errors immediately rather than waiting for a CI run."
+  - "Read the actions/github-script README for your pinned version — the variable reference table at the top shows exactly what is injected (github, context, core, glob, io, exec)."
+  - "When upgrading from github-script v5 to v6+, update all REST method calls from `github.X.Y()` to `github.rest.X.Y()` — this is the only breaking change between v5 and v6."
+docs:
+  - url: "https://github.com/actions/github-script"
+    label: "actions/github-script README — available variables (github, context, core, etc.)"
+  - url: "https://github.com/actions/github-script/issues/545"
+    label: "actions/github-script #545: octokit instance from README examples doesn't work (12 reactions)"
+  - url: "https://github.com/actions/github-script/releases/tag/v4.0.0"
+    label: "actions/github-script v4 release — renamed octokit → github"
+  - url: "https://octokit.github.io/rest.js/v21"
+    label: "Octokit REST.js v21 API reference — methods available via github.rest.*"

package/errors/yaml-syntax/labeler-v5-config-format-breaking.yml

@@ -0,0 +1,67 @@
+id: yaml-syntax-028
+title: "actions/labeler v5 config format breaking change causes unexpected type error"
+category: yaml-syntax
+severity: error
+tags:
+  - labeler
+  - v5-breaking-change
+  - config-format
+  - pull-request-labels
+  - migration
+patterns:
+  - regex: "found unexpected type for label '.+' \\(should be array of config options\\)"
+    flags: "i"
+  - regex: "Error: found unexpected type for label"
+    flags: "i"
+error_messages:
+  - "Error: found unexpected type for label 'frontend' (should be array of config options)"
+  - "found unexpected type for label 'X' (should be array of config options)"
+root_cause: |
+  actions/labeler v5.0.0 introduced a breaking change to the labeler.yml configuration format.
+  In v4 and earlier, labels could be configured as a flat list of glob patterns (strings).
+  In v5, each label must be an array of objects with specific keys such as changed-files,
+  head-branch, or base-branch. If a workflow pins to @master or @latest and a new major
+  version is published, workflows inherit the breaking format without warning.
+  The old flat string format ("label: - path/**") is no longer valid in v5 and causes
+  the action to throw immediately.
+fix: |
+  Either migrate labeler.yml to the v5 object format using changed-files key, or pin the
+  action to @v4 to preserve the old flat string format.
+fix_code:
+  - language: yaml
+    label: "Old v4 format (still works with actions/labeler@v4)"
+    code: |
+      # .github/labeler.yml (v4 format)
+      frontend:
+        - shared/frontend/**/*
+      backend:
+        - shared/api/**/*
+  - language: yaml
+    label: "New v5 format (required for actions/labeler@v5)"
+    code: |
+      # .github/labeler.yml (v5 format)
+      frontend:
+        - changed-files:
+          - any-glob-to-any-file: shared/frontend/**/*
+      backend:
+        - changed-files:
+          - any-glob-to-any-file: shared/api/**/*
+  - language: yaml
+    label: "Pin to v4 to avoid breaking change"
+    code: |
+      steps:
+        - uses: actions/labeler@v4
+          with:
+            repo-token: ${{ secrets.GITHUB_TOKEN }}
+prevention:
+  - "Never pin actions to @master or @latest branch — always use a major version tag like @v4"
+  - "Review the CHANGELOG or release notes before bumping a major version of any action"
+  - "Use Dependabot with major version grouping to get explicit upgrade PRs for breaking changes"
+  - "Test label config changes in a fork or draft PR before merging"
+docs:
+  - url: "https://github.com/actions/labeler/issues/710"
+    label: "actions/labeler#710: found unexpected type for label (v5 breaking change)"
+  - url: "https://github.com/actions/labeler/releases/tag/v5.0.0"
+    label: "actions/labeler v5.0.0 release notes"
+  - url: "https://github.com/actions/labeler/tree/main#pull-request-labeler"
+    label: "actions/labeler v5 configuration documentation"

package/errors/yaml-syntax/runs-on-expression-array-syntax-error.yml

@@ -0,0 +1,121 @@
+id: yaml-syntax-029
+title: "Expression Interpolation in runs-on Array Literal Causes YAML Syntax Error"
+category: yaml-syntax
+severity: error
+tags:
+  - runs-on
+  - self-hosted
+  - expression
+  - dynamic-runner
+  - fromjson
+  - workflow-dispatch
+patterns:
+  - regex: "Invalid workflow file|You have an error in your yaml syntax"
+    flags: "i"
+  - regex: "Unexpected value.*\\$\\{\\{|yaml.*syntax.*runs.on"
+    flags: "i"
+  - regex: "Line.*Col.*Unexpected value.*\\{|error.*yaml.*line.*runs.on"
+    flags: "i"
+error_messages:
+  - "Invalid workflow file: .github/workflows/deploy.yml"
+  - "You have an error in your yaml syntax on line N"
+  - "Error: The workflow is not valid. .github/workflows/....yml (Line: N, Col: N): Unexpected value '{{'"
+  - "Workflow is not valid. (.github/workflows/....yml): There is no event trigger on line N"
+root_cause: |
+  GitHub Actions YAML is fully parsed before any expression evaluation occurs. When an
+  expression like ${{ inputs.runner-label }} appears as a bare value inside a YAML
+  flow sequence (square bracket array), the YAML parser encounters the { character
+  as an unquoted scalar — which is invalid in YAML flow sequence context.
+
+  The error typically surfaces on the job definition line rather than the runs-on
+  line itself, which makes it confusing to diagnose. The workflow annotation says
+  "invalid workflow file" or "yaml syntax error" pointing at the job name line.
+
+  Common trigger: Attempting to dynamically select a self-hosted runner label from
+  a workflow_dispatch input or matrix variable by writing:
+    runs-on: [ self-hosted, ${{ inputs.server-target }} ]
+
+  This is a YAML parsing error, not a GitHub Actions expression error — the file
+  fails validation before any runs even start.
+
+  The idiomatic fix is to pass the label array as a JSON string and deserialize it
+  with fromJSON(), which is supported natively in runs-on since 2021.
+fix: |
+  Three approaches depending on your scenario:
+
+  1. fromJSON() with JSON array input (most flexible, recommended for multi-label):
+     Pass the runs-on labels as a JSON array string and use fromJSON() to deserialize.
+     This fully supports dynamic multi-label selection with no YAML parsing issues.
+
+  2. Quoted expression (for simple labels without YAML-special characters):
+     Quoting the expression as "${{ inputs.label }}" makes it a valid YAML string.
+     Works when the label value is a simple string like "server1" or "linux".
+
+  3. Single dynamic label (when self-hosted prefix is not required):
+     Use runs-on: ${{ inputs.runner_target }} directly without the array syntax.
+     Self-hosted runners can be identified by unique label alone.
+fix_code:
+  - language: yaml
+    label: "fromJSON() — pass full label array as JSON string (recommended)"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            runs_on:
+              description: 'Runner labels as JSON array (e.g. ["self-hosted","linux"])'
+              required: true
+              type: string
+              default: '["self-hosted", "linux"]'
+
+      jobs:
+        build:
+          runs-on: ${{ fromJSON(inputs.runs_on) }}
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "Running on labels ${{ inputs.runs_on }}"
+
+  - language: yaml
+    label: "Quoted expression — for simple label values without YAML-special chars"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              description: 'Target environment runner label'
+              required: true
+              default: 'staging'
+
+      jobs:
+        deploy:
+          runs-on: [ self-hosted, "${{ inputs.environment }}" ]
+          steps:
+            - run: echo "Deploying to ${{ inputs.environment }}"
+
+  - language: yaml
+    label: "Single dynamic label without array syntax"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            runner_target:
+              description: 'Self-hosted runner label (e.g. server1, server2)'
+              required: true
+              default: 'server1'
+
+      jobs:
+        deploy:
+          runs-on: ${{ inputs.runner_target }}
+          steps:
+            - run: echo "Running on ${{ inputs.runner_target }}"
+prevention:
+  - "Never place bare ${{ }} expressions inside YAML flow sequences (square bracket arrays) — always quote or use fromJSON()."
+  - "For dynamic multi-label runner selection, use the fromJSON() pattern with a JSON-string workflow input."
+  - "Validate workflow YAML before committing with: gh workflow list --repo owner/repo or a local YAML linter."
+  - "Document expected input format in the workflow input description: 'JSON array, e.g. [\"self-hosted\",\"linux\"]'."
+docs:
+  - url: "https://stackoverflow.com/questions/68732881/how-do-you-use-an-input-variable-to-specify-which-self-hosted-runner-a-github-ac"
+    label: "Stack Overflow: Input variable for self-hosted runner in runs-on"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on"
+    label: "GitHub Docs: jobs.<job_id>.runs-on workflow syntax"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions#fromjson"
+    label: "GitHub Docs: fromJSON() expression function"

package/errors/yaml-syntax/setup-go-matrix-version-float-coercion.yml

@@ -0,0 +1,69 @@
+id: yaml-syntax-027
+title: "setup-go matrix version YAML float coercion installs wrong Go version"
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - setup-go
+  - matrix
+  - yaml-float
+  - version-mismatch
+  - go-version
+  - silent-failure
+patterns:
+  - regex: "Setup go version spec 1\\.2(?!\\d)"
+    flags: "i"
+  - regex: "Acquiring go1\\.2\\.2 from"
+    flags: "i"
+error_messages:
+  - "Setup go version spec 1.2"
+  - "Acquiring go1.2.2 from https://storage.googleapis.com/golang/go1.2.2.linux-amd64.tar.gz"
+  - "Error: The operation was canceled."
+  - "Attempting to download 1.2..."
+  - "Not found in manifest.  Falling back to download directly from Go"
+root_cause: |
+  When go-version is specified as a bare number in a matrix (e.g., version: [1.22]),
+  YAML parses the value 1.22 as a floating-point number. Due to floating-point precision,
+  this gets coerced to the string "1.2" when the action processes it, dropping the trailing
+  zero. setup-go then resolves "1.2" to the latest 1.2.x release, which is Go 1.2.2 from 2013.
+  This silent failure causes the wrong Go version to be installed, or the action errors out
+  when 1.2.2 cannot be downloaded, with no clear indication that the version string was silently
+  truncated by YAML parsing.
+fix: |
+  Quote the go-version value in the matrix to force YAML to treat it as a string, or append
+  .x to make the version unambiguous. Alternatively, use go-version-file: go.mod to derive
+  the version from your repository's go.mod file.
+fix_code:
+  - language: yaml
+    label: "Quote version in matrix (prevents YAML float coercion)"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              go-version: ['1.22', '1.23', '1.24']
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/setup-go@v5
+              with:
+                go-version: ${{ matrix.go-version }}
+  - language: yaml
+    label: "Use go-version-file instead (recommended)"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+        - uses: actions/setup-go@v5
+          with:
+            go-version-file: 'go.mod'
+prevention:
+  - "Always quote go-version values in YAML matrix (e.g., '1.22', not 1.22)"
+  - "Use the .x wildcard suffix to explicitly request latest patch: '1.22.x'"
+  - "Prefer go-version-file: go.mod to avoid hardcoding versions entirely"
+  - "Verify installed version with a 'run: go version' step after setup"
+  - "This truncation affects any two-component semver ending in zero: 1.20 -> 1.2, 1.10 -> 1.1"
+docs:
+  - url: "https://github.com/actions/setup-go/issues/507"
+    label: "actions/setup-go#507: Go version 1.22 gets parsed to 1.2.2"
+  - url: "https://github.com/actions/setup-go#supported-version-syntax"
+    label: "setup-go: Supported version syntax"
+  - url: "https://yaml.org/type/float.html"
+    label: "YAML float type specification"

package/package.json

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