将GitHub CI迁移到Hugging Face Jobs

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

默认方案很方便，但也有限制。GitHub Actions可能较慢或因维护暂停；托管机器是通用配置，大多数开源项目也无法直接启用GPU访问。对Trackio而言，这些限制开始产生影响。我们既需要可靠的CPU CI执行基本单元测试和前端检查，也需要GPU CI，让测试运行在真正的CUDA硬件上。 （Trackio）

于是我们构建了替代方案：仍由GitHub Actions管理CI，但在Hugging Face Jobs上运行任务。 （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基本上包含： （Hugging Face Jobs）

• 要运行的命令。
• 来自Docker Hub或Hugging Face Space的Docker镜像。
• 硬件规格，例如CPU，或t4-small、h200 GPU。
• 可选的环境变量与secret。

例如，可以运行：

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内部的临时自托管运行器。 （huggingface/jobs-actions）

完整流程如下：

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组织中。

网页配置

打开huggingface/jobs-actions-dispatcher，点击Duplicate this Space。 （huggingface/jobs-actions-dispatcher）

使用以下配置：

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

实际CI应使用cpu-upgrade，确保调度器一直可以接收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工作流配置调度器Space：

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需要监听排队工作流任务，以及创建临时自托管运行器注册令牌的权限。

网页配置

打开复制的调度器Space：

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

在配置表单中输入需要在HF Jobs上运行CI的GitHub仓库：

YOUR-GITHUB-ORG/YOUR-REPO

然后点击创建GitHub App的按钮。GitHub会要求选择App名称；只要在你的GitHub账户或组织中可用，任何名称都可以。提交后，最后一页会准确告诉你如何用hf CLI把App凭据上传到调度器Space。

重要提示：需要提供具有启动Jobs权限的Hugging Face令牌，对应个人账户，或承担Jobs费用的组织。该令牌应保存为调度器Space中的HF_TOKEN secret。 （Hugging Face token）

最后，把App安装到你在Space中输入的同一GitHub仓库。Trackio配置中，我们安装到gradio-app/trackio。

智能体辅助配置

GitHub App manifest流程仍然基于浏览器，但智能体可以沿用相同的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按钮，选择任意可用名称，并遵循生成的GitHub说明。

App创建后，从App设置页安装到仓库。GitHub组织的安装设置位于：

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

步骤3：调度器最后设置

此时调度器Space应已配置好。GitHub App配置流程生成了把App凭据、webhook secret及Hugging Face令牌上传到Space的命令。

默认情况下，HF Jobs在与调度器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

改用调度器处理的一个标签：

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。 （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镜像，效果很好： （Docker镜像）

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上运行，45秒通过；以该时长的t4-small费率计算，费用不到一美分。

CPU结果也令人鼓舞。采用合适镜像后，Linux测试任务比GitHub托管基线更快。这说明HF Jobs可以成为实用CI后端，尤其适合需要定制镜像或加速器的机器学习项目。

日志是另一项惊喜。GitHub Actions日志很有用，但大日志的网页界面可能较重。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！