feat: portable GH_AW_HOME for self-hosted runner support by Mossaka · Pull Request #19744 · github/gh-aw

Mossaka · 2026-03-05T18:21:39Z

Summary

Replace all hardcoded /opt/gh-aw/ paths with a GH_AW_HOME environment variable (defaults to /opt/gh-aw, falls back to $RUNNER_TEMP/gh-aw on self-hosted runners)
setup.sh auto-detects a writable path and exports GH_AW_HOME to $GITHUB_ENV for all subsequent steps
Shell contexts use ${GH_AW_HOME:-/opt/gh-aw}/..., JS require() uses (process.env.GH_AW_HOME || '/opt/gh-aw') + '/...'
All 165 lock files recompiled with new path patterns

Why: GitHub-hosted runners allow writing to /opt/, but self-hosted runners typically don't — requiring admins to sudo mkdir -p /opt/gh-aw && sudo chmod 777 /opt/gh-aw. This change makes gh-aw work out of the box on both.

Security: $RUNNER_TEMP/gh-aw is NOT mounted into the AWF agent container (only $GITHUB_WORKSPACE and /tmp are writable to the agent), so the security model is preserved.

Test plan

make build succeeds
make test-unit — all tests pass (updated 36 test files + 3 golden fixtures)
make test-js — all 209 JS test files pass (4928 tests)
make golint-incremental BASE_REF=HEAD — 0 issues
make recompile — all 165 lock files regenerated
Verified compiled .lock.yml files use $GH_AW_HOME patterns correctly
Smoke test on GitHub-hosted runner (backward compat: default /opt/gh-aw still works)

🤖 Generated with Claude Code

Add OpenCode as a new agentic engine supporting provider-agnostic AI coding with BYOK (Bring Your Own Key) and full MCP Gateway + API proxy support. New engine features: - Provider-agnostic: supports Anthropic, OpenAI, Google, Groq, etc. - Dynamic domain allowlists based on model provider prefix - API proxy on port 10004 (default: Anthropic routing) - MCP Gateway integration with opencode.jsonc converter - Headless CI mode via `opencode run -q` - Auto-configured permissions to prevent CI hanging - 22 unit tests covering all engine methods - Smoke test workflow (5 tests) Files: opencode_engine.go, opencode_mcp.go, opencode_engine_test.go, convert_gateway_config_opencode.sh, smoke-opencode.md/.lock.yml Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Add comprehensive external-facing documentation for the OpenCode engine: - New guide: docs/src/content/docs/guides/opencode.md (460 lines) - Quick start, auth/providers, network security, MCP support - Example workflows, engine comparison, known limitations - Update engines.md: add OpenCode to available agents list - Update auth.mdx: add OpenCode authentication reference - Update network.md: add OpenCode domain config + dynamic provider docs - Update astro.config.mjs: add sidebar link Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Fix BaseEngine struct changes (llmGatewayPort field, remove supportsFirewall, remove UsesAPIProxy from AWFCommandConfig) - Bump DefaultFirewallVersion to v0.23.1 which includes port 10004 for OpenCode API proxy (gh-aw-firewall#1055) - Recompile smoke-opencode.lock.yml with v0.23.1 - Fix test: use constants.OpenCodeLLMGatewayPort assertion Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

OpenCode v1.2.14 does not support -q/--quiet flag. The `run` subcommand accepts the message as a positional argument directly. Discovered from smoke test failure where the CLI printed usage and exited with code 1. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

github-actions · 2026-03-05T19:11:46Z

🎬 THE END — Smoke Claude MISSION: ACCOMPLISHED! The hero saves the day! ✨

github-actions · 2026-03-05T19:11:54Z

🌑 The shadows whisper... Smoke Codex failed. The oracle requires further meditation...

github-actions · 2026-03-05T19:11:56Z

❌ Tool validation failed! Agent Container Smoke Test detected missing tools: failed

github-actions · 2026-03-05T19:11:57Z

📰 BREAKING: Smoke Copilot is now investigating this pull request. Sources say the story is developing...

github-actions · 2026-03-05T19:21:17Z

📰 VERDICT: Smoke Copilot has concluded. All systems operational. This is a developing story. 🎤

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

OpenCode phones home to opencode.ai during initialization (telemetry/ config). Without this domain in the allowlist, Squid blocks the request and OpenCode fails silently with exit code 0. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…xpansion Re-applies all GH_AW_HOME portable path changes that were silently reverted during the merge with main. Also fixes a critical bug where job-level env vars using shell expansion syntax were not expanded by GitHub Actions ${{ env.X }} expressions (used by upload-artifact). Key fixes: - Move GH_AW_SAFE_OUTPUTS/CONFIG_PATH/TOOLS_PATH from job-level env to $GITHUB_ENV (set in "Create gh-aw temp directory" step after setup.sh sets GH_AW_HOME) - Re-apply JsRequireGhAw() for all require() patterns - Re-apply GhAwHome shell expansion for all bash run: blocks - Re-apply DefaultGhAwMount with shell expansion - Update golden files and test expectations Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

pelikhan · 2026-03-06T03:00:13Z

@copilot recompile, review code and simplify if possible (by compile resolved value and avoid repeating magic string)

Copilot · 2026-03-06T03:00:21Z

@pelikhan I've opened a new pull request, #19793, to work on those changes. Once the pull request is ready, I'll request review from you.

pelikhan · 2026-03-06T08:02:22Z

@copilot merge main and recompile

Copilot · 2026-03-06T08:02:28Z

@pelikhan I've opened a new pull request, #19817, to work on those changes. Once the pull request is ready, I'll request review from you.

pelikhan

@copilot define an environment variable on the job level to avoid repeating the macro everywhere

Copilot · 2026-03-06T08:24:22Z

@pelikhan I've opened a new pull request, #19823, to work on those changes. Once the pull request is ready, I'll request review from you.

…#19823)

pelikhan · 2026-03-07T16:24:59Z

@copilot merge main and recompile

github-actions · 2026-03-08T21:07:09Z

Hey @Mossaka 👋 — thanks for the ambitious work on GH_AW_HOME portability! Making gh-aw work out-of-the-box on self-hosted runners is a genuinely useful improvement, and the security analysis in the PR body is thoughtful. A few things would help get this across the finish line:

🔍 Checklist

Check	Result
On-topic	✅ yes
Follows process	⚠️ unclear (see below)
Focused	❌ no
New deps	✅ no
Has tests	✅ yes
Has description	✅ yes
Lines changed	31,443

⚠️ Issues Found

1. Unfocused — Multiple unrelated features bundled together

The PR title says "portable GH_AW_HOME for self-hosted runner support", but the diff actually ships three distinct features:

GH_AW_HOME path portability — the stated goal (~200 lock files + setup_action_paths.go)
OpenCode engine integration — a brand-new engine (opencode_engine.go +303 lines, opencode_mcp.go +71 lines, opencode_engine_test.go +369 lines, docs/guides/opencode.md, convert_gateway_config_opencode.sh) — also called out in .changeset/patch-add-opencode-engine.md under its own changelog entry
Concurrency, expression extraction & schedule preprocessing improvements — concurrency.go (+51 lines), expression_extraction.go (+33 lines), schedule_preprocessing_test.go (+183 lines), and others

These three concerns should live in separate, reviewable PRs. As written, a reviewer can't confidently approve the GH_AW_HOME change without also auditing the OpenCode engine implementation, which is a significant new surface area.

2. Changeset description mismatch

.changeset/patch-add-opencode-engine.md reads "Add the OpenCode engine integration with its MCP/Gateway support and dynamic allowlists." — which doesn't match the PR title or description at all. This changeset should be in its own PR.

3. Process note

CONTRIBUTING.md states that PRs are created and managed by the core team using coding agents. If you're contributing as a community member, the expected path is to open a detailed issue with an agentic plan so a core team member can implement it. If you are on the core team, disregard this note.

🛠️ Suggested next steps

If you'd like a hand breaking this up, you can assign this prompt to your coding agent:

Split PR #19744 (github/gh-aw) into three focused pull requests:

1. **GH_AW_HOME portability** — include only:
   - All `.lock.yml` file changes that replace hardcoded `/opt/gh-aw/` with `\$\{GH_AW_HOME}` or `process.env.GH_AW_HOME`
   - `actions/setup/setup.sh` changes for auto-detecting writable path
   - `pkg/workflow/setup_action_paths.go` changes
   - A correctly-titled changeset entry (e.g. `.changeset/patch-gh-aw-home.md`)
   - PR description should focus on: why self-hosted runners can't write to /opt, the fallback logic to $RUNNER_TEMP/gh-aw, and the security note about agent container mounts

2. **OpenCode engine integration** — include only:
   - `pkg/workflow/opencode_engine.go`
   - `pkg/workflow/opencode_mcp.go`
   - `pkg/workflow/opencode_engine_test.go`
   - `actions/setup/sh/convert_gateway_config_opencode.sh`
   - `.github/workflows/smoke-opencode.md`
   - `docs/src/content/docs/guides/opencode.md`
   - `.changeset/patch-add-opencode-engine.md`
   - PR description should explain the new engine, its MCP/Gateway config, and dynamic allowlist behavior

3. **Compiler improvements** — include only:
   - `pkg/workflow/concurrency.go` + `concurrency_test.go`
   - `pkg/workflow/expression_extraction.go` + `expression_extraction_test.go`
   - `pkg/workflow/schedule_preprocessing_test.go`
   - Other unrelated compiler/safe-outputs fixes
   - A descriptive changeset entry

For each PR: run `make agent-finish` to validate (build, test, recompile, lint), ensure the title matches the actual changeset description, and confirm the smoke test passes before marking ready for review.

Generated by Contribution Check · ◷

pelikhan · 2026-03-09T01:14:30Z

Restarting fresh from #20143

Copilot AI review requested due to automatic review settings March 5, 2026 18:21

This was referenced Mar 5, 2026

Smoke Test: Copilot - 22730512075 #19746

Closed

Smoke Test: Claude - 22730805579 #19751

Closed

Mossaka and others added 6 commits March 5, 2026 18:57

Add changeset [skip-ci]

cc1ee85

ci: trigger checks

7cbb0f5

Mossaka added the smoke label Mar 5, 2026

Copilot AI reviewed Mar 5, 2026

View reviewed changes

Mossaka and others added 3 commits March 5, 2026 19:28

fix: regenerate wasm golden files for action pin updates

0feaad3

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Mossaka force-pushed the portable-gh-aw-home branch from 192debf to 42c1f84 Compare March 5, 2026 19:49

Mossaka and others added 2 commits March 5, 2026 19:54

fix: format code

6e8fd7b

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: update integration test to accept ${GH_AW_HOME} paths

6b63382

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

This comment has been minimized.

Sign in to view

github-actions bot added the needs-work label Mar 5, 2026

This comment has been minimized.

Sign in to view

github-actions bot mentioned this pull request Mar 5, 2026

[Contribution Check Report] Contribution Check — 2026-03-05 #19768

Closed

Merge branch 'main' into portable-gh-aw-home

32470af

Copilot AI mentioned this pull request Mar 6, 2026

refactor: eliminate repeated GH_AW_HOME magic strings using existing constants #19793

Merged

github-actions bot mentioned this pull request Mar 6, 2026

[Contribution Check Report] Contribution Check — 2026-03-06 #19808

Closed

Copilot AI mentioned this pull request Mar 6, 2026

chore: merge main into portable-gh-aw-home and recompile #19817

Merged

chore: merge main into portable-gh-aw-home and recompile (#19817)

59d5776

pelikhan reviewed Mar 6, 2026

View reviewed changes

Copilot AI mentioned this pull request Mar 6, 2026

Define GH_AW_HOME at job level to eliminate fallback macro repetition #19823

Merged

github-actions bot mentioned this pull request Mar 6, 2026

[Daily Report] Daily Status Report — 2026-03-06 #19828

Open

Define GH_AW_HOME at job level to eliminate fallback macro repetition (…

442a051

…#19823)

github-actions bot mentioned this pull request Mar 7, 2026

[Daily Report] Daily Status Report - 2026-03-07 #19937

Open

github-actions bot mentioned this pull request Mar 7, 2026

[Contribution Check Report] Contribution Check — 2026-03-07 #19986

Closed

This comment has been minimized.

Sign in to view

github-actions bot mentioned this pull request Mar 8, 2026

[Contribution Check Report] Contribution Check — 2026-03-08 #20015

Closed

This comment has been minimized.

Sign in to view

This was referenced Mar 8, 2026

[Contribution Check Report] Contribution Check Report — 2026-03-08 #20040

Closed

[Daily Report] Daily Status Report — 2026-03-08 #20041

Open

This comment has been minimized.

Sign in to view

github-actions bot mentioned this pull request Mar 8, 2026

[Contribution Check Report] Contribution Check — 2026-03-08 #20091

Closed

github-actions bot mentioned this pull request Mar 8, 2026

[Contribution Check Report] Contribution Check Report — 2026-03-08 #20121

Closed

pelikhan closed this Mar 9, 2026

Copilot AI mentioned this pull request Mar 9, 2026

Replace hardcoded /opt/gh-aw/ paths with GH_AW_HOME env var for self-hosted runner portability #20143

Open

21 tasks

github-actions bot mentioned this pull request Mar 10, 2026

[Contribution Check Report] March 10, 2026 #20298

Closed

Conversation

Mossaka commented Mar 5, 2026

Summary

Test plan

Uh oh!

github-actions bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 5, 2026

Uh oh!

github-actions bot commented Mar 5, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

This comment has been minimized.

pelikhan commented Mar 6, 2026

Uh oh!

Copilot AI commented Mar 6, 2026

Uh oh!

pelikhan commented Mar 6, 2026

Uh oh!

Copilot AI commented Mar 6, 2026

Uh oh!

pelikhan left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Mar 6, 2026

Uh oh!

pelikhan commented Mar 7, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

github-actions bot commented Mar 8, 2026

🔍 Checklist

⚠️ Issues Found

1. Unfocused — Multiple unrelated features bundled together

2. Changeset description mismatch

3. Process note

🛠️ Suggested next steps

Uh oh!

pelikhan commented Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Mar 5, 2026 •

edited

Loading

github-actions bot commented Mar 5, 2026 •

edited

Loading

github-actions bot commented Mar 5, 2026 •

edited

Loading