@htekdev/actions-debugger 1.0.23 → 1.0.25

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.25",
   "description": "65+ real GitHub Actions errors, queryable by agents. MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",