How do we create an agentic workflow that can fix an issue and run tests in a dev container?

[afreer]

Dear GitHub Agentic Workflow Community,

We’re excited to start using agentic workflows! Can you please help us with some questions? We suspect/hope they’re easy ones 😎.

(1) Our goal is basically to be able to run the agentic workflow and ask it to try to fix a specified issue. We want it to not only have access to the repository, but also to be able to quickly run various test commands. The test commands should be run inside of a docker container that has all the needed dependencies (basically a dev container). The question is, is this a typical use case for agentic workflows? If so, can you please help us get started?

(2) How should we go about having it run tests inside of our container? Are there multiple options for this, and if so, what are the pros/cons to each?

(3) We’d like it to run on self-hosted runners, are there any special considerations for that?

Thank you for your help!

[HereForTheTechNFT]

Yes, "fix this issue and open a PR" is one of the main things agentic workflows are built for. The container part needs a bit of care, because of how the agent is sandboxed.

(1) Getting started

A manually triggered fixer looks like this. It compiles with gh aw compile (I checked it with gh-aw v0.89.21):

---
on:
  workflow_dispatch:
    inputs:
      issue_number:
        description: "Issue to fix"
        required: true
        type: string
permissions:
  contents: read
  issues: read
runs-on: [self-hosted, linux, x64]
steps:
  - uses: actions/setup-node@v7
    with:
      node-version: "22"
  - run: npm ci
tools:
  github:
    toolsets: [issues]
  bash: ["npm:*", "git:*"]
network:
  allowed:
    - defaults
    - node
safe-outputs:
  create-pull-request:
    draft: true
---

Read issue #${{ github.event.inputs.issue_number }} in this repository and fix it.
Run `npm test` and keep iterating until it passes, then open a pull request
that references the issue.

Replace the Node bits with your own stack. Three details matter:

• bash only allows a small set of read-only commands by default (ls, cat, grep…), so list your test commands explicitly (make:*, pytest:*, …) or use [":*"] if you accept unrestricted shell.
• The agent has no write access. It proposes the change through safe-outputs.create-pull-request, and a separate job opens the PR (a draft by default).
• If you would rather trigger it from the issue itself, on: slash_command: (e.g. /fix in a comment) or label_command: work instead of workflow_dispatch.

(2) Running the tests "inside the dev container"

The key constraint is in the sandbox docs: the agent runs inside the firewall container (AWF), the Docker socket is hidden, and agents cannot spawn containers. So the agent cannot docker run or devcontainer exec into your image. What it can see is the runner's filesystem: every binary installed on the host, by apt-get or setup actions, is available inside the sandbox. That leaves these options:

• Install the toolchain on the runner before the agent starts. Custom steps: run outside the sandbox, after checkout, so they can install whatever your devcontainer.json / Dockerfile installs. This is the simplest, and the example above does it. The downside is keeping it in sync with the dev container.
• Use a self-hosted runner whose image already contains your dev container's toolchain. The agent then finds everything on the host. This is the closest to "tests in our container" and fits your plan for self-hosted runners.
• Dependencies that are services (database, cache): declare them under services:. The agent can only reach them with sandbox.agent.runtime: docker-sudo-iptables; the default strict runtime has no route to host services.
• Authoritative test run in the real image: since custom steps are not sandboxed, a post-steps: step can still run your suite inside the actual dev container image (docker run … your-image make test) on the agent's changes, as an extra check on top of the agent's own runs.

The frontmatter also accepts a job-level container:, and the compiler applies it to the agent job. But the agent itself runs in AWF's own container, so I would not count on it seeing your image's tools without a test run.

(3) Self-hosted runners

From the self-hosted runners page:

• Linux with Docker only (no macOS/Windows runners).
• Set runs-on in every workflow; it is not inherited through imports. network and tools can be shared that way.
• To make sure every generated job (including the framework and safe-output jobs) lands on your runners, set "require_self_hosted_runners": true in .github/workflows/aw.json.
• The firewall itself runs rootless and needs no sudo. The default Copilot CLI install script uses sudo unless run with --rootless, which you need on ARC pods without privilege escalation.
• On ARC with a Docker-in-Docker sidecar, set runner.topology: arc-dind.
• Remember the egress allowlist: package registries or internal hosts your tests need must be listed under network.allowed.

[afreer]

Thank you so much @HereForTheTechNFT for the response! It is very helpful.

Quick question on potential future support for running docker containers. It sounds like the agent runtime options are currently (docker, docker-sudo-iptables, cloud-hypervisor). It looks like in July 2026 there was a docker-sbx runtime option that did support running docker containers (see article). But on September 5, 2026 GitHub removed that in favor of cloud-hypervisor (see article).

(4) Do you know if cloud-hypervisor also already supports running docker containers? Or will it in the future? Can it be supported on self-hosted runners in the future?

[HereForTheTechNFT]

Good follow-up. Short answer: not today. I can't speak to the roadmap, though; that one is for the maintainers.

(4) Cloud Hypervisor and containers

• In the current docs, runtime: cloud-hypervisor is a preview that runs the agent in a KVM microVM on GitHub-hosted Ubuntu x86_64 runners only. Self-hosted runners are listed as incompatible (Agent Runtime Selection).
• The sandbox reference still says the Docker socket is hidden and agents cannot spawn containers, and the Cloud Hypervisor section doesn't change that (Sandbox).
• So the "agent can run docker" capability that docker-sbx had has no direct replacement right now.

Worth watching: main has an unreleased preview runtime, runtime: nvx. It runs on any Linux x86_64 host with /dev/kvm (root for AWF, cgroup v2), so it is not limited to GitHub-hosted runners. You build a workload-specific guest layer in a provisioning job before the agent starts, which gets close to "bake the dev container's toolchain into the sandbox". It explicitly rejects Docker-in-Docker, though: the agent still wouldn't start containers, the tools would live in the guest image instead. It isn't in a release yet, so treat it as something to keep an eye on rather than build on.

What works today

1. Install the dev container's dependencies on the runner in steps: before the agent runs. Host binaries are visible inside the sandbox, so the agent can run your test commands directly without Docker.
2. If the tests need backing services (database, cache…), declare them under services: and use runtime: docker-sudo-iptables, which is the profile that can reach published service ports.
3. Keep the full containerized test suite in your regular CI, which runs on the PR the agent opens.

For a definitive answer on containers inside Cloud Hypervisor, or self-hosted support later on, opening an issue on this repo is the best way to get the maintainers' view.