Add ARC DinD how-to guide for running GitHub Copilot coding agent on self-hosted runners

[Copilot]

Customers using Actions Runner Controller (ARC) with Docker-in-Docker (DinD) had no official, end-to-end guide for running GitHub Copilot coding agent in this common self-hosted topology. This PR adds a focused how-to that documents the required DinD runner configuration and usage in gh-aw workflows.

• New guide: ARC + DinD setup for Copilot coding agent

  • Added docs/src/content/docs/guides/arc-dind-copilot-agent.md.
  • Covers prerequisites, ARC controller install, runner namespace/auth secret creation, DinD runner scale set install, runner verification, and workflow targeting.
  • Explicitly documents required assumptions: containerMode.type="dind" (kubernetes mode unsupported), NET_ADMIN, non-root runner user support (with sudo ability preserved), and distro/namespace flexibility. Also warns that securityContext.allowPrivilegeEscalation: false may break Copilot coding agent since it blocks sudo.

• Docs navigation update

  • Added a Guides sidebar entry in docs/astro.config.mjs:
    • ARC DinD for Copilot Coding Agent → /guides/arc-dind-copilot-agent/.

• Reference cross-link

  • Updated docs/src/content/docs/reference/self-hosted-runners.md (ARC DinD section) to link to the new step-by-step guide for operational setup.

helm install "arc-runner-set" \
  --namespace "arc-runners" --create-namespace \
  --set githubConfigUrl="https://github.com/<OWNER>/<REPO>" \
  --set githubConfigSecret="arc-runner-secret" \
  --set containerMode.type="dind" \
  --set-json 'template.spec.containers=[{
    "name": "runner",
    "image": "ghcr.io/actions/actions-runner:latest",
    "command": ["/home/runner/run.sh"],
    "securityContext": {
      "capabilities": { "add": ["NET_ADMIN"] }
    }
  }]' \
  oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set

[lpcox]

Review — Technical Accuracy Issues

I've been working on ARC/DinD support across gh-aw and gh-aw-firewall for the past two weeks (#42906, #43222, #44145, #44445). Here are the issues I found:

---

🔴 Critical: Missing runner.topology: arc-dind in workflow frontmatter (Section 5)

The example frontmatter is missing the key setting that triggers all split-filesystem handling:

---
on: issues
runs-on: arc-runner-set
runner:
  topology: arc-dind
---

Without runner.topology: arc-dind, the compiled workflow won't get: sysroot volumes, Docker Compose installation, daemon-visible node/copilot paths, workspace mounts, artifact consolidation, or chroot config patching. The workflow will fail immediately on ARC/DinD.

---

🔴 NET_ADMIN explanation is misleading

The guide says NET_ADMIN is "required for network operations in the DinD topology." It's specifically needed so AWF can apply iptables rules to the host-level DOCKER-USER chain for network egress filtering. The DinD sidecar already gets its own NET_ADMIN by default (it runs privileged). The capability is needed on the runner container, not for generic "network operations."

---

🔴 "Rootless execution: Assumed" contradicts requirements

The table says "The official runner image default is rootless." But the self-hosted-runners reference doc explicitly states:

Self-hosted runners must allow sudo for agentic workflows... a non-sudo mode is not supported, including ARC configurations with allowPrivilegeEscalation: false.

The runner must be able to run sudo. The install script (install_copilot_cli.sh) uses sudo for binary installation and directory ownership fixes. "Rootless" is misleading here.

---

🟡 Missing minimum version requirements

The guide should note minimum versions where ARC/DinD works correctly:

• gh-aw ≥ v0.82.5 (includes #44145 workspace fix + #44445 detection fix)
• AWF ≥ v0.27.22 (squid log permission fix)

Earlier versions have known bugs: empty workspace, split artifact roots, detection job ENOENT.

---

🟡 Outdated --docker-host-path-prefix in self-hosted-runners.md

The existing reference doc (line 24) says the probe "appends --docker-host-path-prefix /tmp/gh-aw." This is now incorrect — #44145 (merged July 8) removed the prefix flag entirely. With sysroot-stage active, all paths are on the shared work volume and visible to the Docker daemon without translation. The probe now only passes --docker-host and runs the chroot config patch.

Also, the doc says the regex matches tcp://localhost:<port> or tcp://127.0.0.1:<port>, but the actual regex is ^tcp:// — it matches any TCP docker host including pod IPs and K8s service names (tcp://dind:2375, tcp://172.30.0.5:2375, etc.).

---

🟡 Missing privileged DinD sidecar note

ARC's DinD mode runs the sidecar in privileged mode by default (required for Docker daemon). This is automatic with containerMode.type="dind", but worth noting for operators using custom pod templates who might inadvertently restrict it.

---

💡 Suggested additions

1. sandbox.agent.sudo: false — recommend this in the frontmatter since AWF handles network isolation inside the container without requiring sudo on the agent.
2. Troubleshooting: no-new-privileges — note that clusters enforcing allowPrivilegeEscalation: false (via PodSecurity Admission or OPA) are not currently supported because the install script requires sudo.
3. Shared work volume — briefly explain that ARC DinD mode shares /home/runner/_work/ between runner and daemon, which is why workspace mounts work without path translation.

[Copilot]

Pull request overview

This PR adds end-to-end documentation for running GitHub Copilot coding agent on self-hosted runners managed by Actions Runner Controller (ARC) using a Docker-in-Docker (DinD) topology, and wires the guide into the docs navigation and cross-references.

Changes:

• Added a new step-by-step guide for ARC + DinD runner scale set setup and workflow targeting.
• Added a Guides sidebar entry for the new ARC DinD guide.
• Linked the self-hosted runners reference page to the new guide from the ARC DinD section.

Show a summary per file

File	Description
docs/src/content/docs/reference/self-hosted-runners.md	Adds a cross-link from the ARC DinD reference section to the new walkthrough guide.
docs/src/content/docs/guides/arc-dind-copilot-agent.md	New how-to guide describing ARC controller install, runner secret creation, DinD runner scale set setup, and workflow targeting.
docs/astro.config.mjs	Adds the new guide to the Guides sidebar navigation.

Review details

Tip

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

• Files reviewed: 3/3 changed files
• Comments generated: 4
• Review effort level: Low

[lpcox]

Correction on my earlier suggestion about sandbox.agent.sudo: false — please disregard that. The default for sandbox.agent.sudo is already false (network isolation mode), so topology: arc-dind is the only thing needed in frontmatter beyond the standard on and runs-on. Adding explicit sandbox.agent.sudo: false would be redundant and confusing.

The frontmatter example in section 5 should just be:

---
on: issues
runs-on: arc-runner-set
runner:
  topology: arc-dind
---

No other sandbox/network settings are needed — the compiler handles everything else when it sees topology: arc-dind.

[lpcox]

@copilot address all review feedback

[Copilot]

Review — Technical Accuracy Issues

I've been working on ARC/DinD support across gh-aw and gh-aw-firewall for the past two weeks (#42906, #43222, #44145, #44445). Here are the issues I found:...

Addressed in commit 2d416fa.

Updated docs to include required runner.topology: arc-dind, clarified NET_ADMIN as runner-container DOCKER-USER iptables support, replaced rootless wording with explicit runner-host sudo requirement, added minimum version guidance (gh-aw >= v0.82.5, AWF >= v0.27.22), documented privileged DinD sidecar and shared /home/runner/_work behavior, added allowPrivilegeEscalation: false/no-new-privileges troubleshooting, recommended sandbox.agent.sudo: false with host/sandbox sudo distinction, and corrected self-hosted-runners.md to current ARC DinD probe behavior (no --docker-host-path-prefix, ^tcp:// matching behavior).

[lpcox]

Another note: Section 2 only shows a PAT for runner authentication, but ARC also supports GitHub App credentials (recommended for production — finer-grained permissions, no expiry). The guide should show both options:

# Option A: PAT
kubectl create secret generic arc-runner-secret \
  --namespace=arc-runners \
  --from-literal=github_token=<YOUR_PAT>

# Option B: GitHub App (recommended for production)
kubectl create secret generic arc-runner-secret \
  --namespace=arc-runners \
  --from-literal=github_app_id=<APP_ID> \
  --from-literal=github_app_installation_id=<INSTALL_ID> \
  --from-literal=github_app_private_key=<PRIVATE_KEY>

See ARC authentication docs for details.