將你的 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 帶來更快的速度和更靈活的硬件選擇。