Migrating Your GitHub CI to Hugging Face Jobs

将你的 GitHub CI 迁移到 Hugging Face Jobs

返回文章

[-1

]

[0

发布于 2026 年 6 月 9 日

GitHub 更新

点赞

8

[

• +2

Abubakar Abid

abidlabs

关注

如果你有一个 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 任务本身已经是由命令驱动的，已经在干净的环境中运行，并且通常可以从选择合适的硬件中受益。对于机器学习库来说，GPU 的情况尤其有吸引力：你可以在真实的 GPU 硬件上运行测试套件，而无需维护自己的常驻运行器。

关键的步骤是将 GitHub Actions 连接到 HF Jobs，这将在下面进行描述。

架构

为了实现这个设置，我们创建了 huggingface/jobs-actions，这是一个小型的桥梁，可以将 GitHub Actions 任务转换为在 HF Job 内运行的临时自托管运行器。

完整的流程如下：

• 一个 Pull Request 触发 GitHub Actions 工作流。

• GitHub 会排队等待任何 runs-on 标签不可用的任务，例如 hf-jobs-cpu-upgrade 或 hf-jobs-t4-small，并通过 GitHub App 向调度器发送一个签名的 workflow_job.queued webhook。

• 调度器 Space 验证 webhook，检查 hf-jobs-* 标签，生成一个短暂的 GitHub 运行器注册令牌，并在匹配的硬件上启动一个 HF Job。

• HF Job 启动一个临时的 GitHub Actions 运行器，并使用该一次性令牌将其注册到仓库中。

• GitHub 将待处理的工作流任务分配给该运行器；运行器执行 CI 任务，向 GitHub 报告状态，然后退出。

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

第一步：复制 dispatcher 空间

你首先需要的是 dispatcher。这是一个小型的 Docker 空间，用于接收 GitHub workflow_job 的 webhook 事件，并在响应中启动 HF 作业。

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

#### 网络设置

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

使用以下信息：

Owner: 你的 HF 用户或组织
Name: jobs-actions-dispatcher
Hardware: cpu-upgrade

对于真正的 CI 使用，使用 cpu-upgrade 硬件，以确保 dispatcher 对 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 设置

如果你更喜欢使用代理或 CLI 工作流来设置 dispatcher 空间：

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"

安装完成后，请从 App 设置页面将 App 安装到您的仓库中。对于 GitHub 组织，安装设置位于：

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

第 3 步：最终的 dispatcher 设置

到目前为止，dispatcher Space 应该已经配置完成。GitHub App 的设置流程会生成上传 App 凭据、webhook 密钥和 Hugging Face 令牌到 Space 的命令。

默认情况下，HF Jobs 在与 dispatcher Space 相同的命名空间下启动。如果希望将任务费用计入不同的 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 步中设置的令牌应与这个命名空间对应。

第 4 步：更改 runs-on

实际的工作流更改非常小。不再使用：

runs-on:
ubuntu-latest

而是使用 dispatcher 处理的标签之一：

runs-on:
hf-jobs-cpu-upgrade

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

runs-on:
hf-jobs-t4-small

对于任何您希望在 HF Jobs 上运行的 GitHub Action，只需要进行这一行更改即可！

第 5 步：进行测试

要从 CLI 添加一个最小的烟雾测试工作流：

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 的数据：

运行器设置

运行时间

与 GitHub 平均值相比

GitHub

ubuntu-latest

基准

1m40s

HF Jobs CPU，Playwright 镜像

1m10s

-30s

，大约快了

30%

HF Jobs GPU，

t4-small

标签

45s

没有 GitHub 主机的 GPU 基准

最大的优势是 GPU CI。Trackio 的 GPU 检查在 HF Jobs 上运行，并在 45 秒内通过，以 t4-small 的费率，持续时间花费不到一美分。

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

日志是另一个令人愉快的惊喜。GitHub Actions 的日志很有用，但当日志较大时，网页界面可能会变得很慢。HF Jobs 的日志则可以通过 CLI 轻松获取：

hf
jobs
logs <job_id> > logs.txt

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

最后，尽管 Trackio 的 CI 不需要，HF Jobs 还支持挂载卷，这在需要快速从 Hugging Face 加载数据集或模型作为 CI 的一部分时会非常有用。

希望这能为您提供所有必要的信息，尝试使用 HF Jobs 来运行您的 GitHub Actions！

本文中提到的 Spaces 1

更多来自我们博客的文章

guide

hub

optimization

五分钟了解 Hugging Face Kernel Hub

• +3

164

2025 年 6 月 12 日

llm

rl

trl

使用 Hub 桶运输万亿参数：TRL 中的 Delta 权重同步

• +4

41

2026 年 5 月 27 日

社区

编辑

预览

通过拖动到文本输入框、粘贴或

点击此处

上传图片、音频和视频。

轻点或粘贴此处上传图片

评论

· 注册或登录以发表评论