mcpField
D
depot-github-runners

depot-github-runners

github.com/depot云与 DevOps2275 次安装6 天前更新
代码仓库

关于 depot-github-runners

Depot GitHub Runners 为 GitHub Actions 工作流提供托管的临时单租户运行器，面向希望替换 GitHub 托管运行器的团队。通过修改 `runs-on` 标签即可接入，并提供自动缓存和作业资源分析。

主要功能

  1. 01托管临时单租户运行器
  2. 02支持 Ubuntu、Windows 和 macOS
  3. 03通过 Depot Cache 自动缓存
  4. 04提供作业资源指标与分析
  5. 05通过 Tailscale 访问私有端点
  6. 06配置 Linux 出站流量规则

适用场景

  1. 01将 GitHub Actions 作业迁移到 Depot
  2. 02运行需要较大资源的 CI 作业
  3. 03通过缓存加速重复构建
  4. 04让工作流连接私有服务

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/depot/skills --skill depot-github-runners

安装后在 Claude Code 中输入/depot-github-runners确认已加载。

附带文件agents/openai.yaml

详细介绍

Depot GitHub Actions 运行器

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

**要求：**仓库必须归属于 GitHub 组织（而非个人账户）。

设置

  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内存磁盘$/分钟分钟倍率
depot-ubuntu-24.0428 GB100 GB$0.0061x
depot-ubuntu-24.04-4416 GB130 GB$0.0122x
depot-ubuntu-24.04-8832 GB150 GB$0.0244x
depot-ubuntu-24.04-161664 GB180 GB$0.0488x
depot-ubuntu-24.04-3232128 GB200 GB$0.09616x
depot-ubuntu-24.04-6464256 GB250 GB$0.19232x

分钟倍率是计费依据：计费分钟数 = 经过的分钟数 × 倍率，因此更大的运行器会更快耗尽包含的分钟数。

也提供 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内存$/分钟分钟倍率
depot-windows-202528 GB$0.0082x
depot-windows-2025-4416 GB$0.0164x
depot-windows-2025-8 至 -648–6432–256 GB$0.032–$0.2568x–64x

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

macOS（macOS 14/15 上的 Apple M2、macOS 26 上的 M4）
标签CPU内存磁盘$/分钟
depot-macos-26 / depot-macos-latest824 GB400 GB$0.08
depot-macos-15824 GB400 GB$0.08
depot-macos-14824 GB400 GB$0.08

macOS 并非完全弹性扩缩——使用固定资源池，并按先进先出顺序排队。

别名

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

迁移示例

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 运行器上无需配置）：

工具预配置内容
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
Xcode 26+在 Depot macOS 运行器上，编译缓存会自动使用 Depot Cache

缓存行为：按仓库范围生效，不隔离分支，经过加密，吞吐量最高可达 1000 MiB/s，保留期限可配置（7/14/30 天）。

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

对于 Xcode，只有在作业未提供自己的配置文件时，运行器才会设置 XCODE_XCCONFIG_FILE。设置 DEPOT_XCODE_CACHE_ENABLED: '0' 即可为某个作业或工作流选择退出。在构建后添加 depot/xcode-compilation-cache-summary@v1，即可报告缓存统计信息。Xcode 编译缓存不支持在本地工作站上使用。有关构建设置和故障排除，请参阅 https://depot.dev/docs/cache/integrations/xcode。

Dagger 集成

**已弃用：**Depot GitHub Actions 运行器上的 Dagger Engine 支持正在弃用，并将在未来的更新中移除。请勿在新工作流中推荐此集成。

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

启动一个专用的 Dagger Engine VM，并配备持久化 NVMe 缓存。已预装 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 运行器会在作业开始时作为临时节点加入你的 tailnet。
  • 访问权限由你的 Tailscale ACL 控制（建议使用标签：tag:depot-runner）。
  • 仅为让运行器连接到私有端点，无需更改工作流 YAML。

设置：

  1. 在 Tailscale ACL 中，于 tagOwners 下创建一个运行器标签（例如 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:*"]
    }
  ]
}

参考文档：

Dependabot

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

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

检查作业和资源使用情况

使用 depot jobs 查看 Depot 上的 GitHub Actions 作业。Depot CI 作业则使用 depot ci 命令。

depot jobs --repo owner/repo --conclusion failure --output json
depot jobs <github-job-id> --repo owner/repo --output json
depot jobs metrics <github-job-id> --repo owner/repo --output json
depot jobs analytics --repo owner/repo --job test --output json

这四种形式都接受 --org、--token 和 --output，其值可以是 auto、table 或 json。管道输出默认使用 JSON，且不会提示登录。检查单个作业或其指标时，必须且只能指定一个 --repo。

列表支持可重复指定 --repo、--status、--conclusion 和 --runner-label，以及 --query。状态值为 queued、waiting、running 和 finished；结论值为 success、failure、cancelled、skipped 和 neutral。分析筛选条件包括 --repo、--workflow、--workflow-path、--job 和 --runner-label。

列表和分析结果每次只返回一页。使用 --page-size（1–250，默认值为 50）和返回的 nextPageToken 配合 --page-token；筛选条件和时间范围须保持不变。两者默认查询最近 30 天。使用 RFC 3339 时间戳同时指定 --start 和 --end，时间范围必须大于零且不超过 90 天。

单个作业的指标包括 CPU 和内存采样数据、统计信息及可用性。JSON 格式的利用率为 0 到 1 之间的分数；表格中显示百分比。缺失的测量数据会保持缺失，而不会显示为零。执行时间范围最多为七天，最多返回 5,000 个采样数据；统计信息使用降采样前观测到的全部采样数据。聚合分析可能比作业完成时间延迟 15 分钟。步骤耗时不可用。

SSH 调试

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

故障排除

错误解决方法
"No space left on device"操作系统使用约 70 GB 磁盘；升级到更大的运行器，或在工作流中清理磁盘
"Failed to open the device 'kvm'" / "Could not access KVM kernel module"运行器不提供 /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 密钥
工作流未启动确认只使用一个运行器标签；检查运行器组是否允许该仓库；确认 Depot GitHub App 权限
工作流卡住通过 GitHub API 强制取消：POST /repos/{owner}/{repo}/actions/runs/{id}/force-cancel

评论

支持 Markdown