@htekdev/actions-debugger 1.0.124 → 1.0.125

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

@@ -0,0 +1,128 @@
+id: yaml-syntax-075
+title: 'environment: shorthand string format silently rejects needs.* and jobs.* contexts — use environment.name form'
+category: yaml-syntax
+severity: error
+tags:
+  - environment
+  - dynamic-environment
+  - needs-context
+  - expression
+  - shorthand
+  - template-validation
+patterns:
+  - regex: 'Unrecognized named-value.*needs.*environment'
+    flags: 'i'
+  - regex: "Unrecognized named-value: 'needs'.*position.*expression.*needs\\."
+    flags: 'i'
+  - regex: 'TemplateValidationException.*Unrecognized named-value.*needs'
+    flags: 'i'
+error_messages:
+  - "The workflow is not valid. .github/workflows/deploy.yml (Line: 15, Col: 18): Unrecognized named-value: 'needs'. Located at position 1 within expression: needs.set_environment.outputs.my_env"
+  - "Unrecognized named-value: 'needs'. Located at position 1 within expression: needs.X.outputs.env"
+root_cause: |
+  The GitHub Actions workflow parser supports two forms for specifying a job environment:
+
+  1. Shorthand string: `environment: production` or `environment: ${{ some.expression }}`
+  2. Explicit mapping: `environment:\n  name: ${{ expression }}\n  url: ${{ expression }}`
+
+  The shorthand string form (`environment: ${{ ... }}`) supports only a limited expression
+  context and does NOT support the `needs.*` or `jobs.*` contexts, even when the job
+  has `needs:` declared. Attempting to use `needs.X.outputs.Y` inside the shorthand
+  produces a TemplateValidationException at workflow parse time:
+
+    "Unrecognized named-value: 'needs'. Located at position 1 within expression: needs.X.outputs.Y"
+
+  The explicit mapping form (`environment:\n  name: ${{ ... }}`) DOES support the `needs.*`
+  context fully — this is the documented way to set a dynamic environment name or URL.
+
+  This trips up developers who:
+  - Copy the shorthand form from documentation examples and add an expression.
+  - Want to choose between staging/production environments based on the branch output
+    of an earlier job.
+  - Try to set a dynamic environment URL using `needs.deploy.outputs.url`.
+
+  The error appears only at workflow validation time (not at job runtime), which means
+  the entire workflow is rejected before any jobs run.
+fix: |
+  Use the explicit `environment:` mapping format with `name:` and optionally `url:` sub-keys
+  instead of the shorthand string with a `${{ }}` expression.
+
+  The shorthand `environment: ${{ expression }}` is only for literal strings or simple
+  expressions without `needs.*` / `jobs.*`. Once you need cross-job outputs, switch to
+  the explicit form.
+fix_code:
+  - language: yaml
+    label: 'Broken — shorthand with needs.* context causes TemplateValidationException'
+    code: |
+      jobs:
+        determine-env:
+          runs-on: ubuntu-latest
+          outputs:
+            target: ${{ steps.pick.outputs.env }}
+          steps:
+            - id: pick
+              run: echo "env=production" >> $GITHUB_OUTPUT
+
+        deploy:
+          needs: determine-env
+          runs-on: ubuntu-latest
+          # ❌ BROKEN: shorthand does not support needs.* context
+          environment: ${{ needs.determine-env.outputs.target }}
+          steps:
+            - run: echo "deploying"
+
+  - language: yaml
+    label: 'Fixed — explicit environment.name form supports needs.* context'
+    code: |
+      jobs:
+        determine-env:
+          runs-on: ubuntu-latest
+          outputs:
+            target: ${{ steps.pick.outputs.env }}
+          steps:
+            - id: pick
+              run: |
+                if [[ "${{ github.ref_name }}" == "main" ]]; then
+                  echo "env=production" >> $GITHUB_OUTPUT
+                else
+                  echo "env=staging" >> $GITHUB_OUTPUT
+                fi
+
+        deploy:
+          needs: determine-env
+          runs-on: ubuntu-latest
+          # ✅ FIXED: explicit name: sub-key supports needs.* context
+          environment:
+            name: ${{ needs.determine-env.outputs.target }}
+            url: ${{ needs.deploy.outputs.deploy_url }}
+          steps:
+            - run: echo "deploying to ${{ needs.determine-env.outputs.target }}"
+
+  - language: yaml
+    label: 'Dynamic environment from workflow_dispatch input — correct form'
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              required: true
+              type: environment
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          # ✅ Use explicit name: when referencing inputs.* or needs.* contexts
+          environment:
+            name: ${{ inputs.environment }}
+          steps:
+            - run: echo "deploying to ${{ inputs.environment }}"
+prevention:
+  - 'Always use the `environment:\n  name: ${{ }}` form (never the shorthand string) when the environment name is dynamic or derived from another job.'
+  - 'Remember: `environment: ${{ expression }}` is valid syntax but only for literal strings — it silently ignores `needs.*` context at parse time, producing a hard error.'
+  - 'Lint with actionlint (v1.7.0+) which detects this pattern before pushing.'
+docs:
+  - url: 'https://github.com/actions/runner/issues/998'
+    label: 'actions/runner#998 — Setting job environment dynamically fails with needs context in shorthand form'
+  - url: 'https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment'
+    label: 'GitHub Docs — jobs.<job_id>.environment syntax reference'
+  - url: 'https://stackoverflow.com/questions/65826284/use-dynamic-input-value-for-environment-in-github-actions-workflow-job'
+    label: 'Stack Overflow — Dynamic environment in GitHub Actions workflow job (many upvotes)'

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

@@ -0,0 +1,107 @@
+id: yaml-syntax-076
+title: 'actionlint <=1.7.7 rejects valid `entrypoint` and `command` keys on service containers — schema lag after April 2026 GitHub changelog'
+category: yaml-syntax
+severity: error
+tags:
+  - actionlint
+  - service-container
+  - entrypoint
+  - command
+  - schema-lag
+  - linting
+  - CI-check
+patterns:
+  - regex: 'unexpected key "entrypoint" for "services" section'
+    flags: 'i'
+  - regex: 'unexpected key "command" for "services" section'
+    flags: 'i'
+  - regex: 'unexpected key "(?:entrypoint|command)" for "services" section\. expected one of "credentials", "env", "image", "options", "ports", "volumes"'
+    flags: 'i'
+error_messages:
+  - '.github/workflows/test.yaml:9:9: unexpected key "entrypoint" for "services" section. expected one of "credentials", "env", "image", "options", "ports", "volumes" [syntax-check]'
+  - '.github/workflows/test.yaml:10:9: unexpected key "command" for "services" section. expected one of "credentials", "env", "image", "options", "ports", "volumes" [syntax-check]'
+root_cause: |
+  GitHub Actions added support for `entrypoint` and `command` keys on service container
+  definitions on April 2, 2026 (GitHub Actions: Early April 2026 updates changelog). These
+  new keys allow overriding the service container's default entrypoint and command directly from
+  workflow YAML, matching Docker Compose semantics:
+
+  ```yaml
+  services:
+    redis:
+      image: redis
+      entrypoint: redis-server
+      command: --save 60 1 --loglevel warning
+  ```
+
+  actionlint versions <=1.7.7 validate service container keys against a hardcoded schema that
+  only permits `credentials`, `env`, `image`, `options`, `ports`, and `volumes`. When a workflow
+  uses the new `entrypoint` or `command` keys, actionlint reports them as unknown properties with
+  a `[syntax-check]` error.
+
+  This causes CI pipelines that run actionlint as a lint check to fail even though the workflow
+  is perfectly valid on GitHub.com. The fix was merged into actionlint on April 19, 2026 and
+  released in v1.7.8.
+
+  This is a schema-lag pattern: a new GitHub Actions feature was released before the static
+  analysis tool's schema was updated to recognize it, causing a false-positive lint failure.
+fix: |
+  **Primary fix: Upgrade actionlint to >=1.7.8.**
+  The fix was merged April 19, 2026 (rhysd/actionlint#644). Update your CI pipeline to use
+  actionlint >=1.7.8:
+
+  ```yaml
+  - name: Run actionlint
+    uses: raven-actions/actionlint@v2
+    with:
+      version: latest  # or pin to 1.7.8+
+  ```
+
+  **Temporary workaround (if upgrading is not immediately possible):** Add an inline ignore
+  comment to suppress the false-positive while on the older actionlint version:
+
+  ```yaml
+  services:
+    redis:
+      image: redis
+      entrypoint: redis-server  # actionlint:ignore
+      command: --save 60 1      # actionlint:ignore
+  ```
+fix_code:
+  - language: yaml
+    label: 'Upgrade actionlint in CI to >=1.7.8 to recognize entrypoint/command service keys'
+    code: |
+      - name: Run actionlint
+        uses: raven-actions/actionlint@v2
+        with:
+          version: 1.7.8  # Minimum version that supports entrypoint/command on service containers
+  - language: yaml
+    label: 'Valid service container workflow using new entrypoint/command keys (GitHub Actions only)'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          services:
+            redis:
+              image: redis:7
+              # These keys are valid on GitHub Actions (GA April 2, 2026)
+              # but require actionlint >=1.7.8 for linting to pass
+              entrypoint: redis-server
+              command: --save 60 1 --loglevel warning
+              ports:
+                - 6379:6379
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run tests
+              run: npm test
+prevention:
+  - 'Pin actionlint to a specific version in CI and include it in your Dependabot or Renovate configuration so schema updates are picked up promptly when new GitHub Actions features are released.'
+  - 'When a new GitHub Actions feature ships, check the actionlint changelog (https://github.com/rhysd/actionlint/releases) for schema support before using the feature in linted workflows.'
+  - 'Use `# actionlint:ignore` comment as a short-term workaround for valid-but-unknown-to-linter keys while waiting for the schema update.'
+docs:
+  - url: 'https://github.com/rhysd/actionlint/issues/644'
+    label: 'rhysd/actionlint#644 — Add support for entrypoint and command for service containers (fixed in v1.7.8)'
+  - url: 'https://github.blog/changelog/2026-04-02-github-actions-early-april-2026-updates/'
+    label: 'GitHub Changelog — April 2026 updates: entrypoint and command overrides for service containers'
+  - url: 'https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idservicesservice_identrypoint'
+    label: 'GitHub Docs — Workflow syntax: jobs.<job_id>.services.<service_id>.entrypoint'

package/package.json

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