@htekdev/actions-debugger 1.0.97 → 1.0.99

package/errors/known-unsolved/reusable-workflow-github-event-is-workflow-call-event.yml

@@ -0,0 +1,112 @@
+id: known-unsolved-054
+title: 'github.event in a reusable workflow is the workflow_call event, not the caller event'
+category: known-unsolved
+severity: silent-failure
+tags:
+  - reusable-workflow
+  - workflow-call
+  - github-event
+  - context
+  - inputs
+  - github-context
+patterns:
+  - regex: 'github\.event\.(pull_request|commits|release|head_commit)\b'
+    flags: 'i'
+error_messages: []
+root_cause: |
+  When a caller workflow invokes a reusable workflow via jobs.<id>.uses, the
+  github.event context inside the callee is the workflow_call event object,
+  NOT the triggering event (push, pull_request, schedule, etc.) of the caller.
+
+  All event-specific payload fields are undefined inside the reusable workflow
+  and evaluate to empty string or null without any error:
+  - github.event.pull_request (undefined — returns null)
+  - github.event.commits (undefined — returns null)
+  - github.event.release (undefined — returns null)
+  - github.event.head_commit (undefined — returns null)
+  - github.event.inputs (undefined — use inputs context instead)
+
+  Additionally, github.event_name inside the callee always returns 'workflow_call',
+  regardless of what event triggered the caller.
+
+  Importantly, github.ref, github.sha, and github.actor DO retain the caller's
+  values inside the callee — it is specifically github.event and github.event_name
+  that reflect the workflow_call context, not the caller's triggering event.
+
+  This catches developers by surprise when refactoring inline jobs into reusable
+  workflows: the refactored callee silently loses access to the event payload it
+  previously used, with no validation error or warning at parse time or runtime.
+
+  This is by design — reusable workflows execute as independent workflow_call
+  events and there is no mechanism to inherit the caller's event context. GitHub
+  has confirmed this will not change.
+fix: |
+  There is no workaround that exposes the caller's github.event inside the callee.
+  The required approach is to declare all needed event data as explicit inputs:
+  in the reusable workflow and forward them via with: in the caller.
+
+  github.ref, github.sha, and github.actor are available in the callee without
+  any explicit forwarding — they are inherited automatically from the caller context.
+fix_code:
+  - language: yaml
+    label: 'Wrong — accessing caller event payload inside reusable workflow (silently empty)'
+    code: |
+      # .github/workflows/reusable.yml — these are all EMPTY inside the callee
+      on:
+        workflow_call:
+
+      jobs:
+        process:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "PR = ${{ github.event.pull_request.number }}"  # null
+            - run: echo "Event = ${{ github.event_name }}"               # 'workflow_call'
+            - run: echo "Commit = ${{ github.event.head_commit.message }}" # null
+  - language: yaml
+    label: 'Correct — declare inputs in callee and forward event data from caller'
+    code: |
+      # .github/workflows/reusable.yml — declare needed event data as inputs
+      on:
+        workflow_call:
+          inputs:
+            pr_number:
+              type: number
+              default: 0
+              description: 'Pull request number from github.event.pull_request.number'
+            triggering_event:
+              type: string
+              required: true
+              description: 'The caller event name (github.event_name)'
+
+      jobs:
+        process:
+          runs-on: ubuntu-latest
+          steps:
+            - run: echo "PR = ${{ inputs.pr_number }}"
+            - run: echo "Triggered by = ${{ inputs.triggering_event }}"
+            # github.ref and github.sha are safe to use directly — they are inherited
+            - run: echo "SHA = ${{ github.sha }}"
+
+      # ---- CALLER WORKFLOW ----
+      # .github/workflows/caller.yml — forward event data via with:
+      on: [push, pull_request]
+
+      jobs:
+        call-reusable:
+          uses: ./.github/workflows/reusable.yml
+          with:
+            pr_number: ${{ github.event.pull_request.number || 0 }}
+            triggering_event: ${{ github.event_name }}
+prevention:
+  - 'Never access github.event.* fields directly inside a reusable workflow — they will always be empty'
+  - 'github.event_name inside a reusable workflow always returns workflow_call, not the caller event'
+  - 'Declare all required event data as explicit workflow_call inputs and forward with with: in the caller'
+  - 'github.ref, github.sha, and github.actor are inherited from the caller and are safe to use'
+  - 'Add a comment in the reusable workflow reminding contributors not to use github.event directly'
+docs:
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#limitations'
+    label: 'GitHub Docs — Reusing workflows: Limitations'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#github-context'
+    label: 'GitHub Docs — github context'
+  - url: 'https://docs.github.com/en/actions/sharing-automations/reusing-workflows#passing-inputs-and-secrets-to-a-called-workflow'
+    label: 'GitHub Docs — Passing inputs and secrets to a called workflow'

package/errors/permissions-auth/oidc-token-rate-limited-large-parallel-matrix.yml

@@ -0,0 +1,114 @@
+id: permissions-auth-056
+title: 'OIDC token requests rate-limited in large parallel matrix — random 429 job failures'
+category: permissions-auth
+severity: error
+tags:
+  - oidc
+  - id-token
+  - rate-limit
+  - matrix
+  - parallel
+  - aws
+  - gcp
+  - azure
+patterns:
+  - regex: 'Failed to get ID token.*429'
+    flags: 'i'
+  - regex: 'ACTIONS_ID_TOKEN_REQUEST_URL.*429'
+    flags: 'i'
+  - regex: 'No ID token is available.*rate.limit'
+    flags: 'i'
+error_messages:
+  - "Error: Failed to get ID token: Request failed with status code 429"
+  - "Error: Failed to get ID token: Error code: 429"
+root_cause: |
+  GitHub's OIDC token endpoint (ACTIONS_ID_TOKEN_REQUEST_URL) has per-workflow-run
+  rate limits on simultaneous token requests. When a large matrix workflow spawns
+  many parallel jobs (typically 20+) that all request OIDC tokens at the start of
+  their runs, the burst of simultaneous requests can exceed the endpoint's rate
+  limit, and some jobs receive HTTP 429 responses.
+
+  Cloud provider actions that call the OIDC endpoint internally during setup
+  are affected:
+  - aws-actions/configure-aws-credentials
+  - google-github-actions/auth
+  - azure/login (with OIDC federated credentials)
+
+  In a large matrix, all legs start within seconds of each other, creating a
+  simultaneous burst that exceeds the endpoint limit. The failure is
+  non-deterministic: some jobs succeed and some fail on any given run. Manually
+  re-running the failed jobs typically succeeds because the burst window has
+  passed. This intermittent behavior makes the 429 root cause difficult to
+  diagnose without inspecting verbose action output for the HTTP status code.
+
+  The rate limit is enforced per workflow run, not per repository or per user.
+  Actions that include built-in retry logic may mask the error by successfully
+  retrying, but add latency to affected jobs.
+fix: |
+  Reduce parallel OIDC token requests by setting max-parallel on the matrix
+  strategy. A value between 5 and 15 typically prevents rate limit breaches
+  while still providing meaningful parallelism.
+
+  Alternatively, restructure the workflow to acquire a single OIDC-derived
+  credential in a setup job and pass it as a job output to downstream matrix
+  jobs — but this must be done carefully to avoid exposing short-lived tokens
+  in workflow logs. Check the cloud provider's documentation for recommended
+  token-sharing patterns.
+
+  Enable step debug logging (ACTIONS_STEP_DEBUG secret set to 'true') to
+  confirm the 429 root cause when diagnosing intermittent OIDC failures.
+fix_code:
+  - language: yaml
+    label: 'Set max-parallel to prevent simultaneous OIDC token request burst'
+    code: |
+      jobs:
+        deploy:
+          strategy:
+            matrix:
+              region: [us-east-1, us-west-2, eu-west-1, ap-southeast-1, ap-northeast-1,
+                       sa-east-1, ca-central-1, ap-south-1, ap-east-1, eu-central-1]
+            max-parallel: 5  # Prevents simultaneous OIDC token burst
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write
+            contents: read
+          steps:
+            - name: Configure AWS credentials
+              uses: aws-actions/configure-aws-credentials@v4
+              with:
+                role-to-assume: arn:aws:iam::123456789:role/deploy-${{ matrix.region }}
+                aws-region: ${{ matrix.region }}
+            - name: Deploy
+              run: ./scripts/deploy.sh ${{ matrix.region }}
+  - language: yaml
+    label: 'Enable OIDC debug logging to confirm 429 rate limit as root cause'
+    code: |
+      # Add this secret to the repository: ACTIONS_STEP_DEBUG = true
+      # Then re-run the failing workflow and check step logs for:
+      # "Request failed with status code 429"
+      # in the cloud auth action's output to confirm rate limiting.
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          permissions:
+            id-token: write
+          steps:
+            - name: Configure credentials (verbose for debugging)
+              uses: aws-actions/configure-aws-credentials@v4
+              with:
+                role-to-assume: arn:aws:iam::123456789:role/ci-role
+                aws-region: us-east-1
+prevention:
+  - 'Use max-parallel on matrix strategies that use OIDC authentication to limit burst requests'
+  - 'Enable ACTIONS_STEP_DEBUG secret to see HTTP status codes in cloud auth action logs'
+  - 'Treat intermittent OIDC failures in large matrix workflows as a 429 rate limit until proven otherwise'
+  - 'Check whether the cloud auth action has built-in retry logic — some versions retry automatically'
+  - 'Consider staggering matrix jobs with a sleep step if max-parallel alone does not resolve the issue'
+docs:
+  - url: 'https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect'
+    label: 'GitHub Docs — About security hardening with OpenID Connect'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idstrategymax-parallel'
+    label: 'GitHub Docs — jobs.<job_id>.strategy.max-parallel'
+  - url: 'https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/enabling-debug-logging'
+    label: 'GitHub Docs — Enabling debug logging'

package/errors/runner-environment/macos-15-ios-simulator-runtimes-not-preinstalled.yml

@@ -0,0 +1,75 @@
+id: runner-environment-167
+title: "macOS 15 / Xcode 16: iOS Simulator Runtimes Not Pre-Installed — xcodebuild test Fails with No Matching Destination"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - xcode
+  - ios
+  - simulator
+  - xcodebuild
+  - runner-image
+patterns:
+  - regex: 'Unable to find a destination matching the provided destination specifier'
+    flags: i
+  - regex: 'No simulator runtime matching .* was found'
+    flags: i
+  - regex: 'Could not find a simulator destination'
+    flags: i
+error_messages:
+  - "error: Unable to find a destination matching the provided destination specifier: { platform:iOS Simulator, name:iPhone 15 }"
+  - "error: No simulator runtime matching 'iOS 18.0' was found."
+  - "Testing failed: Could not find a destination that satisfied the requested destination specifier."
+  - "xcodebuild: error: 'xcodebuild test' requires a simulator, but no runtimes are installed."
+root_cause: |
+  Starting with Xcode 16 on macOS 15 GitHub-hosted runners, Apple decoupled iOS/iPadOS simulator
+  runtimes from the Xcode installation to reduce download sizes. Unlike Xcode 15 where simulator
+  runtimes for iOS 17 were bundled, Xcode 16 ships without any pre-installed simulator runtimes.
+  Running `xcrun simctl list runtimes` on macos-15 returns an empty list. When `xcodebuild test`
+  is called with an iOS Simulator destination, it fails immediately because there are no runtimes
+  to match against. This affects all iOS, tvOS, and watchOS simulator-based tests.
+fix: |
+  Option 1 — Download the required simulator runtime before testing (adds ~5-10 min):
+    Use `xcrun simctl runtime add <identifier>` to download the runtime.
+  
+  Option 2 — Pin to macos-14 which ships with simulator runtimes pre-installed.
+  
+  Option 3 — Use `xcode-install` or `xcodes` to select an older Xcode with bundled runtimes.
+fix_code:
+  - language: yaml
+    label: "Install iOS simulator runtime before running xcodebuild test"
+    code: |
+      - name: Install iOS 18 Simulator Runtime
+        run: |
+          xcrun simctl runtime add "com.apple.CoreSimulator.SimRuntime.iOS-18-0"
+        timeout-minutes: 15
+      - name: Run iOS Tests
+        run: |
+          xcodebuild test \
+            -scheme MyApp \
+            -destination 'platform=iOS Simulator,name=iPhone 16,OS=18.0'
+  - language: yaml
+    label: "Pin to macos-14 to use pre-installed simulator runtimes"
+    code: |
+      jobs:
+        test:
+          runs-on: macos-14  # Simulator runtimes bundled with Xcode 15
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run iOS Tests
+              run: |
+                xcodebuild test \
+                  -scheme MyApp \
+                  -destination 'platform=iOS Simulator,name=iPhone 15'
+prevention:
+  - "Always pin to a specific macOS version rather than macos-latest for iOS CI workflows"
+  - "Add a `xcrun simctl list runtimes` step early in your workflow to detect missing runtimes fast"
+  - "Check GitHub Actions runner-images release notes when bumping macOS version"
+  - "Budget extra CI time (10-15 min) for simulator runtime download when using Xcode 16+"
+docs:
+  - url: "https://github.com/actions/runner-images/issues/10337"
+    label: "runner-images: Simulator runtimes not pre-installed with Xcode 16"
+  - url: "https://developer.apple.com/documentation/xcode/installing-additional-simulator-runtimes"
+    label: "Apple: Installing Additional Simulator Runtimes"
+  - url: "https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md"
+    label: "macOS 15 Runner Image — Installed Software"

package/errors/runner-environment/pip-install-externally-managed-environment-pep668.yml

@@ -0,0 +1,69 @@
+id: runner-environment-168
+title: "pip install Fails with 'externally-managed-environment' on Ubuntu 22.04/24.04 (PEP 668)"
+category: runner-environment
+severity: error
+tags:
+  - python
+  - pip
+  - pep668
+  - ubuntu-22
+  - ubuntu-24
+  - externally-managed
+patterns:
+  - regex: 'error: externally-managed-environment'
+    flags: i
+  - regex: 'This environment is externally managed'
+    flags: i
+  - regex: 'If you wish to install a non-Debian.*package.*--break-system-packages'
+    flags: i
+error_messages:
+  - "error: externally-managed-environment"
+  - "× This environment is externally managed"
+  - "To install Python packages system-wide, try apt install python3-xyz"
+  - "If you wish to install a non-Debian-packaged Python package, create a virtual environment using python3 -m venv path/to/venv"
+root_cause: |
+  PEP 668 (implemented in Python 3.11+) marks system Python installations as "externally managed"
+  to prevent pip from overwriting system packages managed by the OS package manager (apt, brew, etc.).
+  Ubuntu 22.04 adopted this restriction for its bundled Python 3.10+, and Ubuntu 24.04 enforces it
+  strictly. When a workflow uses the system Python (python3 without actions/setup-python) and runs
+  `pip install`, the installation fails immediately with the "externally-managed-environment" error.
+  This breaks workflows that previously ran pip install directly without a virtual environment.
+fix: |
+  Option 1 (Recommended) — Use actions/setup-python to install an isolated Python:
+    The action installs Python in the tool cache, outside the system-managed environment.
+  
+  Option 2 — Create a virtual environment before running pip:
+    python3 -m venv .venv && source .venv/bin/activate && pip install ...
+  
+  Option 3 (Quick fix, not recommended for CI) — Pass --break-system-packages:
+    pip install --break-system-packages <package>
+fix_code:
+  - language: yaml
+    label: "Use actions/setup-python to avoid externally-managed-environment error"
+    code: |
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install dependencies
+        run: pip install -r requirements.txt  # Uses tool-cache Python, not system Python
+  - language: yaml
+    label: "Use a virtual environment with system Python"
+    code: |
+      - name: Create venv and install
+        run: |
+          python3 -m venv .venv
+          .venv/bin/pip install -r requirements.txt
+      - name: Run tests
+        run: .venv/bin/pytest
+prevention:
+  - "Always use actions/setup-python rather than relying on the runner's system Python"
+  - "If system Python must be used, wrap all pip calls in a virtual environment (python3 -m venv)"
+  - "Avoid pip install --break-system-packages in CI — it risks corrupting the runner environment"
+  - "Pin python-version in setup-python to avoid unexpected upgrades between runner image updates"
+docs:
+  - url: "https://peps.python.org/pep-0668/"
+    label: "PEP 668 — Marking Python base environments as externally managed"
+  - url: "https://github.com/actions/setup-python"
+    label: "actions/setup-python — GitHub"
+  - url: "https://github.com/actions/runner-images/issues/6943"
+    label: "runner-images: PEP 668 externally-managed-environment on Ubuntu 22.04"

package/errors/runner-environment/setup-dotnet-eol-net6-net7-version-not-found.yml

@@ -0,0 +1,72 @@
+id: runner-environment-166
+title: "actions/setup-dotnet Fails Installing EOL .NET 6 and .NET 7 — Version Not Found in Cache or CDN"
+category: runner-environment
+severity: error
+tags:
+  - dotnet
+  - setup-dotnet
+  - eol
+  - version-not-found
+  - net6
+  - net7
+patterns:
+  - regex: 'Error: Version \d+\.\d+\.[\dx]+ was not found in the local cache or download source'
+    flags: i
+  - regex: 'Error: Unable to find dotnet version.*satisf'
+    flags: i
+  - regex: 'Error: Could not find dotnet version matching'
+    flags: i
+error_messages:
+  - "Error: Version 6.0.x was not found in the local cache or download source."
+  - "Error: Unable to find dotnet version that satisfies: 7.0"
+  - "Error: Could not find dotnet version matching '6.x'."
+  - "Failed to install dotnet from official website."
+root_cause: |
+  .NET 6 reached end-of-life on November 12, 2024, and .NET 7 reached end-of-life on May 14, 2024.
+  After EOL, Microsoft removes these SDK builds from the official download CDN
+  (dotnetcli.azureedge.net). actions/setup-dotnet@v4+ will fail with "Version not found" when the
+  requested version is unavailable from Microsoft's servers and is absent from the GitHub-hosted
+  runner tool cache. Workflows pinned to dotnet-version: '6.x', '6.0.x', or '7.x' break silently
+  until CI runs after the removal date — no prior warning is given by the action.
+fix: |
+  Upgrade to a supported .NET LTS version:
+  - .NET 8 (LTS, supported until November 10, 2026)
+  - .NET 9 (STS, supported until May 2026)
+  - .NET 10 (LTS, current preview)
+  
+  Also update <TargetFramework> in .csproj files to match.
+fix_code:
+  - language: yaml
+    label: "Upgrade from EOL .NET 6/7 to .NET 8 LTS"
+    code: |
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '8.x'  # LTS — supported until November 2026
+          # dotnet-version: '6.x'  # EOL November 12, 2024 — will fail
+          # dotnet-version: '7.x'  # EOL May 14, 2024 — will fail
+      - name: Build
+        run: dotnet build
+  - language: yaml
+    label: "Matrix build across multiple supported .NET versions"
+    code: |
+      strategy:
+        matrix:
+          dotnet: ['8.x', '9.x']
+      steps:
+        - uses: actions/setup-dotnet@v4
+          with:
+            dotnet-version: ${{ matrix.dotnet }}
+        - run: dotnet test
+prevention:
+  - "Use only LTS .NET versions in production CI (8.x, 10.x) for maximum support lifetime"
+  - "Track EOL dates at https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core"
+  - "Set a calendar reminder for EOL dates to migrate at least 3 months before end-of-life"
+  - "Enable Dependabot for dotnet-version in workflow files to surface upgrade recommendations"
+docs:
+  - url: "https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core"
+    label: ".NET Support Lifecycle — Microsoft"
+  - url: "https://github.com/actions/setup-dotnet"
+    label: "actions/setup-dotnet — GitHub"
+  - url: "https://github.com/actions/setup-dotnet/issues/475"
+    label: "actions/setup-dotnet: EOL version download failures"

package/errors/silent-failures/macos-latest-upgraded-to-macos-15-xcode-16-swift-6.yml

@@ -0,0 +1,71 @@
+id: silent-failures-089
+title: "macos-latest Silently Upgraded to macOS 15 (Sequoia) — Xcode 16 and Swift 6 Strictness"
+category: silent-failures
+severity: silent-failure
+tags:
+  - macos
+  - xcode
+  - swift
+  - runner-version
+  - label-change
+patterns:
+  - regex: 'Sending .* risks causing data races'
+    flags: i
+  - regex: 'does not conform to protocol .Sendable.'
+    flags: i
+  - regex: 'error: Expression is not assignable'
+    flags: i
+error_messages:
+  - "error: Sending 'self' risks causing data races"
+  - "error: Type 'X' does not conform to protocol 'Sendable'"
+  - "note: annotate with '@MainActor' if property should only be accessed from the main actor"
+root_cause: |
+  GitHub changed macos-latest to point to macOS 15 (Sequoia) with Xcode 16 in December 2024.
+  Xcode 16 enables Swift strict concurrency checking (Swift 6 language mode prerequisites) by
+  default. Workflows written and tested on macOS 14 (Sonoma) with Xcode 15 silently receive
+  macOS 15 with Xcode 16, which promotes Swift concurrency warnings to errors and enforces
+  Sendable conformance. Unlike a build failure with a clear version mismatch message, workflows
+  appear to run normally until the Swift compiler raises concurrency errors on previously clean code.
+  This mirrors the ubuntu-latest → ubuntu-24.04 silent label change (see silent-failures-059).
+fix: |
+  Option 1 — Pin to macos-14 until your codebase is Swift 6 ready:
+    runs-on: macos-14
+  
+  Option 2 — Disable strict concurrency checking temporarily:
+    Add SWIFT_STRICT_CONCURRENCY=minimal to xcodebuild arguments.
+  
+  Option 3 — Migrate to Swift 6 concurrency (recommended long term):
+    Annotate types with @MainActor, Sendable, or nonisolated as appropriate.
+    Use async/await and actors for shared mutable state.
+fix_code:
+  - language: yaml
+    label: "Pin to macos-14 until Swift 6 migration is complete"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-14  # Pinned — avoids Xcode 16 Swift 6 strictness
+          # Use macos-15 once concurrency issues are resolved
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build and test
+              run: xcodebuild test -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15'
+  - language: yaml
+    label: "Disable Swift strict concurrency temporarily with SWIFT_STRICT_CONCURRENCY=minimal"
+    code: |
+      - name: Build with relaxed concurrency checking
+        run: |
+          xcodebuild build \
+            -scheme MyApp \
+            SWIFT_STRICT_CONCURRENCY=minimal
+prevention:
+  - "Pin to a specific macOS version (macos-14, macos-15) instead of macos-latest for stability"
+  - "Follow GitHub Changelog for macos-latest label change announcements before they happen"
+  - "Run Xcode 16 locally with Swift strict concurrency enabled before CI failures surface"
+  - "Add a step printing runner OS version (sw_vers) to detect unexpected runner upgrades"
+docs:
+  - url: "https://github.blog/changelog/2024-12-02-github-actions-macos-15-is-now-generally-available/"
+    label: "GitHub Changelog: macOS 15 Generally Available (Dec 2024)"
+  - url: "https://developer.apple.com/documentation/swift/updating-an-app-to-use-strict-concurrency"
+    label: "Apple: Updating an App to Use Strict Concurrency"
+  - url: "https://github.com/actions/runner-images/blob/main/images/macos/macos-15-Readme.md"
+    label: "macOS 15 Runner Image — Installed Software"

package/errors/silent-failures/vars-context-environment-shadows-repo-org.yml

@@ -0,0 +1,97 @@
+id: silent-failures-088
+title: 'vars.* context: environment-scoped variable silently shadows repository and org variable'
+category: silent-failures
+severity: silent-failure
+tags:
+  - vars
+  - variables
+  - environment
+  - precedence
+  - shadow
+  - configuration
+patterns:
+  - regex: 'vars\.[A-Z_]+'
+    flags: 'i'
+error_messages: []
+root_cause: |
+  The vars.* context resolves configuration variables in strict precedence order:
+  environment-scoped > repository-level > organization-level. When a job specifies
+  an environment: key, any variable defined at that deployment environment's scope
+  with the same name as a repository or organization variable silently overrides
+  the higher-scope value.
+
+  No warning or error is emitted when shadowing occurs. The workflow runs
+  successfully but uses the environment-scoped value rather than the expected
+  org or repository value.
+
+  Common scenario: an organization defines vars.REGION='us-east-1' for all repos.
+  A production deployment environment defines vars.REGION='eu-west-1' to override
+  it for EU deploys. All jobs that reference the production environment now receive
+  'eu-west-1' — including notification jobs, post-deploy validation jobs, or any
+  other job that happens to run in the production environment but was not intended
+  to use the EU override.
+
+  Unlike secrets, where absence raises a validation error, variable shadowing is
+  entirely transparent to the workflow author. Debugging requires manually
+  inspecting variable scopes in GitHub Settings across three levels (org, repo,
+  environment) to find the effective value.
+fix: |
+  Use scope-specific prefixes for variables that intentionally override
+  parent-scope defaults (e.g., PROD_REGION instead of REGION). Audit effective
+  variable values at runtime by echoing vars.* at the start of critical jobs.
+
+  To inspect what is currently configured:
+  - GitHub > Organization Settings > Variables (org-level)
+  - Repo Settings > Secrets and variables > Variables (repo-level)
+  - Repo Settings > Environments > <name> > Variables (environment-level)
+fix_code:
+  - language: yaml
+    label: 'Debug effective vars.* resolution in a job with environment scope'
+    code: |
+      jobs:
+        deploy:
+          environment: production
+          runs-on: ubuntu-latest
+          steps:
+            - name: Audit effective variable values
+              run: |
+                echo "REGION (effective): ${{ vars.REGION }}"
+                # If this shows 'eu-west-1' when you expected 'us-east-1',
+                # the 'production' environment has a REGION variable that
+                # silently shadows the org or repository-level value.
+  - language: yaml
+    label: 'Use environment-scoped prefixes to make overrides explicit'
+    code: |
+      # Organization variable: REGION=us-east-1
+      # Environment 'production' variable: PROD_REGION=eu-west-1  (distinct name)
+
+      jobs:
+        deploy:
+          environment: production
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy to production
+              run: |
+                # Explicit — no ambiguity about which scope is used
+                deploy --region ${{ vars.PROD_REGION }}
+
+        notify:
+          environment: production
+          runs-on: ubuntu-latest
+          steps:
+            - name: Notify
+              run: |
+                # Without prefix, this would silently get 'eu-west-1' instead
+                # of 'us-east-1' if REGION is defined at environment scope
+                notify --datacenter ${{ vars.NOTIFICATION_REGION }}
+prevention:
+  - 'Prefix environment-scoped variable names to make overrides explicit — PROD_REGION not REGION'
+  - 'Audit all three variable scopes before deployments: org, repo, and environment'
+  - 'Add a comment in the workflow file documenting which variables each environment is expected to override'
+  - 'For critical deployment config, avoid relying on implicit variable inheritance — reference scope-prefixed names'
+  - 'Run a variable audit step at the start of critical jobs to log effective vars.* values'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#precedence-for-variable-values'
+    label: 'GitHub Docs — Variable precedence for the vars.* context'
+  - url: 'https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment'
+    label: 'GitHub Docs — Managing environments for deployment'

package/errors/yaml-syntax/timeout-minutes-env-context-unavailable.yml

@@ -0,0 +1,93 @@
+id: yaml-syntax-061
+title: 'env context unavailable in job-level timeout-minutes field'
+category: yaml-syntax
+severity: error
+tags:
+  - env
+  - timeout-minutes
+  - context
+  - context-availability
+  - job-level
+patterns:
+  - regex: 'Unrecognized named-value: .env.'
+    flags: 'i'
+  - regex: 'timeout-minutes.*\$\{\{.*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: env.MY_TIMEOUT"
+root_cause: |
+  The env context is not available in job-level timeout-minutes expressions.
+  GitHub Actions evaluates jobs.<job_id>.timeout-minutes before steps run and
+  before step-level env values are populated. The available contexts at this
+  position are: github, inputs, vars, needs, strategy, and matrix only.
+
+  Developers commonly try to make timeouts configurable by setting a workflow-level
+  env: block (e.g., env: { JOB_TIMEOUT: 60 }) and referencing it as
+  ${{ env.JOB_TIMEOUT }} in timeout-minutes, expecting it to work like env
+  references inside steps. This fails with a parse-time validation error because
+  the env context is not evaluated at job metadata positions.
+
+  Note: env IS available in step-level timeout-minutes
+  (jobs.<job_id>.steps[*].timeout-minutes) — this restriction only applies at
+  the job level. This asymmetry trips up developers who test in steps first
+  and then try to lift the same expression to job level.
+fix: |
+  Use the vars context (repository or environment variables) instead of env for
+  job-level timeout-minutes. Repository variables can be set under
+  Settings > Secrets and variables > Variables and are available at job-evaluation
+  time.
+
+  If the timeout value needs to vary per workflow run, pass it as a workflow
+  input (inputs.*) for workflow_dispatch or workflow_call, or use matrix values
+  to parameterize timeouts per leg.
+fix_code:
+  - language: yaml
+    label: 'Wrong — env context in job-level timeout-minutes (validation error)'
+    code: |
+      env:
+        JOB_TIMEOUT: 60
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: ${{ env.JOB_TIMEOUT }}  # ERROR: env not available here
+          steps:
+            - run: make build
+  - language: yaml
+    label: 'Correct — use vars context for a configurable job timeout'
+    code: |
+      # Set JOB_TIMEOUT_MINUTES in repository Settings > Variables (e.g., "60")
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: ${{ fromJSON(vars.JOB_TIMEOUT_MINUTES || '60') }}
+          steps:
+            - run: make build
+  - language: yaml
+    label: 'Correct — pass timeout as workflow_dispatch input'
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            timeout:
+              type: number
+              default: 60
+              description: 'Job timeout in minutes'
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: ${{ inputs.timeout }}
+          steps:
+            - run: make build
+prevention:
+  - 'Use vars.* (repository or environment variables) for static configurable timeouts at job level'
+  - 'Use inputs.* for runtime-configurable timeouts passed via workflow_dispatch or workflow_call'
+  - 'env context is only available at step level and below — not at the job metadata level'
+  - 'step-level timeout-minutes does support env context; only job-level timeout-minutes does not'
+  - 'Available contexts in job-level fields: github, inputs, vars, needs, strategy, matrix'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/contexts#context-availability'
+    label: 'GitHub Docs — Context availability per workflow position'
+  - url: 'https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes'
+    label: 'GitHub Docs — jobs.<job_id>.timeout-minutes'

package/package.json

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