Running AI agents in GitHub Actions with Docker Sandboxes

在 GitHub Actions 中使用 Docker 沙箱运行 AI 代理 | Docker

在 GitHub Actions 中使用 Docker 沙箱运行 AI 代理

发布于 2026 年 8 月 21 日

Oleg Selajev

2026 年 7 月，GitHub 代理工作流新增了 Docker 沙箱作为支持的代理运行时环境。这意味着在您的 CI 环境中，AI 编码代理可以对其环境拥有广泛控制权限，包括运行 Docker 容器，而环境本身则通过微虚拟机实现隔离，具备网络策略和密钥注入功能，符合当前 AI 隔离的最佳实践标准。

代理隔离至关重要，因为实用的编码代理不仅限于阅读仓库并建议补丁。它们会安装工具、运行任意 shell 命令、执行项目代码、启动数据库，偶尔还会发现“清理”这个词令人意外的新含义。这些能力使代理变得有用，但直接访问 CI 运行器会让每个错误都产生更大的影响范围。

现在通过 sbx 集成，代理的边界变为一个可丢弃的环境，在内部拥有较大自由度，对外部的访问则受到严格限制。

我准备了一个小型示例来演示实际效果。代理在 GitHub 主机的 Ubuntu 运行器上运行，进入 Docker 沙箱（sbx），使用 Testcontainers 运行包含 PostgreSQL 的 Java 集成测试套件，发现一个故意植入的漏洞，修复后并创建一个草稿拉取请求。GitHub 代理工作流原生支持该集成，因此无需任何自定义配置即可使用。

什么是 GitHub 代理工作流？

GitHub Actions 仍然是 CI 系统。它负责安排任务、提供 Ubuntu 运行器、管理权限和密钥，并记录结果。

GitHub 代理工作流（通常简写为 gh-aw）是一个开源的 GitHub CLI 扩展和编译器。您通过 Markdown 文件描述代理工作流，该文件将 YAML 前置信息中的执行配置与代理任务正文结合。运行 gh aw compile 会将源文件转换为带有 .lock.yml 后缀的常规 GitHub Actions 工作流。

两者的关系如下：

Markdown 工作流
    |
    | gh aw compile
    v
生成的 GitHub Actions .lock.yml
    |
    | 在 ubuntu-24.04 上运行
    v
Docker 沙箱微虚拟机
    |
    v
Copilot 代理及其工具

docker-sbx 属于 gh-aw 的代理运行时配置。runs-on 字段仍然选择 ubuntu-24.04，生成的文件是标准的 GitHub Actions 工作流。它会安装沙箱工具、进行身份验证、检查运行器、在沙箱中启动代理，并在完成后清理所有内容。

该集成已合并到 gh-aw 并随 0.82.9 版本发布。

在 GitHub Actions 中配置 sbx

以下是示例中 sandbox-explorer.md 的配置：

---
name: "Docker 沙箱示例：探索性测试"

on:
  workflow_dispatch:

runs-on: ubuntu-24.04

permissions:
  contents: read
  copilot-requests: write

engine: copilot

network:
  allowed:
    - defaults
    - github
    - containers
    - java

sandbox:
  agent:
    id: awf
    runtime: docker-sbx
    sudo: true

tools:
  edit:
  bash: [":*"]

safe-outputs:
  create-pull-request:
    title-prefix: "[docker-sbx 示例] "
    draft: true
    protected-files: blocked
    allowed-files:
      - "src/**"
---

在 sandbox.agent 下方的三行代码选择了 Docker 沙箱运行时。在沙箱内部，代理拥有构建应用和启动测试基础设施所需的 sudo 权限和无限制的 shell 访问权限。

沙箱外部的工作流暴露的攻击面要小得多。其网络块白名单仅包含该任务所需的访问目标，而代理的 GitHub 令牌可以读取仓库内容并发送请求至 Copilot。拉取请求的创建发生在独立的 safe-output 任务中，其补丁仅可能包含 src/** 路径下的文件。

CI 代理应获得的自主权取决于任务类型。对于这个任务，这种分层设计非常有效：沙箱内提供广泛的 shell 访问权限，沙箱外限制网络和仓库的访问范围，并生成需要人工审核的草稿 PR。

隔离边界是微型虚拟机

虽然通常认为“Docker”意味着单个应用容器，但此架构实际上使用微型虚拟机作为主要隔离边界。

通过 sbx ，每个沙箱都是一个独立环境，拥有自己的内核、文件系统和网络栈。最重要的是，它运行着私有的 Docker 守护进程。这意味着代理在虚拟机内获得完整的 root 权限，却永远不会控制宿主机的 Docker 守护进程。两者之间唯一的连接桥梁是仓库的显式共享工作区。

拥有私有守护进程对集成测试具有革命性意义。在此演示中，应用以与开发者在本地机器上完全相同的方式运行 Testcontainers。最终结构如下：

GitHub Actions runner
└── Docker Sandbox microVM
    ├── GitHub Agentic Workflows agent
    └── Private Docker daemon
        ├── Maven / Java 21 container
        └── PostgreSQL Testcontainers container

为保持环境整洁，测试启动器在固定容器内运行 Maven，并通过沙箱的 Docker 套接字进行通信：

docker run --rm \
  --add-host=host.testcontainers.internal:host-gateway \
  -e TESTCONTAINERS_HOST_OVERRIDE=host.testcontainers.internal \
  -v "$PWD:/workspace" \
  -w /workspace \
  -v /var/run/docker.sock:/var/run/docker.sock \
  maven:3.9.9-eclipse-temurin-21@sha256:3a4ab3276a087bf276f79cae96b1af04f53731bec53fb2e651aca79e4b10211e \
  mvn --batch-mode "$@" test

Testcontainers 随后使用该套接字启动 PostgreSQL 数据库。虽然看起来层级很多——容器中运行构建任务并启动另一个容器，所有操作都在 CI runner 的微型虚拟机内进行——但每一层都服务于特定目的，确保代理既保持隔离又具备完整能力。

为代理设置值得发现的缺陷

该示例是一个小型 Java 21 注册服务。其需求说明指出电子邮件地址应不区分大小写。初始实现将地址原样存储，并依赖 PostgreSQL 的区分大小写的唯一性约束。现有的 Testcontainers 集成测试可以捕获完全重复的地址，但对大小写差异的情况保持沉默。

工作流的 Markdown 部分要求代理检查需求说明和代码，运行基准测试套件，并添加一个测试用例来验证仅大小写不同的两个地址。如果不变量失败，代理应做出最小的源码修正。在修改应用之前，它会记录 uname、Docker 版本、Docker 信息以及一个微型 Alpine 容器运行记录，在工作流日志中留下具体证据，标明工作执行位置。

任务本身是 YAML 文件中 frontmatter 下方的普通 Markdown。对我们而言重要的部分（在记录环境用于调试的一些命令之后）是：

作为该仓库的有限探索性测试员进行操作。
... 

然后：
1. 阅读 `REQUIREMENTS.md` 以及相关的源代码和测试文件。
2. 不做任何修改，直接运行 `./scripts/test-in-docker.sh`。
3. 添加一个 PostgreSQL Testcontainers 测试，检查两个仅在字母大小写上不同的地址的注册情况。
4. 运行聚焦测试并解释观察到的行为。
5. 如果实现违反了文档中声明的不变量，请在 `src/` 下进行最小的修复。
6. 再次运行完整的测试套件。
7. 创建一个包含回归测试和修复的草稿拉取请求。

提示级别的防护措施用于建议正确的行为：

不要修改依赖清单、工作流文件、脚本、文档或生成的文件。不要弱化或删除现有测试。在拉取请求描述中包含运行的命令及其结果。

实际运行当然遵循了这一路径：基准测试通过后，新的大小写变体测试失败，显示：

预期: <false> 但实际为: <true>

代理在插入之前对电子邮件进行了规范化处理，重新运行完整套件后获得了两个通过的集成测试。

日志报告了 Docker 客户端和服务器版本 29.7.1 以及默认上下文。这正是当前 sbx 默认沙箱模板中正确的 Docker 版本。这是沙箱的私有守护进程，也是 Testcontainers 库用于集成测试启动 PostgreSQL 的那个。

完整的流程在 GitHub 主机的 ubuntu-24.04 运行器上通过。运行耗时 11 分钟 16 秒。

随后的 safe-output 任务打开了一包含恰好两个 src/** 下文件的草稿 PR：回归测试和一行规范化修复。工作流配置、脚本、依赖项和文档均在其允许的补丁范围内之外。

生成的草稿拉取请求严格保持在声明的源代码限定边界内。

自行运行工作流

首先安装 gh-aw：

gh extension install github/gh-aw

编译后的 Docker 沙箱运行时需要 Docker 凭据来认证并拉取其沙箱模板。在示例仓库的 Settings > Secrets and variables > Actions 下添加 DOCKER_USERNAME 和 DOCKER_PAT，或让 GitHub CLI 提示输入这两个值：

gh secret set DOCKER_USERNAME
gh secret set DOCKER_PAT

仓库的 Copilot 许可和 copilot-requests: write 权限足以成功运行示例。没有该许可的仓库可以使用 gh-aw 文档中说明的受支持 COPILOT_GITHUB_TOKEN 秘密。

同时在仓库的 Actions 设置中启用 Allow GitHub Actions 创建和批准拉取请求。然后编译 Markdown 源代码并提交源代码和生成的工作流：

gh aw compile sandbox-explorer

git add .github/workflows/sandbox-explorer.md \
  .github/workflows/sandbox-explorer.lock.yml
git commit -m "Compile Docker Sandboxes sample workflow"
git push

.lock.yml 是生成的代码。更改应保留在 Markdown 源代码中，随后再次编译。

最后启动工作流并观察执行：

gh aw run sandbox-explorer
gh run watch

该示例可在 GitHub 托管的 ubuntu-24.04 运行器上正常运行。若使用自托管 Linux 运行器，则需要具备支持 KVM 的环境，并满足 Docker 沙箱所需的 Docker 及系统访问权限。

在笔记本电脑上尝试 sbx

在 CI 环境中隔离代理的功能非常强大，但理解 Docker 沙箱最简单的方式是将它应用于本地项目的代理。按照您平台的 Docker 沙箱设置指南进行操作，登录后进入某个仓库并运行已安装的代理：

sbx login
cd ~/my-project

sbx run <claude|codex|opencode>

为其分配需要真实工具的任务，例如运行测试、构建镜像或启动 Testcontainers 依赖项。当工作负载是实际开发流程时，sbx 更容易评估和理解。

如果您的实验扩展到组织范围的代理部署，下一步应了解 Docker AI 治理功能。该功能可为沙箱网络、文件系统和 MCP 访问应用组织及团队策略，并在审计日志中记录策略决策。这些记录可帮助识别来源客户端（包括 sbx ）和机器主机名，使相同的策略和审计模型能够轻松覆盖团队笔记本电脑和 CI 运行器。

AI 代理

Docker 沙箱

工程

目录

相关文章

• 2026年8月18日 17,600 次操作：代理安全是系统问题 OpenAI/Hugging Face 事件暴露了 AI 代理安全的新挑战。17,600 次攻击操作展示了为何 AI 代理安全不能依赖人工审查。探索实现快速约束、监控和治理代理所需的控制措施。Mark Cavage 立即阅读

• 2026年8月21日 使用 Docker 沙箱在 GitHub Actions 中运行 AI 代理 了解如何通过 Docker 沙箱在 GitHub Actions 中运行 AI 代理。查看隔离代理如何运行 Testcontainers 测试、修复代码并创建草稿拉取请求。Oleg Selajev 立即阅读

• 2026年8月20日 Docker 认证发布者应用现已支持自助服务 现可通过 Docker Hub 直接申请成为 Docker 认证发布者（DVP）。让您的认证内容优先展示给寻找可信选项的开发者。Julia Wilson 和 Dan Stelzer 立即阅读