docs: add runner environment requirements, GHES, and ARC sections to self-hosted guide#31923
Merged
Conversation
…self-hosted guide Add guiding principles for self-hosted runner compatibility: - Use RUNNER_TEMP for transient state (not /tmp on shared runners) - No root/sudo assumption for tool installs - No global installs to read-only system paths - No hardcoded HOME paths - Post-job cleanup expectations Add GHES section documenting: - ghes-artifact-compat feature flag for v3.x artifact actions - API endpoint configuration reference Add ARC/Kubernetes section covering: - Docker-in-Docker sidecar support - Socket retry for dind startup race - Pod security requirements Ref #28888, #29551
Contributor
Contributor
Comment MemoryNote This comment is managed by comment memory.It stores persistent context for this thread in the code block at the top of this comment. |
Contributor
There was a problem hiding this comment.
Pull request overview
Expands the self-hosted runners guide to cover operational requirements and additional guidance for ARC/Kubernetes and GHES environments.
Changes:
- Updated the guide description and added an Enterprise Configuration link in “Related documentation”.
- Added a “Runner environment requirements” section covering Docker, filesystem, cleanup, and network expectations.
- Added new GHES and ARC sections with configuration notes and recommendations.
Show a summary per file
| File | Description |
|---|---|
docs/src/content/docs/guides/self-hosted-runners.md |
Adds self-hosted runner requirements plus GHES and ARC-specific guidance to help users run agentic workflows outside GitHub-hosted runners. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 3
|
|
||
| ### Filesystem | ||
|
|
||
| - **Use `RUNNER_TEMP` for transient state.** All job-scoped temporary files (sandbox state, tool downloads, intermediate outputs) should go to `$RUNNER_TEMP`, which is cleaned between jobs. Never write to `/tmp` on shared runners — it persists across jobs. |
Comment on lines
+199
to
+217
| GHES does not support the `@actions/artifact` v2.0.0+ backend used by `upload-artifact@v4+` and `download-artifact@v4+`. Compiled workflows use the latest artifact action versions by default, which fail on GHES with `GHESNotSupportedError`. | ||
|
|
||
| Enable the `ghes-artifact-compat` feature flag to use compatible v3.x artifact actions: | ||
|
|
||
| ```aw | ||
| --- | ||
| on: workflow_dispatch | ||
| runs-on: [self-hosted, linux] | ||
| features: | ||
| ghes-artifact-compat: true | ||
| engine: copilot | ||
| --- | ||
| ``` | ||
|
|
||
| Or set the environment variable globally: | ||
|
|
||
| ```bash | ||
| GH_AW_FEATURES=ghes-artifact-compat gh aw compile | ||
| ``` |
|
|
||
| A working Docker daemon is required. The MCP gateway and sandbox run as containers. | ||
|
|
||
| - **Unix socket**: Docker must be accessible via a Unix socket (typically `/var/run/docker.sock`). The gateway resolves the socket path from `DOCKER_HOST` if set. |
Collaborator
|
@copilot review all comments, build docs |
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Collaborator
|
some of these recommendations need to become instructions or even compiler magic to rewrite. |
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Contributor
pelikhan
reviewed
May 13, 2026
|
|
||
| ### Filesystem | ||
|
|
||
| - **Use `RUNNER_TEMP` for transient state.** Put sandbox state, tool downloads, and intermediate outputs in `$RUNNER_TEMP`, which is cleaned between jobs. On shared runners, avoid writing arbitrary workflow data to `/tmp` because it can persist across jobs. The `/tmp/gh-aw` prefix is reserved for gh-aw/AWF ARC DinD path rewriting. `actions/setup` resets `/tmp/gh-aw` at job start, and your normal runner `/tmp` cleanup policy should handle stale data from interrupted jobs. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Expands the self-hosted runners guide with three new sections:
Ref #28888, #29551