Open
docs: align ARC/DinD docs, spec, and schema with implementation#5890
Conversation
6 tasks
Copilot
AI
changed the title
[WIP] Align ARC/DinD docs, spec, and schema with current implementation
docs: align ARC/DinD docs, spec, and schema with implementation
Jul 3, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
This PR corrects and expands ARC/DinD (split runner/daemon filesystem) documentation and JSON schema descriptions so they match the current implementation, and adds cross-links between the various ARC/DinD guidance surfaces.
Changes:
- Update
runner.topology,container.enableDind, andcontainer.dockerHostschema descriptions to reflect actual ARC/DinD behavior and security implications. - Document loopback TCP (
tcp://localhost:*/tcp://127.0.0.1:*) as an ARC/DinD auto-detection signal and add “See also” cross-references. - Add references to
arc-dind.mdfrom the usage/environment docs and include it in the config spec’s informative references.
Show a summary per file
| File | Description |
|---|---|
| docs/usage.md | Adds an ARC/DinD pointer from the --enable-dind section to the dedicated ARC/DinD guide. |
| docs/environment.md | Adds a “See also” cross-reference to the ARC/DinD guide from the env/config guidance. |
| docs/awf-config.schema.json | Updates schema descriptions for ARC/DinD topology and Docker host/DinD fields to better match implementation. |
| docs/awf-config-spec.md | Adds arc-dind.md to Informative References. |
| docs/arc-dind.md | Documents loopback TCP auto-detection and adds a “See also” section linking related references. |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 5/5 changed files
- Comments generated: 2
- Review effort level: Low
Comment on lines
794
to
801
| "topology": { | ||
| "type": "string", | ||
| "enum": [ | ||
| "standard", | ||
| "arc-dind" | ||
| ], | ||
| "description": "Runner deployment topology. 'standard' (default) = GitHub-hosted VM or self-hosted runner with local Docker. 'arc-dind' = ARC (Actions Runner Controller) with Docker-in-Docker sidecar, where the runner and Docker daemon have separate filesystems. When set to 'arc-dind', AWF applies overridable defaults: network.isolation=true, dind.preStageDirs=true, sysroot image activation, and tool cache validation." | ||
| "description": "Runner deployment topology. 'standard' (default) = GitHub-hosted VM or self-hosted runner with local Docker. 'arc-dind' = ARC (Actions Runner Controller) with Docker-in-Docker sidecar, where the runner and Docker daemon have separate filesystems. When set to 'arc-dind', AWF enables sysroot staging (a sysroot-stage init container copies the build-tools image into a named volume mounted at /host:rw on the agent) and emits a warning when RUNNER_TOOL_CACHE points under /opt (which is typically invisible to the DinD daemon). Other ARC/DinD settings such as container.dockerHostPathPrefix, dind.preStageDirs, and network.isolation are configured explicitly through their own fields. See docs/arc-dind.md for a complete guide." | ||
| }, |
Comment on lines
599
to
602
| "dockerHost": { | ||
| "type": "string", | ||
| "description": "Docker daemon socket or host to connect to (e.g. \"unix:///var/run/docker.sock\")." | ||
| "description": "Docker daemon socket URI for AWF's own operations (e.g. \"unix:///var/run/docker.sock\" or \"tcp://localhost:2375\"). Auto-detected from the DOCKER_HOST environment variable when not set explicitly. When combined with container.enableDind, AWF also mounts that socket inside the agent and sets the agent's DOCKER_HOST to the same URI so in-agent docker commands use the correct daemon. On ARC/DinD runners with a loopback TCP daemon (tcp://localhost:*), AWF detects the split-filesystem configuration automatically." | ||
| }, |
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.
The
runner.topology: arc-dindschema description incorrectly claimed that setting this topology automatically enablesnetwork.isolation=trueanddind.preStageDirs=true. The implementation only enables sysroot staging and emits aRUNNER_TOOL_CACHEwarning — other settings must be configured explicitly. Docs also lacked cross-links between ARC/DinD surfaces and were missing the loopback TCP auto-detection case.Changes
docs/awf-config.schema.jsonrunner.topology(correctness fix): Remove false claim about automaticnetwork.isolation=true/dind.preStageDirs=truedefaults. Actual behavior: enablessysroot-stageinit container +sysroot:/host:rwvolume, emits/opttool-cache warning. Explicitly state other fields must be set independently.container.enableDind: Expand description to cover Docker socket exposure, DOCKER_HOST propagation, and security implication.container.dockerHost: Expand to cover DOCKER_HOST auto-detection,enableDindinteraction, and ARC/DinD loopback TCP detection.docs/arc-dind.mdtcp://localhost:*/tcp://127.0.0.1:*) to the auto-detection section — this pattern is handled byisSiblingDaemonSocket()but was undocumented.docs/awf-config-spec.mddocs/arc-dind.mdto Informative References.docs/environment.md/docs/usage.mdarc-dind.mdat the relevant ARC/DinD sections.