GitHub CI を Hugging Face Jobs に移行する

多くのオープンソースプロジェクトは、継続的インテグレーション（CI）に GitHub Actions のホスト型ランナーをデフォルトで使用しています。この方法は簡単ですが、速度が汎用マシンに依存し、GPU リソースを取得するのが難しいという限界があります。Trackio のようなプロジェクトでは、通常の CPU テストと CUDA ハードウェアを必要とする GPU テストの両方を実行する必要があるため、これらの制限が特に顕著です。

Hugging Face Jobs は柔軟な代替手段を提供します。CPU から H200 GPU まで様々なハードウェア構成をサポートし、Hugging Face のサーバーレスインフラ上でコマンドやスクリプトを実行できます。軽量なブリッジツール huggingface/jobs-actions を使用することで、GitHub Actions のジョブを HF Jobs にシームレスに移行できます。

アーキテクチャとワークフロー

移行の中核は、ディスパッチャー 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 ランナー登録トークンを生成して、対応するハードウェアの HF Job を起動します。HF Job は一時的な GitHub Actions ランナーを起動し、リポジトリに登録して CI ジョブを実行し、終了します。GitHub から見ると、これは単なるセルフホストランナーです。

移行手順

ステップ 1：ディスパッチャー Space の複製

まず、huggingface/jobs-actions-dispatcher から自分の名前空間に Space を複製します。スリープによる webhook 遅延を避けるため、ハードウェアは cpu-upgrade を推奨します。複製後、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 シークレット（Job 起動用の HF トークン）を設定します。最後に、GitHub でその App をリポジトリにインストールします。

ステップ 3：最終的なディスパッチャー設定

デフォルトでは、HF Job はディスパッチャー Space と同じ名前空間で課金されます。変更する場合は、HF_NAMESPACE Space 変数を設定します。

ステップ 4：runs-on ラベルの変更

GitHub Actions ワークフロー内で runs-on: ubuntu-latest を runs-on: hf-jobs-cpu-upgrade または GPU ラベル（例：hf-jobs-t4-small）に置き換えるだけで、ジョブが HF Jobs 上で実行されるようになります。

ステップ 5：テストとログ

簡単なテストワークフローを追加して動作を確認できます。HF Jobs はジョブ完了後も最大 2 時間コンテナを維持できるため、ログやアーティファクトのダウンロードが容易です。ログは HF Job ログと GitHub Actions ログの両方に書き込まれ、デバッグに便利です。また、HF Jobs はボリュームのマウントもサポートしており、Hugging Face 上のデータセットやモデルを迅速にロードできます。

実際の効果

この移行により、Trackio の CPU ジョブ時間は約 30% 短縮され、GPU テストスイートが新たに追加されました。わずかな設定変更で、Hugging Face のインフラを活用し、CI の高速化と柔軟なハードウェア選択が可能になります。