@htekdev/actions-debugger 1.0.13 → 1.0.15

package/errors/permissions-auth/reusable-workflow-permissions-not-inherited.yml

@@ -0,0 +1,114 @@
+id: permissions-auth-012
+title: "Reusable Workflow Permissions Not Inherited from Caller — Must Be Granted Explicitly"
+category: permissions-auth
+severity: error
+tags:
+  - reusable-workflow
+  - permissions
+  - github-token
+  - caller
+  - contents
+patterns:
+  - regex: "is requesting '([^']+)', but is only allowed '([^']+)'"
+    flags: "i"
+  - regex: "The workflow.*is requesting.*but is only allowed"
+    flags: "i"
+  - regex: "Resource not accessible by integration"
+    flags: "i"
+error_messages:
+  - "The workflow is not valid. .github/workflows/caller.yml: Error calling workflow 'org/repo/.github/workflows/reusable.yml@main'. The workflow 'org/repo/.github/workflows/reusable.yml@main' is requesting 'contents: read', but is only allowed 'contents: none'."
+  - "Resource not accessible by integration"
+root_cause: |
+  When a workflow calls a reusable workflow using `jobs.<job>.uses`, the called workflow
+  runs with a GITHUB_TOKEN whose permissions are the INTERSECTION of:
+  1. The permissions declared in the caller workflow (or job)
+  2. The permissions the called reusable workflow needs
+
+  Reusable workflows do NOT automatically inherit the caller's permissions. If the caller
+  workflow declares a restrictive permissions block (or relies on repository-default
+  read-all), but the reusable workflow declares or needs broader permissions, the call
+  fails at validation time with:
+
+    "The workflow 'X' is requesting 'contents: read', but is only allowed 'contents: none'."
+
+  This also manifests at runtime as "Resource not accessible by integration" (HTTP 403)
+  when the reusable workflow's steps attempt API calls or git operations that require
+  permissions not granted by the caller.
+
+  Common scenarios:
+  - Caller explicitly sets `permissions: {}` (no permissions) for security hardening
+  - Caller sets only `id-token: write` for OIDC but reusable workflow needs `contents: read`
+  - Repository setting "Read and write permissions" is overridden to "Read repository
+    contents and packages permissions" at org level, reducing the default token scope
+  - Caller passes `secrets: inherit` but forgets to also pass `permissions:`
+
+  Source: GitHub Community Discussion #52665
+fix: |
+  Explicitly grant the required permission scopes in the **caller** workflow, at either
+  the workflow level or the specific job level that uses the reusable workflow.
+
+  To discover which permissions a reusable workflow needs, check its `on.workflow_call`
+  declaration or read its steps to see which GitHub API/resource operations it performs.
+
+  Follow least privilege: grant only what the reusable workflow actually needs, not
+  blanket read-all.
+fix_code:
+  - language: yaml
+    label: "Broken — caller grants no permissions, reusable workflow needs contents"
+    code: |
+      # ❌ BROKEN: caller sets permissions: {} — reusable workflow inherits none
+      name: Release
+      on: push
+
+      permissions: {}  # Locks down all permissions — nothing passes through
+
+      jobs:
+        release:
+          uses: my-org/shared-workflows/.github/workflows/release.yml@main
+          # Error: release.yml requests 'contents: write' but caller allows 'contents: none'
+  - language: yaml
+    label: "Fixed — grant required scopes explicitly at the job level"
+    code: |
+      # ✅ FIXED: grant only what the reusable workflow needs
+      name: Release
+      on: push
+
+      permissions: {}  # Lock down at workflow level for security
+
+      jobs:
+        release:
+          permissions:
+            contents: write       # Required by the reusable workflow for creating releases
+            id-token: write       # Required for OIDC if the reusable workflow uses it
+          uses: my-org/shared-workflows/.github/workflows/release.yml@main
+  - language: yaml
+    label: "Fixed — grant permissions at workflow level when multiple jobs use reusable workflows"
+    code: |
+      # ✅ FIXED: grant at workflow level when multiple jobs need the same scopes
+      name: CI
+      on: [push, pull_request]
+
+      permissions:
+        contents: read          # Needed for checkout in reusable workflows
+        packages: write         # Needed for reusable workflow that publishes packages
+        pull-requests: write    # Needed for reusable workflow that adds PR comments
+
+      jobs:
+        build:
+          uses: my-org/shared-workflows/.github/workflows/build.yml@main
+        publish:
+          needs: build
+          uses: my-org/shared-workflows/.github/workflows/publish.yml@main
+prevention:
+  - "Always read the reusable workflow's steps to know which permissions it needs before calling it."
+  - "Test reusable workflow calls from a caller with explicit `permissions: {}` first — failures reveal required scopes."
+  - "Document required permissions in the reusable workflow's `on.workflow_call` block as comments."
+  - "When adding `permissions:` to a caller, remember that declaring ANY permission sets all others to `none` — enumerate every scope you need."
+  - "Use job-level `permissions:` rather than workflow-level to apply least-privilege per job."
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/reusing-workflows"
+    label: "Reusing workflows — permissions and access"
+  - url: "https://github.com/orgs/community/discussions/52665"
+    label: "GitHub Community #52665 — reusable workflow permissions"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/controlling-permissions-for-github_token"
+    label: "Controlling permissions for GITHUB_TOKEN"

package/errors/runner-environment/az-powershell-14-to-15-breaking.yml

@@ -0,0 +1,108 @@
+id: runner-environment-034
+title: "Azure PowerShell Az Module Upgraded from 14.x to 15.x on All Runner Images"
+category: runner-environment
+severity: error
+tags:
+  - azure
+  - powershell
+  - az-module
+  - breaking-change
+  - runner-image
+  - migration
+patterns:
+  - regex: "Az\\.(?:Accounts|Compute|Storage|Network|Resources|KeyVault|Sql|Monitor).*not recognized|The term '.*-Az.*' is not recognized"
+    flags: "i"
+  - regex: "Install-Module.*Az.*RequiredVersion.*14"
+    flags: "i"
+  - regex: "Get-AzVM|Set-AzVMExtension|New-AzResourceGroup.*parameter.*was not found|does not exist in the cmdlet"
+    flags: "i"
+  - regex: "CommandNotFoundException.*Az\\.|ParameterBindingException.*Az\\."
+    flags: "i"
+error_messages:
+  - "The term 'Get-AzXxx' is not recognized as a name of a cmdlet"
+  - "A parameter cannot be found that matches parameter name"
+  - "Cannot process argument transformation on parameter"
+  - "Object reference not set to an instance of an object"
+root_cause: |
+  The Azure PowerShell (Az) module was upgraded from version 14.6.0 to 15.6.1 on all
+  GitHub-hosted runner images beginning June 8, 2026 (completing June 15, 2026).
+  This is a major version bump (14 → 15) and includes breaking changes:
+
+  - **Removed cmdlets**: Several deprecated cmdlets from Az 14.x were dropped with no
+    backward-compatible alias.
+  - **Parameter changes**: Some cmdlets have altered parameter names, types, or
+    removed optional parameters that were previously accepted.
+  - **Output type changes**: Return objects from certain cmdlets have changed shape,
+    breaking pipeline expressions like `(Get-AzXxx).Property`.
+  - **ARM64 images affected disproportionately**: windows-11-arm64 and
+    windows-11-vs2026-arm64 jumped from Az 12.5.0 directly to 15.6.1 — a 3-major-version
+    leap with significantly more accumulated breaking changes.
+
+  Unlike other software installed on runner images, the Az PowerShell module does NOT
+  have an LTS version — only the latest release receives security fixes and support.
+  Microsoft discontinued support for Az 14.x as of the 15.x release cycle.
+
+  The runner images affected and their before/after versions:
+  - ubuntu-22.04, ubuntu-24.04, macos-14/15/26, windows-2022/2025/2025-vs2026: 14.6.0 → 15.6.1
+  - windows-11-arm64, windows-11-vs2026-arm64: 12.5.0 → 15.6.1
+
+  Source: actions/runner-images#14104
+fix: |
+  **Option 1 — Pin to Az 14.6.0** (temporary fix while migrating):
+  Add an explicit Install-Module step at the start of any job using Az cmdlets.
+
+  **Option 2 — Migrate to Az 15.x** (recommended long-term):
+  Review the Az 15.x migration guide and update scripts to use the new cmdlet names,
+  parameters, and output types. Run `Get-AzVersion` to confirm the version in use.
+
+  **Diagnosis**: Use `Get-Module -Name Az.* -ListAvailable | Select Name, Version` to
+  confirm which Az module version is installed on the current runner.
+fix_code:
+  - language: yaml
+    label: "Pin Az module to 14.6.0 for immediate rollback"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Pin Azure PowerShell to 14.6.0
+              shell: pwsh
+              run: |
+                Install-Module -Name Az -RequiredVersion 14.6.0 -Force -AllowClobber -Scope CurrentUser
+                Import-Module Az -RequiredVersion 14.6.0
+
+            - name: Azure login
+              uses: azure/login@v2
+              with:
+                client-id: ${{ secrets.AZURE_CLIENT_ID }}
+                tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+                subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+
+            - name: Run Azure operations
+              shell: pwsh
+              run: |
+                # Your existing Az 14.x scripts
+                Get-AzVM -ResourceGroupName $env:RG_NAME
+  - language: yaml
+    label: "Verify installed Az version (diagnosis step)"
+    code: |
+      - name: Check Az module version
+        shell: pwsh
+        run: |
+          Get-Module -Name Az.Accounts -ListAvailable | Select-Object Name, Version
+          Get-AzVersion
+prevention:
+  - "Subscribe to actions/runner-images announcements to get advance warning of Az module version changes."
+  - "Pin the Az module version explicitly in all CI workflows using `Install-Module -RequiredVersion` rather than relying on the runner image default."
+  - "Test Az-based workflows against the new version by temporarily installing Az 15.x before the runner image rollout date."
+  - "Review the Az 15.x migration guide (https://learn.microsoft.com/en-us/powershell/azure/migrate-az-15.0.0) when upgrading."
+  - "Use `Get-AzVersion` at the start of troublesome workflows to emit the exact Az version to logs."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14104"
+    label: "runner-images#14104 — Az module update announcement (14.6.0 → 15.6.1)"
+  - url: "https://learn.microsoft.com/en-us/powershell/azure/migrate-az-15.0.0"
+    label: "Az 15.x migration guide"
+  - url: "https://learn.microsoft.com/en-us/powershell/azure/azureps-support-lifecycle"
+    label: "Az PowerShell support lifecycle"
+  - url: "https://learn.microsoft.com/en-us/powershell/azure/release-notes-azureps"
+    label: "Az PowerShell release notes"

package/errors/runner-environment/checkout-windows-ebusy-lock.yml

@@ -0,0 +1,124 @@
+id: runner-environment-042
+title: "actions/checkout EBUSY File Lock on Windows Self-Hosted Runners"
+category: runner-environment
+severity: error
+tags:
+  - windows
+  - self-hosted
+  - checkout
+  - ebusy
+  - file-lock
+  - git-fsmonitor
+patterns:
+  - regex: "EBUSY.*resource busy or locked"
+    flags: "i"
+  - regex: "File was unable to be removed.*EBUSY"
+    flags: "i"
+  - regex: "Unable to remove.*_temp.*EBUSY"
+    flags: "i"
+error_messages:
+  - "Error: File was unable to be removed Error: EBUSY: resource busy or locked, rmdir 'C:\\Users\\...\\runner\\_temp\\...'"
+  - "Error: EBUSY: resource busy or locked, rmdir"
+  - "Error: The process cannot access the file because it is being used by another process"
+root_cause: |
+  On Windows self-hosted runners, `actions/checkout` fails with an `EBUSY` (resource
+  busy or locked) error when attempting to clean up temp directories during checkout.
+
+  **Primary cause — Git FSMonitor:**
+  Git's `core.fsmonitor` daemon (enabled by default in Git 2.36+) keeps a file handle
+  open on the repository directory. When `actions/checkout` tries to remove or clean the
+  `_temp` directory between runs, the FSMonitor process holds the lock, causing EBUSY.
+
+  **Secondary causes:**
+  - Windows Defender / antivirus scanning files that checkout is trying to delete
+  - Other processes (IDE file watchers, npm watchers, running Node processes) holding
+    handles on workspace files
+  - Concurrent runner jobs accessing the same workspace directory
+
+  **Why Windows only:**
+  Linux/macOS do not enforce EBUSY locks in the same way. Windows file locking is
+  advisory on Unix but mandatory on NTFS, so the same handle that would succeed on
+  Linux causes a hard error on Windows.
+
+  Source: actions/checkout#1388
+fix: |
+  **Option 1 (recommended): Disable Git FSMonitor on the runner**
+
+  Configure Git globally on the self-hosted runner to disable fsmonitor:
+  ```
+  git config --global core.fsmonitor false
+  git config --global core.useBuiltinFSMonitor false
+  ```
+
+  **Option 2: Add a pre-checkout cleanup step**
+
+  Kill any lingering Git processes before checkout:
+  ```yaml
+  - name: Kill lingering git processes
+    shell: pwsh
+    run: Get-Process -Name "git" -ErrorAction SilentlyContinue | Stop-Process -Force
+  ```
+
+  **Option 3: Configure antivirus exclusions**
+
+  Add the runner workspace directory (e.g., `C:\actions-runner\_work\`) to Windows
+  Defender's exclusion list on the self-hosted runner machine.
+
+  **Option 4: Use `clean: false` and handle cleanup manually**
+
+  Setting `clean: false` on `actions/checkout` prevents the step from attempting to
+  clean the workspace, avoiding the lock conflict entirely.
+fix_code:
+  - language: yaml
+    label: "Workaround — disable git FSMonitor before checkout"
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, windows]
+          steps:
+            # Kill git fsmonitor daemon before checkout to release file locks
+            - name: Disable git fsmonitor
+              shell: pwsh
+              run: |
+                git config --global core.fsmonitor false
+                git config --global core.useBuiltinFSMonitor false
+                Get-Process -Name "git" -ErrorAction SilentlyContinue | Stop-Process -Force
+
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: "Workaround — skip workspace clean to avoid EBUSY on _temp"
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, windows]
+          steps:
+            - uses: actions/checkout@v4
+              with:
+                clean: false   # Skip workspace clean; avoids EBUSY on locked dirs
+  - language: yaml
+    label: "Workaround — retry checkout on EBUSY failure"
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, windows]
+          steps:
+            - name: Checkout with retry
+              uses: nick-fields/retry@v3
+              with:
+                timeout_minutes: 5
+                max_attempts: 3
+                command: git checkout
+            - uses: actions/checkout@v4
+prevention:
+  - "Disable Git FSMonitor globally on Windows self-hosted runners: `git config --global core.fsmonitor false`."
+  - "Add the runner `_work` directory to Windows Defender exclusions — AV scanning causes EBUSY on files checkout needs to delete."
+  - "Avoid running multiple workflow jobs concurrently on the same workspace directory on a single Windows self-hosted runner."
+  - "Upgrade to `actions/checkout@v4` — later versions have improved retry logic and are more resilient to transient locks."
+  - "Consider using ephemeral self-hosted runners that start fresh for each job, eliminating stale workspace lock issues entirely."
+docs:
+  - url: "https://github.com/actions/checkout/issues/1388"
+    label: "actions/checkout#1388 — EBUSY resource busy or locked on Windows self-hosted"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners"
+    label: "GitHub Docs: About self-hosted runners"
+  - url: "https://git-scm.com/docs/git-config#Documentation/git-config.txt-corefsmonitor"
+    label: "Git config: core.fsmonitor"

package/errors/runner-environment/deprecated-action-version-auto-rejected.yml

@@ -0,0 +1,89 @@
+id: runner-environment-037
+title: "Deprecated Action Version Automatically Rejected by Runner"
+category: runner-environment
+severity: error
+tags:
+  - deprecated
+  - action-version
+  - actions-cache
+  - breaking-change
+  - pinning
+  - migration
+patterns:
+  - regex: "This request has been automatically failed because it uses a deprecated version of"
+    flags: "i"
+  - regex: "uses a deprecated version of `actions/(cache|checkout|upload-artifact|download-artifact)"
+    flags: "i"
+  - regex: "Please update your workflow to use v[0-9]+ of `actions/"
+    flags: "i"
+error_messages:
+  - "Error: This request has been automatically failed because it uses a deprecated version of `actions/cache: v4.0.2`. Please update your workflow to use v3/v4 of actions/cache. Learn more: https://github.blog/changelog/..."
+  - "Error: This request has been automatically failed because it uses a deprecated version of `actions/upload-artifact: v1`."
+root_cause: |
+  GitHub periodically deprecates specific minor/patch version tags of official actions (e.g.,
+  actions/cache, actions/checkout, actions/upload-artifact). When a workflow pins a deprecated
+  specific version (e.g., @v4.0.2 instead of @v4), the Actions runner rejects the entire run
+  immediately with an "automatically failed" message — before executing any step logic.
+
+  This is distinct from a runtime failure: the runner halts before any user code runs, which
+  means logs contain only the rejection message and no build output.
+
+  Deprecation schedules and affected versions are announced via GitHub Changelog. Common
+  scenarios that trigger this:
+  - Pinning exact minor/patch SHA-like versions (v4.0.2) instead of major aliases (v4)
+  - Old workflow files that predate a deprecation cycle and have not been updated
+  - Third-party or internal actions that internally depend on deprecated toolkit versions
+  - Dependabot bumping a minor version that happens to be on the deprecated list
+
+  Affected actions as of 2024-2026 include actions/cache v1/v2, specific v4.0.x minor pins,
+  actions/upload-artifact v1/v2, and associated @actions/toolkit package versions used as
+  dependencies in published actions.
+fix: |
+  Update all action `uses:` references to a currently supported version tag.
+
+  For official GitHub actions, always prefer the major version alias (e.g., @v4, @v3) rather
+  than pinning a minor or patch version. This ensures your workflow automatically receives
+  non-breaking updates and avoids deprecation gates.
+
+  To track deprecation notices proactively:
+  - Watch or subscribe to https://github.blog/changelog/ for "breaking changes" announcements
+  - Enable Dependabot for GitHub Actions in your repository
+  - Check the action's GitHub releases page for deprecation notices in release notes
+fix_code:
+  - language: yaml
+    label: "Use major version alias instead of pinned minor version"
+    code: |
+      jobs:
+        build:
+          steps:
+            # ❌ Pinned minor version — may be auto-rejected after deprecation
+            - uses: actions/cache@v4.0.2
+
+            # ✅ Major alias — always points to latest supported minor in that major
+            - uses: actions/cache@v4
+
+            # ✅ Full SHA pin — immune to deprecation gates (security-conscious alternative)
+            - uses: actions/cache@5a3ec84eff668545956fd18022155c47c3f8e48
+  - language: yaml
+    label: "Enable Dependabot to keep action versions current"
+    code: |
+      # .github/dependabot.yml
+      version: 2
+      updates:
+        - package-ecosystem: "github-actions"
+          directory: "/"
+          schedule:
+            interval: "weekly"
+prevention:
+  - "Use major version aliases (@v4, @v3) instead of exact minor/patch versions for official GitHub actions."
+  - "Subscribe to github.blog/changelog and watch for 'Notice of upcoming releases and breaking changes for GitHub Actions' posts."
+  - "Enable Dependabot for the github-actions ecosystem in your repository to auto-bump pinned versions."
+  - "Periodically audit your workflows for pinned minor/patch versions: grep -r 'uses:' .github/workflows/ | grep -E '@v[0-9]+\\.[0-9]+'"
+  - "When using SHA pinning for security, use a tool like StepSecurity's Harden-Runner or pin-github-action to maintain fresh SHAs."
+docs:
+  - url: "https://github.blog/changelog/2024-12-05-notice-of-upcoming-releases-and-breaking-changes-for-github-actions/#actions-cache-v1-v2-and-actions-toolkit-cache-package-closing-down"
+    label: "GitHub Changelog — actions/cache v1/v2 deprecation notice"
+  - url: "https://github.com/orgs/community/discussions/151729"
+    label: "Community discussion #151729 — deprecated action version auto-failure"
+  - url: "https://github.com/actions/setup-python/issues/1037"
+    label: "actions/setup-python #1037 — reports of deprecated cache version failures"

package/errors/runner-environment/github-hosted-runner-disk-space-full.yml

@@ -0,0 +1,85 @@
+id: runner-environment-048
+title: "GitHub-hosted runner disk space exhausted (No space left on device)"
+category: runner-environment
+severity: error
+tags:
+  - disk-space
+  - ubuntu
+  - docker
+  - storage
+  - enospc
+patterns:
+  - regex: "No space left on device"
+    flags: "i"
+  - regex: "ENOSPC: no space left on device"
+    flags: "i"
+  - regex: "Disk usage: 100%"
+    flags: "i"
+  - regex: "write .*: no space left on device"
+    flags: "i"
+error_messages:
+  - "No space left on device"
+  - "Error: ENOSPC: no space left on device, write"
+  - "OSError: [Errno 28] No space left on device"
+root_cause: |
+  GitHub-hosted ubuntu-latest runners start with approximately 14-25 GB of free
+  disk space after the OS and pre-installed toolchains occupy the rest of the
+  ~80 GB disk. Workflows that build large Docker images, run multi-stage builds,
+  download large artifacts, or install additional software can exhaust this
+  budget mid-job.
+
+  Common culprits:
+  - Docker build layers accumulating in /var/lib/docker (no automatic pruning)
+  - Android SDK, .NET SDKs, Haskell GHC, and other large pre-installed tools
+    consuming 50+ GB of disk that most workflows never need
+  - Multiple matrix jobs each pulling large container images on the same runner
+    (each job gets a fresh runner, but a single job's steps share one disk)
+fix: |
+  Add a disk-space cleanup step at the start of your job before any build steps.
+  The jlumbroso/free-disk-space action removes pre-installed tools you don't
+  need, recovering 30-60 GB.
+
+  Alternatively, use docker system prune to clean up intermediate layers after
+  each build stage, or split large jobs across multiple workflows.
+fix_code:
+  - language: yaml
+    label: "Use free-disk-space action at job start"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Free disk space
+              uses: jlumbroso/free-disk-space@v1.3.1
+              with:
+                tool-cache: false
+                android: true
+                dotnet: true
+                haskell: true
+                large-packages: true
+                swap-storage: true
+            - uses: actions/checkout@v4
+            - name: Build Docker image
+              run: docker build -t myapp .
+  - language: yaml
+    label: "Prune Docker intermediate layers between build stages"
+    code: |
+      - name: Build builder stage
+        run: docker build --target builder -t myapp:builder .
+      - name: Prune intermediate layers
+        run: docker image prune -f
+      - name: Build final image
+        run: docker build -t myapp:final .
+prevention:
+  - "Add jlumbroso/free-disk-space as the first step in any disk-intensive job"
+  - "Use multi-stage Docker builds and prune builder images after the final stage"
+  - "Run df -h early in the job to baseline free space and catch issues before they crash"
+  - "Consider GitHub larger runners (30-100 GB disk) for builds that legitimately need space"
+  - "Cache Docker layers with type=gha to avoid re-downloading the same base images"
+docs:
+  - url: "https://github.com/jlumbroso/free-disk-space"
+    label: "jlumbroso/free-disk-space — reclaim disk on GitHub-hosted runners"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "GitHub Docs — Hosted runner hardware resources and disk space"
+  - url: "https://github.com/actions/runner-images/issues/2840"
+    label: "runner-images#2840 — Disk space workarounds discussion"

package/errors/runner-environment/github-path-same-step-not-found.yml

@@ -0,0 +1,114 @@
+id: runner-environment-040
+title: "GITHUB_PATH Updates Are Not Available in the Same Step That Writes Them"
+category: runner-environment
+severity: silent-failure
+tags:
+  - GITHUB_PATH
+  - GITHUB_ENV
+  - path
+  - environment-file
+  - command-not-found
+  - same-step
+patterns:
+  - regex: "command not found"
+    flags: "i"
+  - regex: "not recognized as.*cmdlet|not recognized as.*function"
+    flags: "i"
+  - regex: "GITHUB_PATH.*same step|same step.*GITHUB_PATH"
+    flags: "i"
+error_messages:
+  - "/bin/bash: line X: my-tool: command not found"
+  - "The term 'my-tool' is not recognized as the name of a cmdlet, function, script file, or executable program"
+root_cause: |
+  When you write a directory path to `$GITHUB_PATH` (or an environment variable to
+  `$GITHUB_ENV`), the change is **NOT available in the same `run:` step** that writes
+  the file. It only takes effect for **subsequent steps** in the same job.
+
+  The runner reads the environment files between steps — not mid-step. The typical
+  developer mistake is:
+
+  ```yaml
+  - name: Install and use tool
+    run: |
+      echo "$HOME/.local/bin" >> $GITHUB_PATH   # writes to GITHUB_PATH
+      my-tool --version                           # ❌ fails — PATH not updated yet
+  ```
+
+  The same applies to `$GITHUB_ENV` — variables written to the env file are not
+  accessible via `${{ env.VAR }}` or as shell variables in the same step.
+
+  Additionally, using `>` instead of `>>` to write to `$GITHUB_PATH` or `$GITHUB_ENV`
+  overwrites the entire file, wiping all previously set paths/variables and causing
+  unexpected "command not found" errors in later steps.
+
+  Sources: GitHub Community #80916, nektos/act issue #2637, GitHub Docs
+fix: |
+  Split the install/configure step from the step that uses the tool. Write to
+  `$GITHUB_PATH` or `$GITHUB_ENV` in one step, then use the tool/variable in a
+  subsequent step.
+
+  For the current step only, modify `$PATH` directly in the shell environment
+  (not via `$GITHUB_PATH`) if you need immediate access.
+
+  Always use `>>` (append) when writing to `$GITHUB_PATH` or `$GITHUB_ENV` — never
+  `>` (overwrite).
+fix_code:
+  - language: yaml
+    label: "Broken — tool used in same step as GITHUB_PATH write"
+    code: |
+      # ❌ BROKEN: my-tool not found because PATH not updated until next step
+      - name: Install and use tool
+        run: |
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+          my-tool --version   # fails: command not found
+  - language: yaml
+    label: "Fixed — split into two steps"
+    code: |
+      # ✅ FIXED: separate steps so runner reads GITHUB_PATH between them
+      - name: Add tool to PATH
+        run: echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+      - name: Use tool (PATH now includes ~/.local/bin)
+        run: my-tool --version
+  - language: yaml
+    label: "Fixed — same-step access via direct PATH export (no GITHUB_PATH)"
+    code: |
+      # ✅ ALTERNATIVE: Export PATH directly in the same step if splitting isn't possible
+      - name: Install and use tool in same step
+        run: |
+          export PATH="$HOME/.local/bin:$PATH"   # takes effect immediately in this step
+          my-tool --version
+          # Also persist for later steps:
+          echo "$HOME/.local/bin" >> $GITHUB_PATH
+  - language: yaml
+    label: "Fixed — GITHUB_ENV: split the set and the use"
+    code: |
+      # ❌ BROKEN: Variable not available yet in same step
+      - run: |
+          echo "MY_VAR=hello" >> $GITHUB_ENV
+          echo "$MY_VAR"   # empty — not yet loaded
+
+      # ✅ FIXED: Use in a later step
+      - run: echo "MY_VAR=hello" >> $GITHUB_ENV
+      - run: echo "$MY_VAR"    # prints 'hello'
+  - language: yaml
+    label: "Warning — always append (>>) never overwrite (>)"
+    code: |
+      # ❌ BROKEN: Overwrites GITHUB_PATH, removing all previously set paths
+      echo "/new/path" > $GITHUB_PATH
+
+      # ✅ FIXED: Append to preserve existing entries
+      echo "/new/path" >> $GITHUB_PATH
+prevention:
+  - "Never use the result of `$GITHUB_PATH` or `$GITHUB_ENV` writes in the same `run:` step — they take effect in the next step."
+  - "Always use `>>` (append) not `>` (overwrite) when writing to `$GITHUB_PATH` or `$GITHUB_ENV`."
+  - "If you need a tool available in the same step, export `PATH` directly in the shell command: `export PATH=\"/dir:$PATH\"` before calling the tool."
+  - "On Windows (PowerShell), use `Add-Content` or `Out-File -Append` — do not use `Set-Content` which overwrites the file."
+  - "Check the GitHub Actions docs section on 'environment files' to understand the step boundary at which env files are read."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#adding-a-system-path"
+    label: "GitHub Docs: Workflow commands — Adding a system path (GITHUB_PATH)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-an-environment-variable"
+    label: "GitHub Docs: Workflow commands — Setting an environment variable (GITHUB_ENV)"
+  - url: "https://github.com/orgs/community/discussions/80916"
+    label: "GitHub Community #80916 — GITHUB_PATH not available same step"