depot-github-runners

Depot GitHub Actions 运行器

Depot 提供托管的、临时的、单租户 GitHub Actions 运行器。可直接替代 GitHub 托管的运行器——只需更改 runs-on 标签，其他一切保持不变。

要求： 仓库必须由 GitHub 组织拥有（而非个人账户）。

Depot 运行器不是 Depot CI

Depot 运行器仍以 GitHub Actions 为引擎，因此工作流位于 .github/workflows/ 中，检查仍来自 github-actions 应用。 Depot CI 是另一个产品：它读取 .depot/workflows/，而 GitHub Actions 会忽略该目录，并从 depot-code-access 应用发布自己的检查运行记录。 请使用 depot-ci 技能来处理该产品。

其 references/posthog-check-run-semantics.md 比较了各引擎针对被跳过、空矩阵或 continue-on-error 作业所报告的内容，以及 GitHub 和 Trunk 合并队列如何评定这些结论。

设置

1. Depot 仪表板 → GitHub Actions → Connect to GitHub → Install Depot GitHub App
2. 对于公开仓库：GitHub 组织设置 → Actions → Runner groups → Default → "Allow public repositories"
3. 更新工作流文件中的 runs-on

面向多组织用户的组织上下文检查

如果用户属于多个组织，且预期的仓库/设置/运行器不可见，请先验证 Depot 组织上下文：

depot org show              # Current org ID
depot org list              # Orgs the user belongs to
depot org switch <org-id>   # Optional: set default org

对于支持该选项的命令，传入 --org <org-id> 以指定工作流/仓库所在的组织。

运行器标签

使用单个标签。格式：depot-{os}-{version}[-{arch}][-{size}]

Ubuntu（x86，AMD）

标签	CPU	RAM	磁盘	美元/分钟	分钟乘数
depot-ubuntu-24.04	2	8 GB	100 GB	$0.004	1x
depot-ubuntu-24.04-4	4	16 GB	130 GB	$0.008	2x
depot-ubuntu-24.04-8	8	32 GB	150 GB	$0.016	4x
depot-ubuntu-24.04-16	16	64 GB	180 GB	$0.032	8x
depot-ubuntu-24.04-32	32	128 GB	200 GB	$0.064	16x
depot-ubuntu-24.04-64	64	256 GB	250 GB	$0.128	32x

分钟乘数是计费驱动因素：计费分钟数 = 经过分钟数 × 乘数，因此更大的运行器会更快地消耗你包含的分钟数。

Ubuntu 22.04 也可用：depot-ubuntu-22.04、depot-ubuntu-22.04-4 等。

Ubuntu（ARM — Graviton4）

与 Intel 相同的规格和价格。添加 -arm 后缀： depot-ubuntu-24.04-arm、depot-ubuntu-24.04-arm-4、depot-ubuntu-24.04-arm-8 等。

Windows Server

标签	CPU	RAM	美元/分钟	分钟乘数
depot-windows-2025	2	8 GB	$0.008	2x
depot-windows-2025-4	4	16 GB	$0.016	4x
depot-windows-2025-8 到 -64	8–64	32–256 GB	$0.032–$0.256	8x–64x

Windows Server 2022 也可用：depot-windows-2022 等。 Windows 限制： 不支持 Hyper-V（AWS EC2 限制），因此需要它的 Docker 工作负载不太可能运行。

macOS（macOS 14/15 上的 Apple M2，macOS 26 上的 M4）

标签	CPU	RAM	磁盘	美元/分钟
depot-macos-26	8	24 GB	400 GB	$0.08
depot-macos-15 / depot-macos-latest	8	24 GB	400 GB	$0.08
depot-macos-14	8	24 GB	400 GB	$0.08

macOS 并非完全弹性——采用固定资源池，FIFO 排队。

别名

depot-ubuntu-latest → Ubuntu 24.04，depot-windows-latest → Windows 2025，depot-macos-latest → macOS 15

迁移示例

jobs:
  build:
    # Before:
    # runs-on: ubuntu-latest
    # After:
    runs-on: depot-ubuntu-24.04-4
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

常见错误

# ❌ WRONG — multiple labels cause stability issues
runs-on: [self-hosted, depot-ubuntu-24.04]

# ✅ CORRECT — always use a single Depot runner label
runs-on: depot-ubuntu-24.04-4

缓存

使用 GitHub Actions 缓存 API 的操作会自动使用 Depot Cache —— 无需更改配置。这包括 actions/cache、actions/setup-node、actions/setup-python、actions/setup-java，以及任何使用 @actions/cache 的操作。

预配置的构建工具缓存（在 Depot runner 上零配置）：

工具	预配置内容
Turborepo	已设置 TURBO_API 环境变量 —— 只需运行 turbo build
Bazel	已预填充 ~/.bazelrc —— 只需运行 bazel build //...
sccache	已设置 SCCACHE_WEBDAV_ENDPOINT —— 使用 RUSTC_WRAPPER: 'sccache'
Maven	已预填充 settings.xml（缓存 id depot-cache）
Pants	已预配置 pants.toml —— 只需运行 pants package ::
moonrepo	已设置环境变量 —— 只需运行 moon run build

缓存行为：以仓库为范围，无分支隔离，加密，吞吐量最高 1000 MiB/s，保留期可配置（7/14/30 天）。

要禁用自动缓存：组织设置 → 关闭“Allow Actions jobs to automatically connect to Depot Cache”。

Dagger 集成

已弃用： Depot GitHub Actions Runner 上的 Dagger Engine 支持正在弃用，将在未来的更新中移除。不要为新工作流推荐此集成。

runs-on: depot-ubuntu-latest,dagger=0.18.4

启动带有持久 NVMe 缓存的专用 Dagger Engine 虚拟机。已预装 Dagger CLI。额外收费 $0.04/分钟。

出口流量过滤（仅 Linux）

在组织设置 → GitHub Actions Runners → Egress Rules 中配置。将默认规则设为 Allow 或 Deny，然后为 IP、CIDR 或主机名添加特定的允许/拒绝规则。拒绝规则优先于允许规则。环回流量（127.0.0.1、::1）始终允许，Depot 会自动将 depot.dev 域名、GitHub Actions 服务 IP 和 AWS 服务 IP 加入允许列表。规则中的主机名会被解析并固定到 /etc/hosts。启用出口流量过滤后，使用 depot build 进行容器构建仍可正常工作 —— Depot 会在分配 BuildKit 机器 IP 时将其添加到允许列表。macOS 或 Windows 上不支持。与 Tailscale 不兼容。

使用 Tailscale 访问私有端点

当作业需要访问私有服务（内部 API、数据库、私有子网）而不使用静态 IP 允许列表时，请使用 Tailscale。

在 Depot 上的工作原理：

• Depot GitHub Actions runner 在作业开始时以临时节点身份加入你的 tailnet。
• 访问由你的 Tailscale ACL 控制（推荐标签：tag:depot-runner）。
• 仅将 runner 连接到私有端点无需更改工作流 YAML。

设置：

1. 在 Tailscale ACL 中，在 tagOwners 下创建 runner 标签（例如 tag:depot-runner）。
2. 创建一个具有 Keys > Auth Keys 写入范围的 Tailscale OAuth 客户端，并选择该标签。
3. 在 Depot 组织设置中，打开 Tailscale 设置，并使用 OAuth 客户端 ID/密钥进行连接。
4. 添加 ACL，允许 tag:depot-runner 访问目标主机/子网。

ACL 示例：

{
  "acls": [
    {
      "action": "accept",
      "src": ["tag:depot-runner"],
      "dst": ["database-hostname"]
    }
  ]
}

{
  "acls": [
    {
      "action": "accept",
      "src": ["tag:depot-runner"],
      "dst": ["192.0.2.0/24:*"]
    }
  ]
}

参考文档：

• https://depot.dev/docs/github-actions/how-to-guides/access-private-resources
• https://depot.dev/docs/integrations/tailscale

Dependabot

在 GitHub 组织设置中启用“Dependabot on self-hosted runners”。作业会自动在 depot-ubuntu-latest 上运行。

重要： Dependabot 不支持 OIDC。请改用 token: 输入和 DEPOT_TOKEN 密钥。

SSH 调试

steps:
  - uses: actions/checkout@v4
  - uses: mxschmitt/action-tmate@v3
  - run: npm test

故障排查

错误	修复
"No space left on device"	操作系统使用约 70 GB 磁盘；升级到更大的 runner 或在 workflow 中清理磁盘
"Failed to open the device 'kvm'" / "Could not access KVM kernel module"	Runner 不提供 /dev/kvm；将 KVM/QEMU/Android-emulator 任务迁移到 Depot CI，其中嵌套虚拟化默认启用
"Lost communication with server"	检查 status.depot.dev；检查组织使用上限
"Operation was canceled"	手动取消、并发取消进行中或 OOM — 检查仪表板中的内存
"Unable to get ACTIONS_ID_TOKEN_REQUEST_URL"	Dependabot 不支持 OIDC — 使用 DEPOT_TOKEN 密钥
Workflows not starting	验证单个 runner 标签；检查 runner 组是否允许该仓库；验证 Depot GitHub App 权限
Stuck workflows	通过 GitHub API 强制取消：POST /repos/{owner}/{repo}/actions/runs/{id}/force-cancel