@htekdev/actions-debugger 1.0.1 → 1.0.3

package/errors/silent-failures/sparse-checkout-sticky-cone-mode.yml

@@ -0,0 +1,120 @@
+id: silent-failures-008
+title: "Sparse Checkout Persists to Subsequent Checkout Steps (Sticky Cone Mode)"
+category: silent-failures
+severity: silent-failure
+tags:
+  - checkout
+  - sparse-checkout
+  - cone-mode
+  - composite-actions
+  - file-missing
+patterns:
+  - regex: "sparse.*checkout.*persist"
+    flags: "i"
+  - regex: "core\\.sparseCheckout.*true"
+    flags: "i"
+  - regex: "sparse-checkout.*not disabled"
+    flags: "i"
+error_messages:
+  - "Run actions/checkout@v4"
+  - "Expected full checkout but only sparse tree present"
+root_cause: |
+  When `actions/checkout` is called with `sparse-checkout:` options, it sets the git
+  repository's `core.sparseCheckout = true` config. A subsequent call to `actions/checkout`
+  in the same job — even WITHOUT specifying sparse-checkout — re-uses the existing git
+  repository and inherits the sticky `core.sparseCheckout = true` setting.
+
+  Result: the second checkout appears to succeed (no error), but the working directory
+  still contains only the sparse subset from the first checkout. Files outside the
+  original sparse pattern are silently absent.
+
+  This most commonly occurs in two scenarios:
+  1. A workflow calls `actions/checkout` with sparse-checkout for a fast initial clone,
+     then calls `actions/checkout` again (different ref, different path spec) expecting
+     a full checkout.
+  2. A workflow uses sparse-checkout, then calls a composite action that internally runs
+     its own `actions/checkout`. The composite action's checkout inherits the sparse
+     setting from the parent workflow's checkout.
+
+  Root cause: a bug in `actions/checkout` — the `disableSparseCheckout()` method does not
+  explicitly set `core.sparseCheckout false` when `sparse-checkout` input is absent. A
+  fix PR (#2034) exists in the repo but has not been merged as of 2026.
+fix: |
+  **Option 1 (recommended): Explicitly reset sparse-checkout between checkouts**
+  Add a `git sparse-checkout disable` step between the sparse and full checkouts. This
+  clears the sticky `core.sparseCheckout` flag and ensures subsequent checkouts are full.
+
+  **Option 2: Use separate `path:` directories**
+  Checkout into a unique subdirectory with the `path:` input to prevent git config
+  sharing. Each `path:` gets its own `.git` config.
+
+  **Option 3: Use `sparse-checkout-cone-mode: false` carefully**
+  When in non-cone mode, review that patterns don't accidentally match more or fewer
+  files than expected. Non-cone mode with incorrect patterns is its own source of
+  silent failures.
+fix_code:
+  - language: yaml
+    label: "Reset sparse-checkout before a subsequent full checkout"
+    code: |
+      steps:
+        # First checkout: sparse (fast clone for config files only)
+        - uses: actions/checkout@v4
+          with:
+            sparse-checkout: |
+              .github
+              config/
+
+        - name: Reset sparse-checkout so next checkout is full
+          shell: bash
+          run: git sparse-checkout disable
+
+        # Second checkout (in composite action or next step): now gets full tree
+        - uses: actions/checkout@v4
+          with:
+            ref: ${{ github.sha }}
+  - language: yaml
+    label: "Use separate path: directories to avoid shared git config"
+    code: |
+      steps:
+        # Sparse checkout into 'config-only/' subdirectory
+        - uses: actions/checkout@v4
+          with:
+            path: config-only
+            sparse-checkout: |
+              config/
+
+        # Full checkout into 'full-repo/' — completely separate git repo config
+        - uses: actions/checkout@v4
+          with:
+            path: full-repo
+  - language: yaml
+    label: "Composite action defensive reset (add to composite action's beginning)"
+    code: |
+      # In your composite action's action.yml — reset sparse before own checkout
+      runs:
+        using: composite
+        steps:
+          - name: Reset any inherited sparse-checkout
+            shell: bash
+            run: |
+              if git rev-parse --git-dir > /dev/null 2>&1; then
+                git sparse-checkout disable 2>/dev/null || true
+              fi
+
+          - uses: actions/checkout@v4
+            with:
+              ref: ${{ inputs.ref }}
+prevention:
+  - "Never assume a subsequent `actions/checkout` step gets a full tree if any earlier step used sparse-checkout."
+  - "Add `git sparse-checkout disable` as an explicit step between sparse and full checkouts in the same job."
+  - "When writing composite actions that call `actions/checkout`, add a defensive `git sparse-checkout disable` before your checkout step."
+  - "Use the `path:` input to isolate checkouts that need different content into separate directories."
+docs:
+  - url: "https://github.com/actions/checkout/issues/1498"
+    label: "actions/checkout#1498: Sparse checkout persists in composite action"
+  - url: "https://github.com/actions/checkout/pull/2034"
+    label: "actions/checkout#2034: Fix — disable sparse-checkout on subsequent checkout (open PR)"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsuses"
+    label: "Workflow syntax: steps.uses"
+  - url: "https://github.com/actions/checkout#usage"
+    label: "actions/checkout: Usage and sparse-checkout options"

package/errors/triggers/environment-protection-rules-silent-block.yml

@@ -0,0 +1,105 @@
+id: triggers-006
+title: "Job Blocked Silently by Environment Protection Rules — No Clear Log Message"
+category: triggers
+severity: warning
+tags:
+  - environment
+  - protection-rules
+  - deployment
+  - approval
+  - branch-restriction
+  - silent-wait
+patterns:
+  - regex: "Waiting for.*environment.*approval"
+    flags: "i"
+  - regex: "Branch '.*' is not allowed to deploy to .* due to environment protection rules"
+    flags: "i"
+  - regex: "Expected.*Waiting for status to be reported"
+    flags: "i"
+error_messages:
+  - "Branch 'feature/my-branch' is not allowed to deploy to production due to environment protection rules."
+  - "Waiting for approval — This workflow run requires approval from the environment's configured reviewers."
+  - "Expected — Waiting for status to be reported"
+root_cause: |
+  GitHub Environments can have protection rules that gate job execution:
+  - **Required reviewers**: A human must approve the deployment before the job runs.
+  - **Branch/tag restrictions**: Only specific branches or tags are allowed to
+    deploy to the environment (e.g., only `main` can deploy to `production`).
+  - **Required status checks**: External status checks must pass first.
+  - **Wait timers**: A mandatory delay before the job can proceed.
+
+  When a job targets an environment with unsatisfied protection rules, it enters
+  a waiting state in the GitHub UI. The **workflow log may not show a clear
+  failure message** — the job simply appears as pending or "Expected — Waiting
+  for status to be reported." This is a common source of confusion for teams
+  that enable environment protection rules for the first time, especially in
+  forks or feature-branch workflows where the branch is not in the allowed list.
+
+  Documented in GitHub Community discussions #39054 and #26698.
+fix: |
+  1. **Check environment settings**: Repository Settings → Environments → select
+     the environment → review protection rules (required reviewers, deployment
+     branches, required checks, wait timers).
+
+  2. **For branch restriction failures**: Add the branch that the workflow runs
+     on to the environment's "Deployment branches and tags" list, or change the
+     policy to "No restriction" for non-production environments.
+
+  3. **For pending approval**: A configured reviewer must approve the deployment
+     in the GitHub UI (Actions tab → select the run → click "Review deployments").
+
+  4. **For automated CI**: Use a separate environment with no protection rules
+     for automated test deployments, and reserve protected environments for
+     production deployments that require human approval.
+
+  5. **For fork PRs**: Environments with protection rules can silently block
+     fork PRs since the fork branch is not in the allowed branch list — use a
+     separate no-protection environment for fork PR validation jobs.
+fix_code:
+  - language: yaml
+    label: "Use separate environments for CI vs production"
+    code: |
+      jobs:
+        deploy-staging:
+          runs-on: ubuntu-latest
+          environment: staging    # ✅ no protection rules — runs immediately
+          steps:
+            - run: ./deploy.sh staging
+
+        deploy-production:
+          needs: deploy-staging
+          runs-on: ubuntu-latest
+          environment: production  # 🔒 has required reviewers — waits for approval
+          if: github.ref == 'refs/heads/main'  # ✅ only main is in allowed branch list
+          steps:
+            - run: ./deploy.sh production
+  - language: yaml
+    label: "Check branch restriction: ensure workflow branch is in allowed list"
+    code: |
+      # In GitHub UI: Settings → Environments → production → Deployment branches
+      # Add "main" or change policy to match your workflow's ref.
+      #
+      # In workflow: use github.ref_name to verify before targeting environment
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          # Only run on main — matches production environment's branch restriction
+          if: github.ref == 'refs/heads/main'
+          environment: production
+          steps:
+            - run: ./deploy.sh
+prevention:
+  - "Document environment protection rules in your repository's CONTRIBUTING.md so all developers know which branches can deploy where."
+  - "Test protection rules in a staging environment before applying them to production — the silent-wait behavior is surprising on first encounter."
+  - "For automated CI workflows that run on feature branches, use environments without branch restrictions or required reviewers."
+  - "After enabling environment protection rules, verify the workflow can actually trigger by running a test deployment from an allowed branch."
+  - "Monitor for stuck jobs in the Actions tab — a job sitting in 'waiting' or 'Expected' state usually means an environment protection rule is blocking it."
+docs:
+  - url: "https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment"
+    label: "Using environments for deployment — protection rules"
+  - url: "https://github.com/orgs/community/discussions/39054"
+    label: "GitHub Community #39054 — Branch not allowed to deploy due to environment protection rules"
+  - url: "https://github.com/orgs/community/discussions/26698"
+    label: "GitHub Community #26698 — Job stuck in Expected / Waiting for status to be reported"
+  - url: "https://stackoverflow.com/questions/72109150/github-action-avoid-approval-on-same-environment-rule-within-same-workflow"
+    label: "Stack Overflow — Avoiding approval in same environment within same workflow"

package/errors/yaml-syntax/env-context-unavailable-job-level.yml

@@ -0,0 +1,109 @@
+id: yaml-syntax-014
+title: "env Context Not Available at Job-Level if or Reusable Workflow Positions"
+category: yaml-syntax
+severity: error
+tags:
+  - env
+  - context
+  - job-if
+  - reusable-workflow
+  - expression
+  - context-availability
+patterns:
+  - regex: "Unrecognized named-value: 'env'"
+    flags: "i"
+  - regex: "The workflow is not valid.*Unrecognized named-value: 'env'"
+    flags: "i"
+  - regex: "Located at position \\d+ within expression.*env\\."
+    flags: "i"
+error_messages:
+  - "The workflow is not valid. .github/workflows/<workflow>.yml (Line: X, Col: Y): Unrecognized named-value: 'env'. Located at position Z within expression: <expression>"
+  - "Unrecognized named-value: 'env'. Located at position 1 within expression"
+root_cause: |
+  GitHub Actions evaluates job-level expressions (jobs.<job_id>.if, certain
+  jobs.<job_id>.with: inputs for reusable workflows) before any steps run and
+  before step-level env values are available. Because the `env` context is
+  only populated at step execution time, using `env.MY_VAR` inside a job-level
+  `if:` condition or inside a reusable workflow's `jobs:` block triggers a
+  validation error at parse time rather than a runtime failure.
+
+  This affects:
+  - `jobs.<job_id>.if: ${{ env.MY_VAR == 'foo' }}`
+  - `jobs.<job_id>.with:` fields referencing `env.*` in a reusable workflow call
+  - Any top-level workflow expression that attempts to read `env` context
+
+  Documented in actions/runner issues #1189, #1661, and #2372.
+fix: |
+  Replace env context references in job-level positions with contexts that are
+  available at job evaluation time:
+  - Use `vars.*` (repository/environment variables) for static configuration values
+  - Use `github.*` context for event-driven values
+  - Use `inputs.*` for values passed into reusable workflows
+  - Use job outputs (`needs.<job_id>.outputs.<name>`) to pass dynamic values
+    computed in earlier steps to downstream job `if:` conditions
+
+  If the value is truly dynamic and set in a previous step, emit it as a step
+  output → job output → needs output chain so downstream jobs can reference it.
+fix_code:
+  - language: yaml
+    label: "WRONG — env context in job-level if (fails validation)"
+    code: |
+      jobs:
+        deploy:
+          if: ${{ env.DEPLOY_ENV == 'production' }}  # ❌ env not available here
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying"
+  - language: yaml
+    label: "RIGHT — use vars context or job outputs instead"
+    code: |
+      # Option 1: use vars (repository/environment variables) for static config
+      jobs:
+        deploy:
+          if: ${{ vars.DEPLOY_ENV == 'production' }}  # ✅ vars available at job level
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying"
+
+      # Option 2: compute in a preceding job, emit as output
+      jobs:
+        compute-env:
+          runs-on: ubuntu-latest
+          outputs:
+            deploy_env: ${{ steps.set-env.outputs.deploy_env }}
+          steps:
+            - id: set-env
+              run: echo "deploy_env=production" >> $GITHUB_OUTPUT
+
+        deploy:
+          needs: compute-env
+          if: ${{ needs.compute-env.outputs.deploy_env == 'production' }}
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "Deploying"
+  - language: yaml
+    label: "RIGHT — reusable workflow: pass value via inputs not env"
+    code: |
+      # Caller workflow
+      jobs:
+        call-deploy:
+          uses: ./.github/workflows/deploy.yml
+          with:
+            environment: production  # ✅ pass via inputs, not env
+          secrets: inherit
+prevention:
+  - "Consult the GitHub docs context availability table before writing expressions — not all contexts are available at every YAML key position."
+  - "For job-level if conditions, use `vars.*`, `github.*`, or `needs.<job>.outputs.*` — never `env.*`."
+  - "For reusable workflow inputs, pass values explicitly through `with:` inputs rather than relying on caller env context."
+  - "Use `vars` (repository/environment variables) as a replacement for env-based feature flags that need to be available at job evaluation time."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#context-availability"
+    label: "Context availability — which contexts are available at each YAML key"
+  - url: "https://github.com/actions/runner/issues/1189"
+    label: "actions/runner #1189 — Unrecognized named-value: 'env' for job conditional"
+  - url: "https://github.com/actions/runner/issues/1661"
+    label: "actions/runner #1661 — env unrecognised in job-level if when calling reusable workflow"
+  - url: "https://github.com/actions/runner/issues/2372"
+    label: "actions/runner #2372 — Unrecognized named-value: 'env' in reusable workflow jobs"
+  - url: "https://stackoverflow.com/questions/76471787/why-is-env-context-not-available-in-github-action-job-level-if-statement"
+    label: "Stack Overflow — Why is env context not available in job level if statement?"

package/errors/yaml-syntax/reusable-workflow-missing-output-declaration.yml

@@ -0,0 +1,140 @@
+id: yaml-syntax-013
+title: "Reusable Workflow Output Missing on.workflow_call.outputs Declaration"
+category: yaml-syntax
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - workflow-call
+  - outputs
+  - silent-failure
+  - job-outputs
+patterns:
+  - regex: "needs\\.[a-zA-Z0-9_-]+\\.outputs\\.[a-zA-Z0-9_-]+"
+    flags: "i"
+  - regex: "on\\.workflow_call\\.outputs.*not defined"
+    flags: "i"
+  - regex: "output.*reusable.*workflow.*empty"
+    flags: "i"
+error_messages:
+  - "The output variable was not found in the called workflow's on.workflow_call.outputs map."
+  - "Output 'version' not found in called workflow."
+root_cause: |
+  A called (reusable) workflow exposes job-level outputs but forgets to declare them at
+  the `workflow_call` trigger level. As a result the caller workflow's
+  `needs.<called-job>.outputs.<name>` expression evaluates to an empty string with NO
+  error message — a silent failure.
+
+  GitHub Actions requires a two-layer output declaration for reusable workflows:
+  1. The job inside the called workflow declares step outputs via `outputs:` on the job.
+  2. The called workflow's `on.workflow_call.outputs:` section explicitly maps workflow-
+     level output names to job-level output expressions.
+
+  If layer 2 is missing, the caller never receives the value even though layer 1 exists.
+  Because the expression resolves to an empty string (not an error), downstream steps may
+  silently receive wrong values — version tags become empty strings, Docker image names
+  become malformed, deploy environment names become blank.
+
+  A second variant occurs when accessing outputs from a called workflow that uses a matrix:
+  matrix job outputs cannot be aggregated automatically at the workflow level, so outputs
+  from individual matrix legs are inaccessible to the caller.
+fix: |
+  Add the `on.workflow_call.outputs:` section to the called workflow, mapping each
+  desired output name to the corresponding job output expression.
+
+  For matrix jobs: aggregate outputs into a single job (e.g. using `toJSON`) or use a
+  final non-matrix aggregator job inside the called workflow that reads matrix outputs
+  and re-exposes them as a single value.
+fix_code:
+  - language: yaml
+    label: "Called workflow — correct two-layer output declaration"
+    code: |
+      # .github/workflows/build-and-version.yml (CALLED workflow)
+      on:
+        workflow_call:
+          # Layer 2: workflow-level outputs (REQUIRED for caller to receive values)
+          outputs:
+            version:
+              description: "The computed version string"
+              value: ${{ jobs.build.outputs.version }}
+            artifact-name:
+              description: "Name of the uploaded artifact"
+              value: ${{ jobs.build.outputs.artifact-name }}
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          # Layer 1: job-level outputs
+          outputs:
+            version: ${{ steps.compute-version.outputs.version }}
+            artifact-name: ${{ steps.upload.outputs.artifact-name }}
+          steps:
+            - id: compute-version
+              run: echo "version=1.2.3-${{ github.sha }}" >> $GITHUB_OUTPUT
+
+            - id: upload
+              uses: actions/upload-artifact@v4
+              with:
+                name: build-output
+                path: dist/
+  - language: yaml
+    label: "Caller workflow — consuming outputs from called workflow"
+    code: |
+      # .github/workflows/deploy.yml (CALLER workflow)
+      jobs:
+        build:
+          uses: ./.github/workflows/build-and-version.yml
+          secrets: inherit
+
+        deploy:
+          needs: build
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy version
+              # This only works if the called workflow has on.workflow_call.outputs declared
+              run: |
+                echo "Deploying version: ${{ needs.build.outputs.version }}"
+                echo "Using artifact: ${{ needs.build.outputs.artifact-name }}"
+  - language: yaml
+    label: "Aggregate matrix outputs in a final job for caller consumption"
+    code: |
+      # Called workflow with matrix — aggregate results before exposing as outputs
+      on:
+        workflow_call:
+          outputs:
+            all-results:
+              value: ${{ jobs.aggregate.outputs.results }}
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          strategy:
+            matrix:
+              suite: [unit, integration, e2e]
+          outputs:
+            result-${{ matrix.suite }}: ${{ steps.run.outputs.result }}
+          steps:
+            - id: run
+              run: echo "result=passed" >> $GITHUB_OUTPUT
+
+        # Aggregator job: collects matrix outputs and re-exposes as single value
+        aggregate:
+          needs: test
+          runs-on: ubuntu-latest
+          outputs:
+            results: ${{ steps.collect.outputs.results }}
+          steps:
+            - id: collect
+              run: |
+                echo "results=${{ toJSON(needs.test.outputs) }}" >> $GITHUB_OUTPUT
+prevention:
+  - "Always declare `on.workflow_call.outputs:` in a reusable workflow if any caller needs its outputs."
+  - "Test output propagation by printing `${{ needs.<job>.outputs.<name> }}` in a debug step on the caller side."
+  - "Treat empty string outputs from called workflows as a sign of missing `on.workflow_call.outputs:` mapping."
+  - "Matrix jobs inside called workflows require an aggregator job — matrix outputs cannot be directly mapped."
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows#using-outputs-from-a-reusable-workflow"
+    label: "Reusable workflows: using outputs"
+  - url: "https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onworkflow_calloutputs"
+    label: "Workflow syntax: on.workflow_call.outputs"
+  - url: "https://stackoverflow.com/questions/73702333/github-actions-reuse-outputs-from-other-reusable-workflows"
+    label: "Stack Overflow: Reuse outputs from reusable workflows (82 upvotes)"

package/package.json

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