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