@htekdev/actions-debugger 1.0.124 → 1.0.125

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

@@ -0,0 +1,117 @@
+id: runner-environment-228
+title: 'setup-node@v6 cache detection fails when .yarnrc.yml contains approvedGitRepositories (yarn 4.14+)'
+category: runner-environment
+severity: error
+tags:
+  - setup-node
+  - yarn
+  - cache
+  - yarnrc
+  - approvedGitRepositories
+  - yarn-4
+  - cache-detection
+patterns:
+  - regex: 'Unrecognized or legacy configuration settings found: approvedGitRepositories'
+    flags: 'i'
+  - regex: "The 'yarn config get cacheFolder' command failed with exit code"
+    flags: 'i'
+  - regex: 'yarn config get cacheFolder.*exit code: 1'
+    flags: 'i'
+error_messages:
+  - "Usage Error: Unrecognized or legacy configuration settings found: approvedGitRepositories - run \"yarn config -v\" to see the list of settings supported in Yarn"
+  - "Error: The 'yarn config get cacheFolder' command failed with exit code: 1"
+root_cause: |
+  Yarn 4.14 introduced the `approvedGitRepositories` security setting in `.yarnrc.yml`.
+  This key enforces an allowlist of Git repository URLs that yarn is permitted to fetch
+  packages from, blocking unapproved source URLs with:
+
+    "Request to '<url>' has been blocked because it doesn't match any of the
+    patterns in 'approvedGitRepositories'"
+
+  However, any `.yarnrc.yml` key that is unrecognized or deprecated by the currently
+  installed version of yarn causes yarn to abort ALL config commands with:
+
+    "Usage Error: Unrecognized or legacy configuration settings found: approvedGitRepositories"
+
+  The `actions/setup-node@v6` action detects the yarn cache folder path by executing
+  `yarn config get cacheFolder` early in the action — before any Node.js version is
+  installed and before yarn itself is updated. If the runner's bundled yarn version is
+  older than 4.14, it does not recognize `approvedGitRepositories` and aborts.
+
+  The action catches the non-zero exit code and surfaces the error:
+    "Error: The 'yarn config get cacheFolder' command failed with exit code: 1"
+
+  This failure prevents setup-node from resolving the yarn cache path, breaking the
+  entire step. Users frequently observe this when:
+  - Upgrading to yarn 4.14+ and adding `approvedGitRepositories` to `.yarnrc.yml`
+  - Running on hosted runners where the system yarn version is older than 4.14
+  - Running on self-hosted runners with a frozen yarn version
+
+  The root issue is that yarn's unrecognized-key validation is global — it aborts even
+  read-only config queries when any single key is unrecognized, even if that key is not
+  related to the query.
+fix: |
+  Option 1 — Remove cache:yarn from setup-node (safest immediate fix).
+  Set cache: '' or omit the cache: input entirely. Manage yarn caching with a separate
+  actions/cache step pointed directly at the yarn cache directory.
+
+  Option 2 — Pin the yarn version in the runner environment to match .yarnrc.yml.
+  Ensure the yarn version on the runner is >= 4.14.0 so it recognizes
+  approvedGitRepositories before setup-node calls yarn config get.
+
+  Option 3 — Upgrade setup-node to a version that handles this gracefully.
+  Track actions/setup-node#1534 for a fix that makes cache folder detection resilient
+  to yarn config validation errors.
+
+  Option 4 — Use a separate cache step instead of setup-node's built-in cache.
+  This avoids the setup-node yarn version probe entirely.
+fix_code:
+  - language: yaml
+    label: 'Remove cache:yarn from setup-node and use a standalone cache step'
+    code: |
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          # Do NOT set cache: yarn — it triggers yarn config get cacheFolder
+          # which fails when approvedGitRepositories is in .yarnrc.yml
+
+      # Manage yarn cache manually
+      - name: Get yarn cache directory
+        id: yarn-cache-dir
+        run: echo "dir=$(yarn config get cacheFolder)" >> $GITHUB_OUTPUT
+
+      - uses: actions/cache@v4
+        with:
+          path: ${{ steps.yarn-cache-dir.outputs.dir }}
+          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
+
+      - run: yarn install --immutable
+
+  - language: yaml
+    label: 'Pin yarn version to 4.14+ before setup-node runs'
+    code: |
+      - name: Enable corepack with matching yarn version
+        run: |
+          corepack enable
+          corepack prepare yarn@4.14.1 --activate
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: yarn   # Now safe — yarn 4.14+ recognizes approvedGitRepositories
+prevention:
+  - 'After adding any new key to .yarnrc.yml, verify it is recognized by running yarn config -v locally and confirming the key appears in the supported list.'
+  - 'When using setup-node cache:yarn with yarn 4+, pin the yarn version via packageManager in package.json or via corepack before the setup-node step.'
+  - 'Monitor actions/setup-node release notes for fixes to yarn cache detection resilience (issue #1534).'
+  - 'If .yarnrc.yml uses security features added in a recent yarn release, document the minimum required yarn version in your repo README and CI setup guide.'
+docs:
+  - url: 'https://github.com/actions/setup-node/issues/1534'
+    label: 'actions/setup-node#1534 — Problem with yarn v4.14 config approvedGitRepositories'
+  - url: 'https://github.com/yarnpkg/berry/issues/7108'
+    label: 'yarnpkg/berry#7108 — approvedGitRepositories config key tracking issue'
+  - url: 'https://yarnpkg.com/configuration/yarnrc#approvedGitRepositories'
+    label: 'Yarn docs — approvedGitRepositories configuration'
+  - url: 'https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md#caching-packages-data'
+    label: 'setup-node — Advanced usage: caching packages data'

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

@@ -0,0 +1,119 @@
+id: runner-environment-229
+title: 'runner-container-hooks v0.8.0+ breaks local composite actions and event.json in Kubernetes job containers'
+category: runner-environment
+severity: error
+tags:
+  - runner-container-hooks
+  - kubernetes
+  - ARC
+  - local-actions
+  - composite-action
+  - job-container
+  - GITHUB_EVENT_PATH
+patterns:
+  - regex: "Can't find 'action\\.yml', 'action\\.yaml' or 'Dockerfile' under '.+\\.github/actions/.+'"
+    flags: 'i'
+  - regex: 'GITHUB_EVENT_PATH .+/github/workflow/event\\.json does not exist'
+    flags: 'i'
+  - regex: 'Did you forget to run actions/checkout before running your local action'
+    flags: 'i'
+error_messages:
+  - "Error: Can't find 'action.yml', 'action.yaml' or 'Dockerfile' under '/home/runner/_work/<repo>/<repo>/.github/actions/<action-name>'. Did you forget to run actions/checkout before running your local action?"
+  - "GITHUB_EVENT_PATH /github/workflow/event.json does not exist"
+root_cause: |
+  In `runner-container-hooks` v0.8.0 (released with actions-runner v2.334.0),
+  PR #244 replaced the shared PersistentVolumeClaim (PVC) between the runner
+  pod and job pods with exec-based file copying.
+
+  Two distinct regressions were introduced:
+
+  **1. Local composite actions fail ("Can't find action.yml")**
+  In `runScriptStep`, only the `_temp` directory is synced back from the job
+  pod to the runner host after each step. When `actions/checkout` runs inside
+  the job pod, the entire repository (including `.github/actions/`) is written
+  to `/__w/<owner>/<repo>/` inside the pod — but it is never copied back to
+  the runner host filesystem.
+
+  The runner resolves local actions by reading `action.yml` from its own
+  filesystem before dispatching the hook for that step. Since the workspace
+  was never synced back, the runner cannot find the action definition and
+  fails with the "Did you forget to run actions/checkout?" error — even
+  though checkout ran successfully inside the pod.
+
+  `runContainerStep` is not affected: it copies the full `/__w` back from
+  the job pod because container action steps run in a separate pod.
+
+  **2. GITHUB_EVENT_PATH missing for jobs without custom volume mounts**
+  In v0.7.0, `/github/home` and `/github/workflow` were set up as volume
+  subPath mounts on every job container. PR #244 replaced these mounts with
+  a `prepareJobScript` call that copies these directories into place — but
+  only when `args.container.userMountVolumes` is non-empty. If the workflow
+  has no custom `volumes:` in the `container:` block, the script never runs
+  and `/github/workflow/event.json` is never created.
+
+  Any action that reads `GITHUB_EVENT_PATH` (e.g. `dorny/paths-filter`,
+  `tj-actions/changed-files`, `actions/github-script` reading the event
+  payload) then fails because the file does not exist.
+
+  Both regressions affect Kubernetes-based ARC (Actions Runner Controller)
+  setups using runner-container-hooks v0.8.0+. Standard GitHub-hosted runners
+  and self-hosted runners that do NOT use container-hooks are unaffected.
+fix: |
+  **Immediate workaround:**
+  Pin `runner-container-hooks` to v0.7.0 by setting the container hooks
+  image in your ARC `HorizontalRunnerAutoscaler` or `RunnerDeployment`
+  configuration to use the v0.7.0 bundle (included in
+  `ghcr.io/actions/actions-runner:2.333.0`).
+
+  **For the local action failure specifically:**
+  After a fix is available upstream, the recommended approach is to upgrade
+  to a patched version of `runner-container-hooks` that copies `.github/`
+  back from the job pod after each `runScriptStep`.
+
+  **For the GITHUB_EVENT_PATH issue specifically:**
+  Ensure your `container:` block includes at least one `volumes:` entry to
+  trigger `prepareJobScript`, or wait for the upstream fix that unconditionally
+  runs the prepare script.
+
+  Track the upstream fix in actions/runner-container-hooks#337.
+fix_code:
+  - language: yaml
+    label: 'Pin ARC runner to actions-runner v2.333.0 (uses hooks v0.7.0) to avoid regression'
+    code: |
+      # In your HorizontalRunnerAutoscaler spec, pin the runner image
+      # to the last version that uses runner-container-hooks v0.7.0:
+      spec:
+        template:
+          spec:
+            image: ghcr.io/actions/actions-runner:2.333.0
+  - language: yaml
+    label: 'Workaround for GITHUB_EVENT_PATH: add a dummy volume mount to trigger prepareJobScript'
+    code: |
+      jobs:
+        build:
+          runs-on: self-hosted
+          container:
+            image: my-ci-image:latest
+            # Adding any volume entry triggers prepareJobScript and restores
+            # /github/workflow/event.json inside the job container
+            volumes:
+              - /tmp:/tmp
+          steps:
+            - uses: actions/checkout@v4
+            - uses: dorny/paths-filter@v3
+              with:
+                filters: |
+                  src:
+                    - 'src/**'
+prevention:
+  - 'When upgrading ARC runner images, check the bundled runner-container-hooks version and validate that local composite actions still work after the upgrade.'
+  - 'Pin runner images to a specific version tag rather than `latest` so unexpected upgrades do not break your workflows.'
+  - 'After upgrading runner-container-hooks, run a canary workflow that (a) uses a local composite action and (b) uses an action that reads GITHUB_EVENT_PATH to catch both regressions early.'
+  - 'Monitor the actions/runner-container-hooks releases page and the linked issue #337 for the official fix.'
+docs:
+  - url: 'https://github.com/actions/runner-container-hooks/issues/337'
+    label: 'actions/runner-container-hooks#337 — Local actions fail after PR #244 removed shared volume'
+  - url: 'https://github.com/actions/runner-container-hooks/pull/244'
+    label: 'actions/runner-container-hooks#244 — Remove dependency on the runner''s volume (introduced regression)'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners-with-actions-runner-controller/about-actions-runner-controller'
+    label: 'GitHub Docs — About Actions Runner Controller'

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

@@ -0,0 +1,129 @@
+id: runner-environment-230
+title: 'setup-python installs free-threaded Python (3.13t / 3.14t) as broken 0-byte symlink on windows-11-arm64'
+category: runner-environment
+severity: error
+tags:
+  - setup-python
+  - free-threaded
+  - python-3.13t
+  - python-3.14t
+  - windows-11-arm64
+  - symlink
+  - arm64
+  - GIL
+patterns:
+  - regex: 'Remove-Item.+arm64-freethreaded.+python\.exe.+because it does not exist'
+    flags: 'i'
+  - regex: 'Fatal Python error: Failed to import encodings module'
+    flags: 'i'
+  - regex: 'ModuleNotFoundError: No module named .encodings.'
+    flags: 'i'
+  - regex: 'Error happened during pip installation / upgrade'
+    flags: 'i'
+error_messages:
+  - "[error] Remove-Item : Cannot find path 'C:\\hostedtoolcache\\windows\\Python\\3.13.3-freethreaded\\arm64-freethreaded\\python.exe' because it does not exist."
+  - '[error] Fatal Python error: Failed to import encodings module'
+  - '[error] ModuleNotFoundError: No module named ''encodings'''
+  - '[error] Error happened during pip installation / upgrade'
+root_cause: |
+  The `win32-arm64-freethreaded` distribution zip for Python 3.13t and 3.14t
+  contains `python.exe` and `python3.exe` as **symlinks** (Windows reparse
+  points) that point to the version-specific binary (e.g. `python3.13t.exe`).
+
+  When `actions/setup-python` extracts the zip to the tool cache, the symlink
+  target does not exist at the expected relative path inside the extracted
+  directory. This leaves `python.exe` and `python3.exe` as **dangling 0-byte
+  reparse points** rather than working executables.
+
+  The setup script (`setup.ps1`, line 131) then attempts to remove `python.exe`
+  before placing the shim — but because the file is a dangling reparse point,
+  PowerShell cannot find it and throws:
+
+    `Remove-Item : Cannot find path '...\arm64-freethreaded\python.exe'
+     because it does not exist.`
+
+  Even if this error is swallowed, any subsequent attempt to invoke the
+  interpreter fails because the `python.exe` reparse point has no valid target.
+  The interpreter cannot locate its standard library, resulting in:
+
+    `Fatal Python error: Failed to import encodings module`
+
+  Non-free-threaded arm64 builds (`3.11`, `3.12`, `3.13`) are NOT affected
+  because their zips contain real executable files rather than symlinks.
+  x64 free-threaded builds are also unaffected.
+
+  This bug is present in `actions/setup-python` v5.x and v6.x when
+  `windows-11-arm64` runners are used. It was reported in April 2026 and
+  assigned for fix; check actions/setup-python#1307 for the patched release.
+fix: |
+  **Workaround 1 (recommended until patched):** Use a non-arm64 runner for
+  free-threaded Python testing. The x64 free-threaded wheels work correctly on
+  `windows-latest` or `windows-2025`:
+
+    ```yaml
+    runs-on: windows-latest  # x64 runner
+    ```
+
+  **Workaround 2:** Install free-threaded Python from NuGet on arm64 runners
+  rather than using `actions/setup-python`:
+
+    ```powershell
+    nuget install Microsoft.Python.Python.3.13-freethreaded.Arm64 -Version 3.13.3 -OutputDirectory .python
+    ```
+
+  **Workaround 3:** If you need arm64 + free-threaded specifically, test on
+  a Linux arm64 runner (`ubuntu-24.04-arm`) where the free-threaded build
+  does not have the symlink issue.
+
+  **Long-term:** Upgrade to the patched `actions/setup-python` version once
+  released (track actions/setup-python#1307).
+fix_code:
+  - language: yaml
+    label: 'Run free-threaded Python tests on x64 instead of arm64 until fix ships'
+    code: |
+      jobs:
+        test-freethreaded:
+          # Use x64 runner — free-threaded Python on windows-11-arm64 is broken
+          # (setup-python#1307). Switch back when the fix ships.
+          runs-on: windows-latest
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v6
+              with:
+                python-version: '3.13t'  # free-threaded; works on x64
+            - run: python --version
+            - run: python -c "import sys; print(sys._is_gil_enabled())"
+  - language: yaml
+    label: 'Use a matrix to run standard Python on arm64 and free-threaded on x64'
+    code: |
+      jobs:
+        test:
+          strategy:
+            matrix:
+              include:
+                # Standard arm64 — works fine
+                - os: windows-11-arm64
+                  python-version: '3.13'
+                # Free-threaded — x64 only until setup-python#1307 is fixed
+                - os: windows-latest
+                  python-version: '3.13t'
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v6
+              with:
+                python-version: ${{ matrix.python-version }}
+prevention:
+  - 'When adding free-threaded Python (3.13t, 3.14t) to a matrix, verify the runner OS — windows-11-arm64 has a broken symlink issue; use windows-latest (x64) instead.'
+  - 'Pin actions/setup-python to a known-good version and monitor actions/setup-python#1307 for the fix release before upgrading on arm64 free-threaded jobs.'
+  - 'After setting up free-threaded Python, add a smoke-test step (`python -c "import sys; print(sys.version)"`) early in the job to catch a broken interpreter before the full test suite runs.'
+  - 'Check that python.exe in the tool cache is a real executable, not a 0-byte reparse point, by running `(Get-Item python.exe).Length -gt 0` in a PowerShell step on windows-arm64.'
+docs:
+  - url: 'https://github.com/actions/setup-python/issues/1307'
+    label: 'actions/setup-python#1307 — setup-python fails for free-threaded Python (3.13t / 3.14t) on windows-11-arm64'
+  - url: 'https://github.com/onnx/onnx/actions/runs/24930991133'
+    label: 'Example failing CI run (onnx/onnx)'
+  - url: 'https://docs.python.org/3/whatsnew/3.13.html#free-threaded-cpython'
+    label: 'Python 3.13 — Free-threaded CPython (experimental no-GIL build)'
+  - url: 'https://github.com/actions/setup-python'
+    label: 'actions/setup-python — GitHub repository'

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

@@ -0,0 +1,90 @@
+id: runner-environment-231
+title: 'setup-java hangs indefinitely at "Trying to resolve the latest version from remote"'
+category: runner-environment
+severity: error
+tags:
+  - setup-java
+  - version-resolution
+  - hang
+  - network
+  - JDK
+  - distribution
+  - timeout
+  - temurin
+patterns:
+  - regex: 'Trying to resolve the latest version from remote'
+    flags: 'i'
+  - regex: 'setup-java.+Trying to resolve.+version'
+    flags: 'i'
+error_messages:
+  - 'Trying to resolve the latest version from remote'
+root_cause: |
+  When `java-version` is specified without a full patch version (e.g., `'21'`
+  or `'17'`), `actions/setup-java` must contact the JDK distribution's upstream
+  release manifest API to resolve the latest matching release. Before the fix
+  added in later versions of the action, this HTTP request was issued without a
+  timeout. When the upstream distribution endpoint (Eclipse Temurin, Amazon
+  Corretto, Microsoft JDK, etc.) was slow or unreachable — even transiently —
+  the resolution step could stall indefinitely, wedging the job until the
+  workflow-level `timeout-minutes` expired.
+
+  This affected all distributions that require a remote lookup for the latest
+  version, and was particularly impactful in environments with restricted or
+  intermittently degraded outbound network connectivity. The action would print
+  "Trying to resolve the latest version from remote" and then produce no further
+  output until the job hit its overall timeout.
+
+  The root cause was reported with 24+ community reactions in
+  actions/setup-java#897. The action was subsequently updated with improved
+  retry logic and enhanced error messages that surface the endpoint being
+  queried, making failures diagnosable.
+fix: |
+  **Immediate workaround (always recommended):** Pin an explicit full or
+  three-part version to bypass the remote manifest lookup entirely:
+
+  ```yaml
+  - uses: actions/setup-java@v4
+    with:
+      java-version: '21.0.3'  # Explicit patch version — no remote resolution needed
+      distribution: 'temurin'
+  ```
+
+  **Alternative:** Upgrade `actions/setup-java` to the version that includes
+  retry/timeout improvements (v4.2.2 or later). The updated action adds
+  timeouts and surfaces the endpoint URL in error output so stalls are
+  diagnosable rather than silent hangs.
+
+  **For self-hosted runners with restricted outbound access:** Explicitly add
+  the JDK distribution manifest endpoints to your allowlist, or pin exact
+  versions to eliminate remote lookups entirely.
+fix_code:
+  - language: yaml
+    label: 'Pin explicit patch version to avoid remote resolution'
+    code: |
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          # Explicit 3-part version — skips "Trying to resolve the latest
+          # version from remote" entirely
+          java-version: '21.0.3'
+          distribution: 'temurin'
+  - language: yaml
+    label: 'Use version file to avoid hardcoding version while skipping remote lookup'
+    code: |
+      # Define your JDK version in .java-version or .tool-versions
+      # When java-version-file is present, no remote lookup is needed:
+      - name: Set up JDK
+        uses: actions/setup-java@v4
+        with:
+          java-version-file: '.java-version'
+          distribution: 'temurin'
+prevention:
+  - 'Always pin an explicit JDK patch version (e.g., 21.0.3) or use a version file to eliminate remote manifest lookups and prevent hang-on-stall failures.'
+  - 'Set `timeout-minutes` on individual steps or jobs so a stalled remote lookup kills the step quickly rather than consuming the full runner allocation.'
+  - 'Monitor outbound network connectivity from self-hosted runners to JDK distribution APIs (e.g., api.adoptium.net for Temurin) and add these endpoints to firewall/proxy allowlists.'
+  - 'Use `actions/setup-java@v4.2.2` or later which includes retry logic and improved error messages for remote resolution failures.'
+docs:
+  - url: 'https://github.com/actions/setup-java/issues/897'
+    label: 'actions/setup-java#897 — Trying to resolve the latest version from remote (indefinite hang)'
+  - url: 'https://github.com/actions/setup-java#supported-version-syntax'
+    label: 'actions/setup-java — Supported version syntax (pin exact versions to avoid remote lookup)'

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

@@ -0,0 +1,131 @@
+id: runner-environment-232
+title: 'Self-hosted runner started as a service (svc.sh/svc.cmd) does not load user PATH from shell profile'
+category: runner-environment
+severity: error
+tags:
+  - self-hosted
+  - PATH
+  - svc.sh
+  - service
+  - environment-variables
+  - bash
+  - profile
+  - command-not-found
+patterns:
+  - regex: '(?:command not found|No such file or directory).+(?:\/home\/.+\/|~\/.+\/|GOPATH|cargo\/bin|\.local\/bin)'
+    flags: 'i'
+  - regex: '(?:bash|sh):.+: (?:command not found|No such file or directory)'
+    flags: 'i'
+error_messages:
+  - '/bin/bash: my-tool: command not found'
+  - 'bash: /home/runner/.local/bin/my-tool: No such file or directory'
+  - 'Error: Unable to locate executable file: my-tool. Please verify either the file path exists or the file can be found within a directory specified by the PATH environment variable.'
+root_cause: |
+  When the self-hosted runner is registered and started as a system service
+  using `svc.sh install && svc.sh start` (Linux/macOS) or
+  `svc.cmd install` (Windows), the service is launched by the OS service
+  manager (systemd, launchd, or Windows SCM) rather than interactively by
+  the user. As a result:
+
+  1. **Shell profile files are NOT sourced.** The service process never runs
+     `~/.bashrc`, `~/.bash_profile`, `~/.profile`, or `~/.zshrc`, so any
+     `export PATH=...` statements in those files have no effect on the runner
+     process or any job steps it spawns.
+
+  2. **Step shells use `--noprofile --norc` by default.** Even when job steps
+     invoke `bash`, the runner uses `bash --noprofile --norc -e -o pipefail`
+     (or equivalent), which explicitly disables sourcing of profile files.
+     This means binaries installed in user-specific directories — such as
+     `~/.local/bin`, `~/.cargo/bin`, `~/go/bin`, `~/.nvm/versions/node/*/bin`,
+     or any path added via `nvm`, `rbenv`, `pyenv`, `asdf`, etc. — are missing
+     from `PATH` in job steps even if they work fine in an interactive terminal.
+
+  3. **The runner's `.env` file is the authoritative PATH source.** The runner
+     process reads environment variables from a `.env` file at startup
+     (typically at `<runner-install-dir>/.env`). This file is NOT automatically
+     populated when the service is installed.
+
+  This is a common trap when developers install tools as their user (e.g.,
+  `cargo install`, `npm install -g`, `go install`, `pip install --user`) and
+  then register a self-hosted runner. Everything works in an interactive
+  terminal but fails when the service-started runner tries to execute the same
+  commands.
+fix: |
+  **Option 1 (recommended): Add paths to the runner's `.env` file**
+  Edit `<runner-install-dir>/.env` and append the needed PATH entries. The
+  runner reads this file at startup and merges it into the environment for all
+  job steps:
+
+  ```bash
+  # Append to <runner-install-dir>/.env
+  PATH=/home/runner/.cargo/bin:/home/runner/.local/bin:/home/runner/go/bin:$PATH
+  ```
+
+  Restart the service after editing: `sudo svc.sh stop && sudo svc.sh start`
+
+  **Option 2: Use `$GITHUB_PATH` in the workflow**
+  Add a step early in the job to append the needed paths using the
+  `$GITHUB_PATH` mechanism — this persists for all subsequent steps in the job:
+
+  ```yaml
+  - name: Add user bins to PATH
+    run: echo "$HOME/.local/bin" >> $GITHUB_PATH
+  ```
+
+  **Option 3: Start the runner interactively (development/testing only)**
+  Use `./run.sh` instead of the service to start the runner in an interactive
+  session that sources your shell profile. This is useful for debugging but
+  not suitable for production.
+
+  **Option 4: Change step shell to a login shell**
+  Override the shell at the step level to source the user profile:
+
+  ```yaml
+  - name: Run with login shell
+    shell: 'bash --login -e {0}'
+    run: my-tool --version
+  ```
+fix_code:
+  - language: yaml
+    label: 'Append user bin paths to runner PATH via .env file (persistent, affects all jobs)'
+    code: |
+      # Run this once on the self-hosted runner host:
+      # echo "PATH=/home/runner/.cargo/bin:/home/runner/.local/bin:$PATH" >> /home/runner/actions-runner/.env
+      # Then restart the runner service: sudo ./svc.sh stop && sudo ./svc.sh start
+      #
+      # In your workflow, the tool will now be found without any PATH workaround:
+      - name: Use cargo-installed tool
+        run: my-tool --version
+  - language: yaml
+    label: 'Append missing path per-job using $GITHUB_PATH'
+    code: |
+      jobs:
+        build:
+          runs-on: [self-hosted, linux]
+          steps:
+            - name: Add cargo bin to PATH
+              run: echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+
+            - name: Use cargo-installed tool
+              run: my-tool --version  # Now visible because GITHUB_PATH was updated
+  - language: yaml
+    label: 'Use login shell on a single step to source ~/.profile'
+    code: |
+      - name: Run with login shell (sources ~/.profile and ~/.bash_profile)
+        shell: 'bash --login -e {0}'
+        run: |
+          my-tool --version
+prevention:
+  - 'After registering a self-hosted runner, verify PATH by running a debug step: `run: echo $PATH && which my-tool` to confirm expected binaries are visible.'
+  - 'Document all non-standard tool paths in your `.env` file at runner registration time, before registering as a service, so PATH is correct from the first job.'
+  - 'Prefer system-wide tool installations (e.g., `/usr/local/bin/`) over user-specific paths for tools used on self-hosted runners, so the service environment sees them without profile sourcing.'
+  - 'When using version managers like nvm, rbenv, pyenv, or asdf, their shims are typically installed into shell-profile-sourced directories and will NOT work in service-started runners without explicit PATH entries in `.env`.'
+docs:
+  - url: 'https://github.com/actions/runner/issues/2903'
+    label: 'actions/runner#2903 — Runner service does not update PATH when started via svc.sh'
+  - url: 'https://github.com/actions/runner/issues/2528'
+    label: 'actions/runner#2528 — PATH changes at runtime not applied to runner steps (--noprofile --norc)'
+  - url: 'https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#adding-the-runner-to-your-enterprise'
+    label: 'GitHub Docs — Self-hosted runner environment configuration'
+  - 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 — Adding a system path (GITHUB_PATH)'