@htekdev/actions-debugger 1.0.85 → 1.0.87

package/errors/caching-artifacts/upload-artifact-storage-quota-exceeded.yml

@@ -0,0 +1,76 @@
+id: caching-artifacts-050
+title: "upload-artifact@v4 fails when artifact storage quota is exceeded"
+category: caching-artifacts
+severity: error
+tags:
+  - upload-artifact
+  - storage-quota
+  - v4
+  - billing
+  - artifact-cleanup
+patterns:
+  - regex: 'Artifact storage quota has been hit'
+    flags: i
+  - regex: 'unable to upload any new artifacts'
+    flags: i
+  - regex: 'storage limit.*exceeded'
+    flags: i
+error_messages:
+  - "Artifact storage quota has been hit, unable to upload any new artifacts. Please remove some old artifacts or increase storage for the repo."
+root_cause: |
+  GitHub Actions artifact storage has per-account limits (500 MB for free plans, 2 GB for Pro,
+  50 GB for Teams, and custom limits for Enterprise). Unlike actions/upload-artifact@v3 which
+  used a legacy backend, v4 strictly enforces storage quotas and fails hard when the limit
+  is exceeded. Old artifacts from previous workflow runs accumulate over time and are not
+  automatically purged unless a retention policy is set. Once the quota is hit, all subsequent
+  artifact uploads fail immediately with no partial upload.
+fix: |
+  1. Set retention-days on all upload-artifact steps to automatically expire old artifacts.
+  2. Delete old artifacts programmatically using the GitHub REST API via actions/github-script.
+  3. Increase artifact and log storage in GitHub billing settings (Org/User Settings -> Billing -> Storage).
+  4. Audit artifact size — only upload what is necessary for debugging or downstream jobs.
+fix_code:
+  - language: yaml
+    label: "Set retention-days to auto-expire artifacts"
+    code: |
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: dist/
+          retention-days: 7   # auto-delete after 7 days; default is 90
+
+  - language: yaml
+    label: "Delete artifacts older than 30 days via GitHub API script"
+    code: |
+      - name: Clean up old artifacts
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const cutoff = new Date();
+            cutoff.setDate(cutoff.getDate() - 30);
+            const artifacts = await github.paginate(
+              github.rest.actions.listArtifactsForRepo,
+              { owner: context.repo.owner, repo: context.repo.repo, per_page: 100 }
+            );
+            for (const artifact of artifacts) {
+              if (new Date(artifact.created_at) < cutoff) {
+                await github.rest.actions.deleteArtifact({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  artifact_id: artifact.id,
+                });
+              }
+            }
+prevention:
+  - "Always set retention-days on upload-artifact steps — default is 90 days which fills storage quickly"
+  - "Upload only the minimum files needed for debugging or downstream jobs, not entire build directories"
+  - "Add a weekly scheduled workflow to delete artifacts older than your retention window"
+  - "Monitor storage usage under GitHub Settings -> Billing & plans -> Storage"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/storing-workflow-data-as-artifacts#configuring-a-custom-artifact-retention-period"
+    label: "GitHub Docs: Custom artifact retention period"
+  - url: "https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-actions/about-billing-for-github-actions#included-storage-and-minutes"
+    label: "GitHub Docs: Included storage and minutes"
+  - url: "https://github.com/actions/upload-artifact/issues/577"
+    label: "actions/upload-artifact#577: Storage quota exceeded on v4"

package/errors/permissions-auth/fine-grained-pat-resource-owner-mismatch.yml

@@ -0,0 +1,75 @@
+id: permissions-auth-050
+title: "Fine-grained PAT with wrong resource owner causes 'repository not found' in checkout"
+category: permissions-auth
+severity: error
+tags:
+  - fine-grained-pat
+  - checkout
+  - resource-owner
+  - PAT
+  - authentication
+patterns:
+  - regex: 'repository.*not found'
+    flags: i
+  - regex: 'remote: Repository not found'
+    flags: i
+  - regex: 'fatal: unable to access.*403'
+    flags: i
+error_messages:
+  - "fatal: repository 'https://github.com/org/repo.git/' not found"
+  - "remote: Repository not found."
+  - "Error: fatal: unable to access 'https://github.com/org/repo.git/': The requested URL returned error: 403"
+root_cause: |
+  Fine-grained personal access tokens (PATs) require selecting a resource owner when created —
+  either your personal account or a specific organization. A token scoped to a personal account
+  (e.g., user alice) cannot authenticate to repositories owned by an organization (e.g., myorg),
+  even if alice is a member of myorg with full access. Attempting to use such a PAT in
+  actions/checkout, actions/github-script REST calls, or any GitHub API call targeting the
+  organization's repos results in a misleading "repository not found" or HTTP 403 error. The
+  repository is accessible through the web UI because browser sessions use OAuth-based auth —
+  but the fine-grained PAT token is strictly limited to its configured resource owner scope.
+  Classic PATs (without granular resource scope) do not have this restriction, which is why
+  the problem only appears after migrating to fine-grained PATs.
+fix: |
+  Regenerate the fine-grained PAT selecting the correct resource owner — the organization or
+  user account that owns the target repository. If you need to access repositories across
+  multiple organizations, create one PAT per organization, or use a GitHub App installation
+  token which supports cross-repo access without resource-owner restrictions.
+fix_code:
+  - language: yaml
+    label: "Checkout org repo — PAT must have org as resource owner"
+    code: |
+      # The secret ORG_SCOPED_PAT must be a fine-grained PAT created with
+      # Resource owner = myorg (not your personal account)
+      - uses: actions/checkout@v4
+        with:
+          repository: myorg/private-repo
+          token: ${{ secrets.ORG_SCOPED_PAT }}
+
+  - language: yaml
+    label: "Use a GitHub App installation token to avoid resource-owner scope issues"
+    code: |
+      - name: Generate app installation token
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ vars.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+          owner: myorg
+
+      - uses: actions/checkout@v4
+        with:
+          repository: myorg/private-repo
+          token: ${{ steps.app-token.outputs.token }}
+prevention:
+  - "When creating a fine-grained PAT, verify the Resource owner dropdown matches the organization or user that OWNS the target repository"
+  - "Name secrets descriptively: ORG_SCOPED_PAT vs USER_SCOPED_PAT to avoid mixing tokens with different owners"
+  - "Prefer GitHub App installation tokens for multi-repo or cross-org access — they have no resource-owner scoping restriction"
+  - "Classic PATs (repo scope) remain an option if fine-grained token resource-owner scoping is causing confusion"
+docs:
+  - url: "https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token"
+    label: "GitHub Docs: Creating a fine-grained personal access token"
+  - url: "https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#about-fine-grained-personal-access-tokens"
+    label: "GitHub Docs: About fine-grained PATs and resource owner scope"
+  - url: "https://github.com/actions/checkout?tab=readme-ov-file#checkout-a-different-private-repository"
+    label: "actions/checkout: Checkout a different private repository"

package/errors/runner-environment/github-script-require-relative-path-cwd.yml

@@ -0,0 +1,74 @@
+id: runner-environment-150
+title: "actions/github-script relative require() fails — CWD is not GITHUB_WORKSPACE"
+category: runner-environment
+severity: error
+tags:
+  - github-script
+  - require
+  - nodejs
+  - working-directory
+  - module-not-found
+patterns:
+  - regex: 'Cannot find module'
+    flags: i
+  - regex: 'MODULE_NOT_FOUND'
+    flags: ''
+error_messages:
+  - "Error: Cannot find module './my-helper'"
+  - "Error: Cannot find module '../utils/helper'"
+  - "{ code: 'MODULE_NOT_FOUND' }"
+root_cause: |
+  The actions/github-script action evaluates the script: block in a Node.js context where the
+  current working directory (CWD) is a temporary internal directory used by the action runtime —
+  NOT $GITHUB_WORKSPACE. As a result, relative require() calls like require('./helpers/my-util')
+  fail with "Cannot find module" even when the file exists in the repository workspace. This
+  surprises developers who assume the script evaluates from the repository root directory.
+  Note: This is distinct from missing npm packages (runner-environment-136) — the file exists
+  on disk but is not found because Node.js resolves the relative path from the wrong base directory.
+fix: |
+  Construct an absolute path using process.env.GITHUB_WORKSPACE before calling require(). The
+  GITHUB_WORKSPACE environment variable is always set to the repository root in hosted runners.
+  Alternatively, use the recommended pattern from the actions/github-script docs: point to the
+  absolute path via a template literal.
+fix_code:
+  - language: yaml
+    label: "Use absolute path via process.env.GITHUB_WORKSPACE"
+    code: |
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const myHelper = require(`${process.env.GITHUB_WORKSPACE}/scripts/my-helper.js`);
+            await myHelper.run(github, context);
+
+  - language: yaml
+    label: "Pass workspace as env var for explicit clarity"
+    code: |
+      - uses: actions/github-script@v7
+        env:
+          WORKSPACE: ${{ github.workspace }}
+        with:
+          script: |
+            const helper = require(`${process.env.WORKSPACE}/scripts/helper.js`);
+            const result = helper.compute();
+            core.setOutput('result', result);
+
+  - language: yaml
+    label: "Use path.resolve for cross-platform safety"
+    code: |
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const path = require('path');
+            const utils = require(path.resolve(process.env.GITHUB_WORKSPACE, 'lib', 'utils.js'));
+            utils.run();
+prevention:
+  - "Never use relative require() paths in github-script — always construct absolute paths with process.env.GITHUB_WORKSPACE"
+  - "Print process.cwd() in debug runs to confirm the actual CWD — it will not be your repo root"
+  - "For complex shared logic, consider a composite action or a dedicated JS action that has proper module resolution"
+docs:
+  - url: "https://github.com/actions/github-script?tab=readme-ov-file#run-a-separate-file"
+    label: "actions/github-script: Run a separate file (recommended pattern)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables"
+    label: "GitHub Docs: GITHUB_WORKSPACE default environment variable"
+  - url: "https://github.com/actions/github-script/issues/390"
+    label: "actions/github-script#390: Cannot find module with relative path"

package/errors/runner-environment/runner-environment-151.yml

@@ -0,0 +1,93 @@
+id: runner-environment-151
+title: "Docker container action creates root-owned files causing Permission denied in following steps"
+category: runner-environment
+severity: error
+tags:
+  - docker
+  - container-action
+  - file-permissions
+  - root-user
+  - workspace
+patterns:
+  - regex: 'Permission denied'
+    flags: i
+  - regex: 'EACCES: permission denied'
+    flags: i
+  - regex: 'cannot open .+ Permission denied'
+    flags: i
+  - regex: 'error: open .+ permission denied'
+    flags: i
+error_messages:
+  - "Permission denied"
+  - "cannot create directory '...': Permission denied"
+  - "EACCES: permission denied, open '/github/workspace/...'"
+  - "error: cannot open '.git/COMMIT_EDITMSG': Permission denied"
+  - "chown: changing ownership of '...': Operation not permitted"
+root_cause: |
+  Docker-based GitHub Actions — both `uses: docker://image:tag` inline steps and
+  actions with `runs.using: docker` in their action.yml — run their container process
+  as root (UID 0) by default unless the Dockerfile explicitly sets a USER directive.
+
+  Any files written to `GITHUB_WORKSPACE` (mounted at `/github/workspace` inside the
+  container) are created with root ownership (uid=0, gid=0). Subsequent workflow steps
+  run as the `runner` user (UID 1001) and cannot read, modify, or delete root-owned
+  files, causing "Permission denied" errors.
+
+  The failure is especially common when:
+  - A Docker action writes build artifacts, generated code, or lock files.
+  - A subsequent step tries to commit changes or run tools on the generated output.
+  - The workflow uses `actions/checkout` after a Docker action and git operations fail.
+fix: |
+  Option 1 — Chown the workspace after the Docker action (easiest for third-party actions):
+    Add a step after the Docker action: `sudo chown -R "$USER:$(id -gn)" "$GITHUB_WORKSPACE"`
+
+  Option 2 — Set USER in the Dockerfile (best for actions you control):
+    Add `USER 1001` (runner UID) to the action's Dockerfile so all written files
+    are owned by the runner user.
+
+  Option 3 — Use --user flag in the Docker run args:
+    Set `args` in the action's action.yml to include `--user=1001:127`.
+fix_code:
+  - language: yaml
+    label: "Fix: chown workspace after Docker action (works for any Docker-based action)"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+
+        - name: Run Docker-based action
+          uses: docker://my-build-image:latest
+          with:
+            args: '--output /github/workspace/dist'
+
+        - name: Fix file ownership after Docker action
+          run: sudo chown -R "$USER:$(id -gn)" "$GITHUB_WORKSPACE"
+
+        - name: Use build output (now accessible as runner user)
+          run: ls -la dist/ && cat dist/output.txt
+  - language: yaml
+    label: "Fix: set non-root USER in Dockerfile (preferred when controlling the action)"
+    code: |
+      # In your Docker action's Dockerfile — run as UID 1001 to match GitHub runner
+      # FROM ubuntu:22.04
+      # RUN useradd -u 1001 -g 127 runner
+      # WORKDIR /github/workspace
+      # USER 1001
+      # ENTRYPOINT ["/entrypoint.sh"]
+      
+      # With this Dockerfile, no chown step is needed — files are owned by runner user
+      steps:
+        - uses: actions/checkout@v4
+        - uses: ./  # local Docker action with non-root USER
+        - run: cat generated-output.txt  # accessible without permission errors
+prevention:
+  - "Always set a non-root USER directive in Dockerfiles for actions that write to the workspace."
+  - "After any third-party Docker action, add a chown step before accessing created files."
+  - "Prefer JavaScript/TypeScript or composite actions over Docker actions when workspace I/O is needed — they run as the runner user by default."
+  - "Test Docker actions locally with UID 1001 to catch permission issues before CI."
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/dockerfile-support-for-github-actions"
+    label: "Dockerfile support for GitHub Actions"
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-docker-container-action"
+    label: "Creating a Docker container action"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables"
+    label: "GITHUB_WORKSPACE default environment variable"

package/errors/silent-failures/checkout-path-github-workspace-unchanged.yml

@@ -0,0 +1,91 @@
+id: silent-failures-079
+title: "actions/checkout path: input doesn't change GITHUB_WORKSPACE — subsequent steps use wrong directory"
+category: silent-failures
+severity: silent-failure
+tags:
+  - checkout
+  - path
+  - GITHUB_WORKSPACE
+  - working-directory
+  - subdirectory
+patterns:
+  - regex: 'No such file or directory'
+    flags: i
+  - regex: 'ENOENT.*no such file'
+    flags: i
+error_messages:
+  - "No such file or directory"
+  - "ENOENT: no such file or directory"
+root_cause: |
+  When actions/checkout is used with a path: input (e.g., path: app), the repository is
+  checked out into $GITHUB_WORKSPACE/app. However, the GITHUB_WORKSPACE environment variable
+  continues to point to the root workspace directory (/home/runner/work/repo-name/repo-name),
+  not to the path: subdirectory. Any subsequent run: steps that use ${{ github.workspace }}
+  or rely on the default working directory will NOT operate inside the checkout subdirectory.
+  This causes file-not-found errors that are hard to debug because the checkout step succeeds
+  and the files do exist — just not at the location subsequent steps expect. This is a
+  particularly common footgun when checking out multiple repositories into different subdirs.
+fix: |
+  Explicitly specify working-directory on all run: steps that operate on the checked-out code,
+  OR set a job-level defaults.run.working-directory. Alternatively, avoid path: unless you
+  need multiple checkouts — the default checkout places files directly at $GITHUB_WORKSPACE.
+fix_code:
+  - language: yaml
+    label: "Use working-directory to point to the checkout subdirectory"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          path: app
+
+      - name: Build
+        working-directory: ${{ github.workspace }}/app
+        run: npm install && npm run build
+
+  - language: yaml
+    label: "Set job-level default working-directory"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          defaults:
+            run:
+              working-directory: ./app
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                path: app
+            - run: npm install && npm run build
+
+  - language: yaml
+    label: "Multiple checkouts — use explicit paths for each"
+    code: |
+      steps:
+        - uses: actions/checkout@v4
+          with:
+            repository: myorg/frontend
+            path: frontend
+
+        - uses: actions/checkout@v4
+          with:
+            repository: myorg/backend
+            path: backend
+
+        - name: Build frontend
+          working-directory: frontend
+          run: npm ci && npm run build
+
+        - name: Build backend
+          working-directory: backend
+          run: go build ./...
+prevention:
+  - "Prefer the default checkout (no path:) unless checking out multiple repos in the same job"
+  - "When path: is used, always add defaults.run.working-directory at the job level"
+  - "Never use ${{ github.workspace }} to reference files from a path:-redirected checkout without appending the path value"
+  - "Use echo $GITHUB_WORKSPACE and ls $GITHUB_WORKSPACE in debug steps to verify directory contents"
+docs:
+  - url: "https://github.com/actions/checkout?tab=readme-ov-file#usage"
+    label: "actions/checkout: path input documentation"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_iddefaultsrun"
+    label: "GitHub Docs: jobs.defaults.run.working-directory"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables"
+    label: "GitHub Docs: GITHUB_WORKSPACE default environment variable"

package/errors/silent-failures/silent-failures-080.yml

@@ -0,0 +1,97 @@
+id: silent-failures-080
+title: "github.event.commits always empty array on pull_request events"
+category: silent-failures
+severity: silent-failure
+tags:
+  - pull-request
+  - commits
+  - event-payload
+  - skip-ci
+  - multi-trigger
+patterns:
+  - regex: 'github\.event\.commits\[0\]'
+    flags: i
+  - regex: 'Cannot read propert\w+ of undefined.*message'
+    flags: i
+error_messages:
+  - "Error: Cannot read properties of undefined (reading 'message')"
+  - "github.event.commits[0] evaluates to null on pull_request events"
+  - "contains(github.event.commits[0].message, '[skip ci]') always false on PRs"
+root_cause: |
+  The `github.event.commits` array is only populated in `push` event payloads.
+  On `pull_request` events, `github.event.commits` is always an empty array `[]`.
+  Accessing `github.event.commits[0]` returns `null`, and
+  `github.event.commits[0].message` returns an empty string without throwing an
+  expression error.
+
+  This is the most common footgun when implementing "[skip ci]" commit message
+  detection: the condition works correctly for `push` events but silently never
+  triggers (never skips) on `pull_request` events. The workflow runs for every PR
+  push regardless of the commit message.
+
+  The issue affects any multi-trigger workflow with both `push:` and `pull_request:`
+  that reads commit data from the event payload.
+fix: |
+  Guard `github.event.commits` access by event type, or use PR-specific context:
+  1. Use `if: github.event_name == 'push'` before accessing commits.
+  2. For PR events, check `github.event.pull_request.title` or `github.event.pull_request.body`
+     for skip conditions.
+  3. Use the `actions/github-script` action to query commits via the REST API on PR events.
+  4. Consider separate workflows for push and pull_request to avoid cross-event payload confusion.
+fix_code:
+  - language: yaml
+    label: "Wrong: commit message check silently fails on pull_request events"
+    code: |
+      on: [push, pull_request]
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          # github.event.commits[0].message is null on pull_request — condition always false
+          if: "!contains(github.event.commits[0].message, '[skip ci]')"
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm test
+  - language: yaml
+    label: "Fix: guard by event type and use PR-appropriate skip signal"
+    code: |
+      on: [push, pull_request]
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Check skip condition
+              id: skip
+              run: |
+                SKIP=false
+                if [[ "${{ github.event_name }}" == "push" ]]; then
+                  # Commits array is available on push events
+                  if echo "${{ github.event.commits[0].message }}" | grep -q '\[skip ci\]'; then
+                    SKIP=true
+                  fi
+                elif [[ "${{ github.event_name }}" == "pull_request" ]]; then
+                  # Check PR title or body for skip signal on PR events
+                  if echo "${{ github.event.pull_request.title }}" | grep -q '\[skip ci\]'; then
+                    SKIP=true
+                  fi
+                fi
+                echo "skip=$SKIP" >> "$GITHUB_OUTPUT"
+
+            - name: Run tests
+              if: steps.skip.outputs.skip != 'true'
+              run: npm test
+prevention:
+  - "Never access github.event.commits on workflows with pull_request triggers — it will always be empty."
+  - "Use separate workflows for push and pull_request if commit-message-based conditionals are required."
+  - "For PR skip conditions, use the PR title or body rather than commit messages."
+  - "Check which fields are populated for each event type in the GitHub webhook event payload documentation."
+docs:
+  - url: "https://docs.github.com/en/webhooks/webhook-events-and-payloads#push"
+    label: "Push webhook event payload (commits array)"
+  - url: "https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request"
+    label: "Pull request webhook event payload"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-conditions-to-control-job-execution"
+    label: "Using conditions to control job execution"

package/errors/triggers/triggers-059.yml

@@ -0,0 +1,106 @@
+id: triggers-059
+title: "workflow_call required: true inputs silently receive empty string when omitted by caller"
+category: triggers
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - workflow-call
+  - inputs
+  - required
+  - validation
+patterns:
+  - regex: 'required.*input.*not provided'
+    flags: i
+  - regex: 'Input .+ is required but was not provided'
+    flags: i
+error_messages:
+  - "Input 'environment' is required but was not provided"
+  - "required: true input silently receives empty string when omitted from caller with:"
+root_cause: |
+  When a reusable workflow declares `on.workflow_call.inputs` with `required: true`,
+  GitHub does NOT enforce this requirement at call time via the REST API or from other
+  calling workflows. The `required: true` flag is informational documentation only —
+  it is not validated before the workflow runs.
+
+  When a calling workflow omits a required input from its `with:` block, the reusable
+  workflow receives an empty string `""` for the missing input with no error or warning.
+  The workflow starts and runs to whatever conclusion the empty input causes.
+
+  This leads to silent failures such as deploying to an undefined environment, running
+  against an empty target URL, or passing `""` to shell commands that produce incorrect
+  results. The bug is especially hard to find because the calling workflow shows a green
+  "success" until the silent empty input causes a downstream failure.
+fix: |
+  Explicitly validate all required inputs at the start of the reusable workflow:
+  1. Add an input-validation step as the FIRST step of the FIRST job that checks each
+     required input for emptiness and fails with a descriptive error.
+  2. Use `default:` values in `on.workflow_call.inputs` to handle omitted inputs
+     gracefully with a fallback rather than silently using empty string.
+  3. In calling workflows, always pass all inputs explicitly with `with:` — never
+     rely on `required: true` to catch missing inputs.
+fix_code:
+  - language: yaml
+    label: "Reusable workflow: validate required inputs at startup"
+    code: |
+      # .github/workflows/deploy.yml (reusable workflow)
+      on:
+        workflow_call:
+          inputs:
+            environment:
+              required: true   # documentation only — NOT enforced by GitHub
+              type: string
+            target-url:
+              required: true
+              type: string
+
+      jobs:
+        validate-inputs:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Validate required inputs
+              run: |
+                ERRORS=()
+                if [[ -z "${{ inputs.environment }}" ]]; then
+                  ERRORS+=("Required input 'environment' was not provided")
+                fi
+                if [[ -z "${{ inputs.target-url }}" ]]; then
+                  ERRORS+=("Required input 'target-url' was not provided")
+                fi
+                if [[ ${#ERRORS[@]} -gt 0 ]]; then
+                  for ERR in "${ERRORS[@]}"; do
+                    echo "::error::$ERR"
+                  done
+                  exit 1
+                fi
+
+        deploy:
+          needs: validate-inputs
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying to ${{ inputs.environment }}"
+  - language: yaml
+    label: "Fix: use default: values to avoid silent empty string behavior"
+    code: |
+      on:
+        workflow_call:
+          inputs:
+            environment:
+              required: false
+              default: 'staging'   # explicit default instead of relying on required: true
+              type: string
+      
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying to ${{ inputs.environment }}"  # always 'staging' if omitted
+prevention:
+  - "Treat required: true on workflow_call inputs as documentation only — always validate inside the reusable workflow."
+  - "Add a dedicated input-validation job as the first job in every reusable workflow with required inputs."
+  - "Prefer default: values over required: true when a sensible fallback exists."
+  - "In calling workflows, always explicitly pass all inputs in the with: block."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onworkflow_callinputs"
+    label: "on.workflow_call.inputs syntax reference"
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows#using-inputs-and-secrets-in-a-called-workflow"
+    label: "Using inputs in a called workflow"

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

@@ -0,0 +1,94 @@
+id: yaml-syntax-054
+title: "env context silently empty in reusable workflow with: inputs"
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - env-context
+  - with-inputs
+  - workflow-call
+  - context-availability
+patterns:
+  - regex: '"env" context is not available in this context'
+    flags: i
+  - regex: 'env context.*not available.*reusable'
+    flags: i
+error_messages:
+  - '"env" context is not available in this context'
+  - "Input evaluates to empty string when env context used in reusable workflow with:"
+root_cause: |
+  The `env` context is NOT available inside `jobs.<job_id>.with:` blocks used to
+  call reusable workflows. Unlike `jobs.<job_id>.steps.with:` (regular action steps,
+  which support `env` context), reusable workflow `with:` inputs are evaluated before
+  job-level environment variables are injected.
+
+  Using `${{ env.MY_VAR }}` in a reusable workflow `with:` block silently evaluates
+  to an empty string. No error is thrown and the reusable workflow receives `""` for
+  that input. The actionlint static linter reports:
+  `"env" context is not available in this context`.
+
+  This is explicitly documented in GitHub's context availability table — `env` is
+  available in `jobs.<job_id>.steps.with` but NOT in `jobs.<job_id>.with`.
+fix: |
+  Replace `env` context references in reusable workflow `with:` blocks with one of:
+  1. `vars` context — for repository or organization-level configuration variables
+     (Settings → Variables). Available in reusable workflow `with:`.
+  2. Inline literal values directly in `with:`.
+  3. Workflow-level `inputs:` context if the calling workflow is itself a reusable
+     workflow (chain input passing).
+  4. A prior job that captures the value and passes it via `needs.<job>.outputs`.
+fix_code:
+  - language: yaml
+    label: "Wrong: env context in reusable workflow with: (silently evaluates to empty string)"
+    code: |
+      env:
+        BASE_URL: 'https://api.example.com'
+        DEPLOY_ENV: 'production'
+
+      jobs:
+        call-deploy:
+          uses: ./.github/workflows/deploy.yml
+          with:
+            api-url: ${{ env.BASE_URL }}    # silently empty — env unavailable in reusable with:
+            environment: ${{ env.DEPLOY_ENV }}  # also silently empty
+  - language: yaml
+    label: "Fix: use vars context or inline value"
+    code: |
+      # Set BASE_URL as a repository variable in Settings → Secrets and variables → Variables
+      jobs:
+        call-deploy:
+          uses: ./.github/workflows/deploy.yml
+          with:
+            api-url: ${{ vars.BASE_URL }}       # vars IS available in reusable with:
+            environment: 'production'            # inline literal also works
+  - language: yaml
+    label: "Fix: pass via prior job output if value is dynamic"
+    code: |
+      jobs:
+        resolve-config:
+          runs-on: ubuntu-latest
+          outputs:
+            api-url: ${{ steps.config.outputs.url }}
+          steps:
+            - id: config
+              run: echo "url=$BASE_URL" >> "$GITHUB_OUTPUT"
+              env:
+                BASE_URL: ${{ env.BASE_URL }}  # env IS available in step env:
+
+        call-deploy:
+          needs: resolve-config
+          uses: ./.github/workflows/deploy.yml
+          with:
+            api-url: ${{ needs.resolve-config.outputs.api-url }}  # needs context available
+prevention:
+  - "Consult the GitHub Actions context availability table before using contexts in reusable workflow with: blocks."
+  - "Prefer vars context (repository/org variables) over env for values shared across workflows."
+  - "Run actionlint in CI — it detects unavailable context usage and catches this before runtime."
+  - "If a reusable workflow input is silently empty, check context availability as the first debugging step."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#context-availability"
+    label: "GitHub Actions context availability table"
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows#passing-inputs-and-secrets-to-a-called-workflow"
+    label: "Passing inputs and secrets to a called workflow"
+  - url: "https://rhysd.github.io/actionlint/"
+    label: "actionlint — static checker for GitHub Actions"

package/package.json

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