如何把 GitHub CI 迁移到 Hugging Face Jobs

如果你有一个 GitHub 仓库并且启用了 GitHub Actions，你很可能使用 GitHub 托管的运行器来运行 CI。这是许多项目的默认选择，因为它很简单：添加一个工作流，编写 runs-on: ubuntu-latest，GitHub 就会给你一台机器。

这种默认方式很方便，但也有其局限性。GitHub Actions 可能速度慢或因维护而停机，托管的机器是通用的，而且大多数开源项目无法直接获得 GPU 访问权限。对于 Trackio 来说，这些限制开始变得重要。我们既需要可靠的 CPU CI 来运行基本的单元测试和前端检查，也需要 GPU CI 来运行需要在真实 CUDA 硬件上运行的测试。

因此，我们构建了一个替代方案：让 GitHub Actions 继续负责 CI，但在 Hugging Face Jobs 上运行作业。

结果：Trackio 的 CI 现在运行在 Hugging Face Jobs 上，并实时流式传输日志，将我们 CPU 作业的 CI 时间缩短了约 30%，并启用了一套全新的、在 GPU 机器上运行的测试套件！

在本文中，我们将逐步解释如何为你的 GitHub 仓库重新创建相同的设置。如果你在使用智能体，可以将它指向本文，因为我们除了提供面向人类的基于浏览器的说明外，还提供了 CLI 指令。

让我们先快速介绍一下 Hugging Face Jobs！

什么是 Hugging Face Jobs？

Hugging Face Jobs 让你可以在 Hugging Face 的无服务器基础设施上运行命令或脚本，几乎可以使用任何硬件配置。一个 Job 本质上包含：

• 要运行的命令
• 一个 Docker 镜像，来自 Docker Hub 或 Hugging Face Space
• 一个硬件配置，例如 CPU 或 t4-small 或 h200 GPU
• 可选的环境变量和密钥

例如，你可以运行：

hf jobs run python:3.12 python -c "print('Hello world')"

或

hf jobs uv run --flavor a10g-small "https://raw.githubusercontent.com/huggingface/trl/main/trl/scripts/sft.py" 

这使得 Jobs 天然适合 CI。CI 作业已经是命令驱动的，已经在干净的环境中运行，并且通常受益于选择完全合适的硬件。对于 ML 库来说，GPU 场景尤其有吸引力：你可以在真实的 GPU 硬件上运行测试套件，而无需维护自己的常开运行器。

关键步骤是将 GitHub Actions 连接到 HF Jobs，我们将在下面描述。

架构

对于这个设置，我们创建了 huggingface/jobs-actions，一个小型桥接器，它将 GitHub Actions 作业转换为在 HF Job 内运行的临时自托管运行器。

完整流程如下：

1. 一个拉取请求触发 GitHub Actions 工作流。
2. GitHub 将任何 runs-on 标签不可用的作业排队，例如 hf-jobs-cpu-upgrade 或 hf-jobs-t4-small，并通过 GitHub App 向调度器发送签名的 workflow_job.queued webhook。
3. 调度器 Space 验证 webhook，检查 hf-jobs-* 标签，生成一个短期的 GitHub 运行器注册令牌，并在匹配的硬件上启动一个 HF Job。
4. HF Job 启动一个临时的 GitHub Actions 运行器，并使用该一次性令牌将其注册到仓库。
5. GitHub 将待处理的工作流作业分配给该运行器；运行器执行 CI 作业，将状态报告回 GitHub，然后退出。

从 GitHub 的角度来看，这只是一个自托管运行器。从 Hugging Face 的角度来看，这只是一个 Job，它启动一个容器来运行仓库 GitHub Actions 中的工作流步骤。

第 1 步：复制调度器 Space

你首先需要的是调度器。这是一个小型 Docker Space，它接收 GitHub workflow_job webhook 事件并相应地启动 HF Jobs。

先创建这个，因为 GitHub App 需要一个 webhook URL，而该 URL 来自这个 Space。这个 Space 应该位于你自己的命名空间下，或者位于你有写入权限的 Hugging Face 组织下。

Web 设置

前往 huggingface/jobs-actions-dispatcher 并点击 Duplicate this Space。

使用：

Owner: your HF user or org
Name: jobs-actions-dispatcher
Hardware: cpu-upgrade

使用 cpu-upgrade 用于真实 CI，这样调度器就能保持可用以接收 GitHub webhook。cpu-basic 用于测试没问题，而且大概率也能用，但它在不活动后可能会休眠；如果 GitHub 的 webhook 在它唤醒期间到达，工作流可能会永远停留在排队状态。

构建完成后，打开复制出来的 Space。你会看到一个写着“Required Space secrets”的部分，现在可以先忽略它。落地页应该会显示你在下一步需要的 GitHub App webhook URL。它看起来会像这样：

https://YOUR-HF-NAMESPACE-jobs-actions-dispatcher.hf.space/webhook

CLI 设置

如果你更愿意用 agent 来设置调度器 Space，或者使用 CLI 工作流：

export HF_NAMESPACE=your-hf-user-or-org
export SPACE_ID="$HF_NAMESPACE/jobs-actions-dispatcher"

hf repo duplicate huggingface/jobs-actions-dispatcher "$SPACE_ID" \
  --type space \
  --flavor cpu-upgrade \
  --exist-ok

然后设置：

export DISPATCHER_URL="https://${HF_NAMESPACE}-jobs-actions-dispatcher.hf.space"

第 2 步：创建并安装 GitHub App

接下来，从调度器 Space 本身创建并安装 GitHub App。这个 App 需要权限来监听排队的 workflow 作业，并创建临时的自托管 runner 注册令牌。

Web 设置

打开你复制出来的调度器 Space：

https://YOUR-HF-NAMESPACE-jobs-actions-dispatcher.hf.space

在设置表单中，输入其 CI 应在 HF Jobs 上运行的 GitHub 仓库：

YOUR-GITHUB-ORG/YOUR-REPO

然后点击按钮创建 GitHub App。GitHub 会要求你为这个 App 选择一个名称；名称可以是任何内容，只要在你的 GitHub 账户或组织中可用即可。提交后，最终屏幕会确切地告诉你如何使用 hf CLI 将 App 凭据上传到调度器 Space。

重要提示：你需要提供一个 Hugging Face token，它要有启动 Jobs 的权限，并对应你的个人账户或应为其支付 Jobs 费用的组织。这个 token 应保存为调度器 Space 中的 HF_TOKEN secret。

最后，你将在 Space 中输入的同一个 GitHub 仓库上安装这个 App。在 Trackio 设置中，我们把它安装在了 gradio-app/trackio 上。

Agent 辅助设置

GitHub App manifest 流程仍然是基于浏览器的，但 agent 可以遵循同样的由 Space 驱动的路径：

export HF_NAMESPACE=your-hf-user-or-org
export GITHUB_REPO=YOUR-GITHUB-ORG/YOUR-REPO
open "https://${HF_NAMESPACE}-jobs-actions-dispatcher.hf.space"

将 $GITHUB_REPO 粘贴到 Space 中，点击 GitHub App 创建按钮，选择任意可用的 App 名称，然后按照生成的 GitHub 说明操作。

App 创建完成后，从 App 设置页面将其安装到你的仓库上。对于 GitHub 组织，安装设置位于：

https://github.com/organizations/YOUR-GITHUB-ORG/settings/installations

第 3 步：最终调度器设置

此时，调度器 Space 应该已经配置好了。GitHub App 设置流程生成了将 App 凭据、webhook secret 和 Hugging Face token 上传到该 Space 的命令。

默认情况下，HF Jobs 会在与调度器 Space 相同的命名空间下启动。可选地，如果你想把 jobs 计费到另一个 Hugging Face 用户或组织，可以将 HF_NAMESPACE 设置为 Space 变量：

export SPACE_ID=YOUR-HF-NAMESPACE/jobs-actions-dispatcher
hf spaces variables add "$SPACE_ID" -e HF_NAMESPACE=your-billing-namespace
hf spaces restart "$SPACE_ID"

你在第 2 步中设置的 token 应对应这个命名空间。

第 4 步：更改 runs-on

实际的 workflow 更改很小。不要使用：

runs-on: ubuntu-latest

而是使用调度器处理的标签之一：

runs-on: hf-jobs-cpu-upgrade

对于 GPU 测试，使用 GPU 标签：

runs-on: hf-jobs-t4-small

对于任何你想在 HF Jobs 上运行的 GitHub Action，只需这 1 行更改！

第 5 步：测试一下

从 CLI 添加一个最小冒烟测试 workflow：

mkdir -p .github/workflows
cat > .github/workflows/hf-jobs-test.yml <<'EOF'
name: HF Jobs Test

on:
  pull_request:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  test:
    runs-on: hf-jobs-cpu-upgrade
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello from Hugging Face Jobs"
EOF

git add .github/workflows/hf-jobs-test.yml
git commit -m "Run CI on Hugging Face Jobs"
git push

从 CLI 验证：

gh run list --repo YOUR-GITHUB-ORG/YOUR-REPO --limit 5
hf jobs ps --namespace "$HF_NAMESPACE"
hf spaces logs "$SPACE_ID"

你应该能够像普通 GitHub Action 一样看到日志——例如，在这个 Trackio PR #565 中。

就是这样！

关于选择正确 Docker 镜像的说明

我们最初的 CPU 配置使用了 ubuntu:22.04，并在每次运行时安装缺失的系统包。这样做可行，但比实际需要的速度慢。GitHub 的 ubuntu-latest 镜像默认包含大量开发者工具；而裸 Ubuntu 镜像则没有。

对于 Trackio，UI 测试需要 Playwright 浏览器、Node、ffmpeg、sqlite、git 以及常规的 Linux 构建依赖。Hugging Face Jobs 支持使用任何 Docker 镜像，因此我们切换到了 Microsoft Playwright 镜像，效果很好：

mcr.microsoft.com/playwright:v1.60.0-jammy

对于 GPU 任务，我们使用了：

nvidia/cuda:12.4.0-runtime-ubuntu22.04

结果

以下是 Trackio CI 的数据：

最大的收益是 GPU CI。Trackio GPU 检查在 HF Jobs 上运行，并在 45s 内通过，按该时长的 t4-small 费率计算，成本不到一美分。

CPU 的结果也令人鼓舞。使用正确的镜像后，Linux 测试任务比 GitHub 托管的基线更快。这表明 HF Jobs 可以成为一个实用的 CI 后端，尤其是对于需要自定义镜像或加速器的 ML 项目。

日志是另一个令人愉快的惊喜。GitHub Actions 日志很有用，但对于大型日志，其 Web UI 可能很笨重。HF Jobs 日志很容易从 CLI 获取：

hf jobs logs <job_id> > logs.txt

这使得它们易于用本地工具或编码代理进行检查。在我们的桥接中，我们还将 GitHub Actions 任务日志镜像到 HF Job 日志中，因此任一系统都有足够的信息来调试运行。

最后，尽管 Trackio 的 CI 不需要它们，HF Jobs 也支持挂载卷，如果你需要在 CI 过程中快速从 Hugging Face 加载数据集或模型，这会非常有帮助。

希望这能为你提供尝试使用 HF Jobs 运行 GitHub Actions 所需的一切！