From c7b10b7ef84ad968442319ef6f47a190eca19f44 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 26 Mar 2026 21:56:35 +0000
Subject: [PATCH 1/2] Initial plan


From 26a838b5dbcfb9457184d9e779696c9c57e829c0 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 26 Mar 2026 22:01:26 +0000
Subject: [PATCH 2/2] fix: add debug logging for GITHUB_PATH path merge

---
 docs/environment.md   | 26 ++++++++++++++++++++++++++
 src/docker-manager.ts |  2 ++
 2 files changed, 28 insertions(+)

diff --git a/docs/environment.md b/docs/environment.md
index cde09380..aa9ccf90 100644
--- a/docs/environment.md
+++ b/docs/environment.md
@@ -106,6 +106,32 @@ The following environment variables are set internally by the firewall and used
 
 **Note:** These are set automatically based on CLI options and should not be overridden manually.
 
+## GitHub Actions `setup-*` Tool Availability
+
+Tools installed by GitHub Actions `setup-*` actions (e.g., `astral-sh/setup-uv`, `actions/setup-node`, `ruby/setup-ruby`, `actions/setup-python`) are **automatically available inside the AWF chroot**. This works by:
+
+1. `setup-*` actions write their tool bin directories to the `$GITHUB_PATH` file.
+2. AWF reads this file at startup and merges its entries (prepended, higher priority) into `AWF_HOST_PATH`.
+3. The chroot entrypoint exports `AWF_HOST_PATH` as `PATH` inside the chroot, so tools like `uv`, `node`, `python3`, `ruby`, etc. resolve correctly.
+
+This behavior was introduced in **awf v0.60.0** and is active automatically — no extra flags are required.
+
+**Fallback behavior:** If `GITHUB_PATH` is not set (e.g., outside GitHub Actions or on self-hosted runners that don't set it), AWF uses `process.env.PATH` as the chroot PATH. If `sudo` has reset `PATH` before AWF runs and `GITHUB_PATH` is also absent, the tool's directory may be missing from the chroot PATH. In that case, invoke the tool via its absolute path or ensure `GITHUB_PATH` is set.
+
+**Troubleshooting:** Run AWF with `--log-level debug` to see whether `GITHUB_PATH` is set and how many entries were merged:
+
+```
+[DEBUG] Merged 3 path(s) from $GITHUB_PATH into AWF_HOST_PATH
+```
+
+If you see instead:
+
+```
+[DEBUG] GITHUB_PATH env var is not set; skipping $GITHUB_PATH file merge …
+```
+
+the runner did not set `GITHUB_PATH`, and the tool's bin directory must already be in `$PATH` at AWF launch time.
+
 ## Debugging Environment Variables
 
 The following environment variables control debugging behavior:
diff --git a/src/docker-manager.ts b/src/docker-manager.ts
index 27e60965..eafe69eb 100644
--- a/src/docker-manager.ts
+++ b/src/docker-manager.ts
@@ -163,6 +163,7 @@ export function extractGhHostFromServerUrl(serverUrl: string | undefined): strin
 export function readGitHubPathEntries(): string[] {
   const githubPathFile = process.env.GITHUB_PATH;
   if (!githubPathFile) {
+    logger.debug('GITHUB_PATH env var is not set; skipping $GITHUB_PATH file merge (tools installed by setup-* actions may be missing from PATH if sudo reset it)');
     return [];
   }
 
@@ -174,6 +175,7 @@ export function readGitHubPathEntries(): string[] {
       .filter(line => line.length > 0);
   } catch {
     // File doesn't exist or isn't readable — expected outside GitHub Actions
+    logger.debug(`GITHUB_PATH file at '${githubPathFile}' could not be read; skipping file merge`);
     return [];
   }
 }