Add ARC-DinD runner topology with sysroot-stage build-tools image by Copilot · Pull Request #5697 · github/gh-aw-firewall

Copilot · 2026-06-29T23:22:00Z

This change adds a stable ARC/DinD contract to AWF via runner.topology and runner.sysrootImage, enabling split-filesystem runners to start agent containers without runtime root package installation. It also introduces a dedicated build-tools sysroot image and wires it into compose generation and release publishing.

Config surface: runner.topology + runner.sysrootImage
- Added runner section to AWF config types, mapping, and schema validation.
- Supported values:
  - runner.topology: "arc-dind"
  - optional runner.sysrootImage override (defaults to ghcr.io/github/gh-aw-firewall/build-tools:latest).
Compose behavior for ARC/DinD
- Added sysroot-stage one-shot init service.
- Added named sysroot volume and mounted it into agent as /host:ro.
- Agent now depends on sysroot-stage completion in arc-dind topology.
- In sysroot topology, host system bind-mounts (/usr, /bin, /lib*, /opt, /sys, /dev) are not layered over /host, so staged sysroot content remains authoritative.
ARC operational guardrail
- Added warning when runner.topology=arc-dind and RUNNER_TOOL_CACHE is under /opt, which is commonly not daemon-visible in DinD layouts.
Build-tools sysroot image + release publishing
- Added containers/build-tools/Dockerfile (Ubuntu 22.04 with compilers/linkers, dev libs, and required utilities like capsh, gosu, gh).
- Added build-build-tools job to release workflow with multi-arch build, cosign signing, and SBOM attestation.
Docs/spec updates
- Updated ARC/DinD docs with topology selector usage, sysroot staging flow, and tool-cache path guidance.
- Updated AWF config schema docs/runtime copy to include runner section.

{
  "runner": {
    "topology": "arc-dind",
    "sysrootImage": "ghcr.io/github/gh-aw-firewall/build-tools:latest"
  }
}

Copilot

Pull request overview

This PR introduces an explicit ARC+DinD runner contract to AWF by adding a runner topology (arc-dind) that stages a “sysroot” into a named Docker volume via a one-shot sysroot-stage service, then mounts that sysroot into the agent’s chroot. It also adds a dedicated build-tools sysroot image (plus release publishing) and updates config types, mapping, schema validation, tests, and docs to support the new config surface.

Changes:

Add runner.topology=arc-dind and runner.sysrootImage to AWF config types/mapping/schema and validation tests.
Extend compose generation to optionally add sysroot-stage + sysroot volume and adjust agent mount behavior for sysroot topology.
Add a new containers/build-tools image and publish it from the release workflow (multi-arch + cosign + SBOM), plus update ARC/DinD documentation and guardrail warnings.

Show a summary per file

File	Description
src/types/wrapper-config.ts	Extends `WrapperConfig` with runner-related options.
src/types/runner-options.ts	Introduces runner option types for topology + sysroot image.
src/services/sysroot-service.ts	Adds sysroot topology detection, sysroot image resolution, and sysroot-stage service definition.
src/services/sysroot-service.test.ts	Unit tests for sysroot service behavior and defaults.
src/services/agent-volumes/volume-builder.ts	Threads sysroot topology flag into system mount construction.
src/services/agent-volumes/system-mounts.ts	Modifies system mount list behavior when sysroot topology is enabled.
src/schema.test.ts	Adds schema validation coverage for the new `runner` config section.
src/config-mapper.ts	Maps file config `runner.*` into flattened CLI/build-config options.
src/config-file.ts	Adds `runner` section to the config-file TypeScript interface.
src/config-file-validation.test.ts	Adds schema-driven validation tests for runner config errors.
src/config-file-mapping.test.ts	Adds mapping tests for runner topology fields.
src/compose-generator.ts	Adds sysroot-stage service + sysroot volume and agent dependency wiring.
src/compose-generator.test.ts	Tests sysroot-stage service inclusion and agent mount/depends_on behavior.
src/commands/validators/network-options.ts	Adds ARC-specific warning when RUNNER_TOOL_CACHE is under `/opt` for `arc-dind`.
src/commands/validators/network-options.test.ts	Adds tests asserting the RUNNER_TOOL_CACHE warning behavior.
src/commands/build-config.ts	Plumbs runner topology/sysroot image options into `WrapperConfig`.
src/awf-config-schema.json	Extends the published JSON schema with the `runner` object.
docs/awf-config.schema.json	Mirrors schema changes into docs copy.
docs/arc-dind.md	Documents the new runner topology, sysroot staging, and tool cache guidance.
containers/build-tools/Dockerfile	Adds build-tools sysroot image definition (Ubuntu 22.04 + build deps/utilities).
.github/workflows/release.yml	Builds, pushes, signs, and attests the build-tools image during releases.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 21/21 changed files
Comments generated: 5
Review effort level: Low

lpcox · 2026-06-30T00:24:07Z

+  const sysrootEnabled = isSysrootTopologyEnabled(config);
+  if (sysrootEnabled) {
+    agentService.volumes = [`sysroot:/host:ro`, ...(agentService.volumes || [])];
+    agentService.depends_on['sysroot-stage'] = {
+      condition: 'service_completed_successfully',
+    };
+  }


Fixed -- changed sysroot:/host:ro to sysroot:/host:rw since the agent entrypoint writes resolv.conf and hosts into /host/etc during chroot setup.

lpcox · 2026-06-30T00:24:07Z

  const mounts = [
-    '/usr:/host/usr:ro',
-    '/bin:/host/bin:ro',
-    '/sbin:/host/sbin:ro',
-    '/lib:/host/lib:ro',
-    '/lib64:/host/lib64:ro',
-    '/opt:/host/opt:ro',
-    '/sys:/host/sys:ro',
-    '/dev:/host/dev:ro',
+    ...(useSysroot
+      ? []
+      : [
+        '/usr:/host/usr:ro',
+        '/bin:/host/bin:ro',
+        '/sbin:/host/sbin:ro',
+        '/lib:/host/lib:ro',
+        '/lib64:/host/lib64:ro',
+        '/opt:/host/opt:ro',
+        '/sys:/host/sys:ro',
+        '/dev:/host/dev:ro',
+      ]),
    `${workspaceDir}:/host${workspaceDir}:rw`,
    '/tmp:/host/tmp:rw',
  ];


Good catch -- sysroot mode now keeps /sys and /dev bind mounts (live kernel VFS) while only skipping the userspace dirs (/usr, /bin, /sbin, /lib, /lib64, /opt) that the sysroot volume provides.

lpcox · 2026-06-30T00:24:07Z

+    command: [
+      '/bin/bash',
+      '-lc',
+      "set -euo pipefail; rm -rf /sysroot/.awf-tmp; mkdir -p /sysroot/.awf-tmp; tar -C / --exclude='./sysroot' -cf - . | tar -C /sysroot -xf -",
+    ],


No change needed here -- the implementation already uses targeted cp -a for specific directories (usr, lib, bin, sbin, etc, and conditionally lib64). It does not archive /proc, /sys, or /dev. The staging command is already selective by design.

lpcox · 2026-06-30T00:24:07Z

+export function resolveSysrootImage(config: WrapperConfig, imageConfig: ImageBuildConfig): string {
+  if (config.runnerSysrootImage) {
+    return config.runnerSysrootImage;
+  }
+  return `${imageConfig.registry}/build-tools:${imageConfig.parsedTag.tag}`;
+}


Updated the docs to clarify that the default sysroot image is derived dynamically from --image-registry and --image-tag (same as other AWF containers), not hardcoded. The implementation is correct -- it uses the user's configured registry/tag so private registries and pinned versions work out of the box.

lpcox · 2026-06-30T00:24:07Z

+- `runner.topology: "arc-dind"`: enables sysroot staging (`sysroot-stage` init service + `sysroot` volume mounted on agent at `/host:ro`).
+- `runner.sysrootImage`: optional override for the sysroot image used by `runner.topology=arc-dind`.
+
+## Build-tools sysroot image
+
+When `runner.topology` is `arc-dind`, AWF starts a one-shot `sysroot-stage` service that copies
+the filesystem from `ghcr.io/github/gh-aw-firewall/build-tools:latest` into a named `sysroot`
+volume. The agent mounts that volume at `/host:ro`.


Fixed -- docs now say /host:rw to match the implementation. The volume is ephemeral per run so read-write access is safe and required for the entrypoint's DNS/hosts setup.

Reconcile duplicate runner topology definitions: - Remove runnerTopology/sysrootImage from PlatformOptions (now in RunnerOptions) - Add "standard" to RunnerOptions.runnerTopology enum for consistency - Remove duplicate runnerTopology property in build-config.ts - Fix test assertion for updated topology enum values Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-06-30T00:19:39Z

✅ Copilot review passed with no inline comments.

@copilot Add the ready-for-aw label to this PR to trigger agentic CI smoke tests.

github-actions · 2026-06-30T00:19:51Z

Documentation Preview

Documentation build failed for this PR. View logs.

Built from commit 1ac92c4

github-actions · 2026-06-30T00:21:34Z

⚠️ Coverage Regression Detected

This PR decreases test coverage. Please add tests to maintain coverage levels.

Overall Coverage

Metric	Base	PR	Delta
Lines	98.38%	98.42%	📈 +0.04%
Statements	98.31%	98.35%	📈 +0.04%
Functions	99.54%	99.54%	➡️ +0.00%
Branches	94.45%	94.44%	📉 -0.01%

📁 Per-file Coverage Changes (1 files)

File	Lines (Before → After)	Statements (Before → After)
`src/workdir-setup.ts`	92.7% → 94.5% (+1.82%)	92.7% → 94.5% (+1.82%)

Coverage comparison generated by scripts/ci/compare-coverage.ts

- Mount sysroot volume at /host:rw (agent entrypoint writes resolv.conf) - Keep /sys and /dev bind mounts in sysroot mode (live kernel VFS needed) - Clarify docs: default sysroot image derives from --image-registry/--image-tag - Update docs from :ro to :rw to match implementation Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-06-30T00:25:55Z

⚠️ Coverage Regression Detected

This PR decreases test coverage. Please add tests to maintain coverage levels.

Overall Coverage

Metric	Base	PR	Delta
Lines	98.38%	98.42%	📈 +0.04%
Statements	98.31%	98.35%	📈 +0.04%
Functions	99.54%	99.54%	➡️ +0.00%
Branches	94.45%	94.44%	📉 -0.01%

📁 Per-file Coverage Changes (1 files)

File	Lines (Before → After)	Statements (Before → After)
`src/workdir-setup.ts`	92.7% → 94.5% (+1.82%)	92.7% → 94.5% (+1.82%)

Coverage comparison generated by scripts/ci/compare-coverage.ts

Initial plan

bbe9671

Copilot AI assigned Copilot and lpcox Jun 29, 2026

Copilot started work on behalf of lpcox June 29, 2026 23:22 View session

feat: add ARC-DinD sysroot topology support

d2f4c55

Copilot AI changed the title ~~[WIP] Add build-tools sysroot image and runner topology config~~ Add ARC-DinD runner topology with sysroot-stage build-tools image Jun 29, 2026

Copilot AI requested a review from lpcox June 29, 2026 23:34

Copilot finished work on behalf of lpcox June 29, 2026 23:34

lpcox marked this pull request as ready for review June 29, 2026 23:44

Copilot AI review requested due to automatic review settings June 29, 2026 23:44

Copilot started reviewing on behalf of lpcox June 29, 2026 23:45 View session

Copilot AI reviewed Jun 29, 2026

View reviewed changes

lpcox added the ready-for-aw label Jun 30, 2026

lpcox merged commit b814a51 into main Jun 30, 2026
27 of 30 checks passed

lpcox deleted the copilot/arc-dind-add-build-tools-sysroot-image branch June 30, 2026 00:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add ARC-DinD runner topology with sysroot-stage build-tools image#5697

Add ARC-DinD runner topology with sysroot-stage build-tools image#5697
lpcox merged 4 commits into
mainfrom
copilot/arc-dind-add-build-tools-sysroot-image

Copilot AI commented Jun 29, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

lpcox Jun 30, 2026

Uh oh!

lpcox Jun 30, 2026

Uh oh!

lpcox Jun 30, 2026

Uh oh!

lpcox Jun 30, 2026

Uh oh!

lpcox Jun 30, 2026

Uh oh!

github-actions Bot commented Jun 30, 2026

Uh oh!

github-actions Bot commented Jun 30, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 30, 2026

Uh oh!

github-actions Bot commented Jun 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

Copilot AI commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Review details

Uh oh!

lpcox Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

lpcox Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

lpcox Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

lpcox Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

lpcox Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jun 30, 2026

Uh oh!

github-actions Bot commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation Preview

Uh oh!

github-actions Bot commented Jun 30, 2026

⚠️ Coverage Regression Detected

Overall Coverage

Uh oh!

github-actions Bot commented Jun 30, 2026

⚠️ Coverage Regression Detected

Overall Coverage

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Jun 29, 2026 •

edited

Loading

github-actions Bot commented Jun 30, 2026 •

edited

Loading