将你的 GitHub CI 迁移到 Hugging Face Jobs

许多开源项目默认使用 GitHub Actions 的托管 runner 进行持续集成（CI），这种方式简单但存在局限：运行速度受限于通用机器，且 GPU 资源难以获取。对于像 Trackio 这样需要同时进行常规 CPU 测试和 CUDA 硬件的 GPU 测试的项目，这些限制尤为突出。

Hugging Face Jobs 提供了一种灵活的替代方案：它允许用户在 Hugging Face 的无服务器基础设施上运行命令或脚本，并支持从 CPU 到 H200 GPU 等多种硬件配置。通过一个轻量级的桥接工具 huggingface/jobs-actions，可以将 GitHub Actions 作业无缝迁移到 HF Jobs 上执行。

架构与工作流程

迁移的核心架构包括一个调度器 Space（dispatcher Space）和一个 GitHub App。当 PR 触发 GitHub Actions 工作流时，如果作业的 runs-on 标签匹配 hf-jobs-* 模式（如 hf-jobs-cpu-upgrade 或 hf-jobs-t4-small），GitHub 会发送 workflow_job.queued webhook 到调度器 Space。调度器验证 webhook 后，生成一个临时的 GitHub runner 注册令牌，并启动一个对应硬件的 HF Job。HF Job 启动一个短暂的 GitHub Actions runner，注册到仓库，然后执行 CI 作业，最后退出。从 GitHub 的角度看，这只是一个自托管 runner。

迁移步骤

步骤 1：复制调度器 Space

首先，从 huggingface/jobs-actions-dispatcher 复制一个 Space 到自己的命名空间下。建议使用 cpu-upgrade 硬件以避免睡眠导致的 webhook 延迟。复制后，Space 的页面会提供一个 webhook URL，形如 https://YOUR-HF-NAMESPACE-jobs-actions-dispatcher.hf.space/webhook。

步骤 2：创建并安装 GitHub App

在调度器 Space 的页面中，输入你的 GitHub 仓库（如 YOUR-GITHUB-ORG/YOUR-REPO），点击创建 GitHub App。按照生成的说明，使用 hf CLI 上传 App 凭据，并设置 HF_TOKEN secret（用于启动 Job 的 HF 令牌）。最后，在 GitHub 上安装该 App 到你的仓库。

步骤 3：最终调度器设置

默认情况下，HF Job 会在与调度器 Space 相同的命名空间下计费。如需更改，可设置 HF_NAMESPACE Space 变量。

步骤 4：修改 runs-on 标签

只需在 GitHub Actions workflow 中将 runs-on: ubuntu-latest 替换为 runs-on: hf-jobs-cpu-upgrade 或 GPU 标签（如 hf-jobs-t4-small），即可将作业切换到 HF Jobs 上运行。

步骤 5：测试与日志

可以添加一个简单的测试 workflow 来验证。HF Jobs 支持在作业完成后保持容器运行最多 2 小时，便于下载日志和工件。日志会同时写入 HF Job 日志和 GitHub Actions 日志，方便调试。此外，HF Jobs 还支持挂载卷，可快速加载 Hugging Face 上的数据集或模型。

实际效果

通过迁移，Trackio 的 CPU 作业时间缩短了约 30%，并新增了 GPU 测试套件。整个设置仅需少量配置，就能充分利用 Hugging Face 的基础设施，为 CI 带来更快的速度和更灵活的硬件选择。