@htekdev/actions-debugger 1.0.81 → 1.0.83

package/errors/yaml-syntax/secrets-in-workflow-level-env-block-rejected.yml

@@ -0,0 +1,91 @@
+id: yaml-syntax-051
+title: "secrets context unavailable in top-level workflow env: block — only valid at job/step level"
+category: yaml-syntax
+severity: error
+tags:
+  - secrets
+  - env-block
+  - workflow-level
+  - context-availability
+  - expression-error
+  - validation
+patterns:
+  - regex: 'Context access might be invalid: secrets'
+    flags: 'i'
+  - regex: 'Unrecognized named-value: .secrets.'
+    flags: 'i'
+  - regex: 'The workflow is not valid.*named-value.*secrets'
+    flags: 'i'
+error_messages:
+  - "The workflow is not valid. .github/workflows/build.yml (Line: 5, Col: 20): Unexpected value 'secrets'"
+  - "Context access might be invalid: secrets"
+  - "Unrecognized named-value: 'secrets'. Located at position 1 within expression: secrets.MY_SECRET"
+root_cause: |
+  The secrets context (${{ secrets.* }}) is only available at the job and step level,
+  not at the top-level (workflow-level) env: block. Placing secret references under the
+  top-level env: key generates a workflow validation error because GitHub evaluates
+  the workflow-level env: block before any job context is established and before
+  secret injection has occurred.
+
+  Available secret context locations:
+    OK  jobs.<job_id>.env:
+    OK  jobs.<job_id>.steps[*].env:
+    OK  jobs.<job_id>.steps[*].with:
+    OK  jobs.<job_id>.container.env:
+    OK  jobs.<job_id>.services.<id>.env:
+    NOT OK  env: (top-level, outside jobs:)
+    NOT OK  jobs.<job_id>.if:
+    NOT OK  jobs.<job_id>.steps[*].if:
+
+  This is the most common cause of the "Unexpected value 'secrets'" validation error
+  in newly written workflows. The workflow fails the pre-run validation check and
+  no jobs execute.
+fix: |
+  Move the secrets reference from the top-level env: block down to the job-level or
+  step-level env: block where the secrets context is available.
+fix_code:
+  - language: yaml
+    label: "Wrong: secrets in top-level env: block generates validation error"
+    code: |
+      env:
+        DB_PASSWORD: ${{ secrets.DB_PASSWORD }}   # Invalid at top level
+        API_TOKEN: ${{ secrets.API_TOKEN }}        # Invalid at top level
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - run: ./run-tests.sh
+  - language: yaml
+    label: "Correct: secrets moved to job-level env: block"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          env:
+            DB_PASSWORD: ${{ secrets.DB_PASSWORD }}   # Valid at job level
+            API_TOKEN: ${{ secrets.API_TOKEN }}        # Valid at job level
+          steps:
+            - run: ./run-tests.sh
+  - language: yaml
+    label: "Alternative: secrets at step-level env: for minimal exposure"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Run tests
+              run: ./run-tests.sh
+              env:
+                DB_PASSWORD: ${{ secrets.DB_PASSWORD }}   # Valid at step level
+prevention:
+  - "The top-level env: block only supports literals and expressions that don't reference secrets, needs, or job context"
+  - "Use top-level env: for constants like APP_ENV: production or NODE_ENV: test"
+  - "Prefer step-level env: for secrets to minimize the scope where secrets are exposed"
+  - "actionlint checks context availability and will flag secret-placement errors before push"
+  - "GitHub validates workflow files on push — the validation error appears as a failed check before any job runs"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#context-availability"
+    label: "GitHub Docs: Context availability"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#env"
+    label: "GitHub Docs: Workflow env: syntax"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htekdev/actions-debugger",
-  "version": "1.0.81",
+  "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",