GitHub Actions を Hugging Face Jobs で動かす完全ガイド：CPU 30%高速化・GPU テスト 45秒

はじめに：なぜ Hugging Face Jobs なのか

GitHub Actions は標準で ubuntu-latest などのホステッドランナーを提供しており、ちょっとした CI ならすぐに始められます。しかし、本格的なプロジェクトでは以下のような限界にぶつかります。

• キュー待ちが長い：メンテナンス時間やトラフィック集中時にジョブが滞留
• GPU 非対応：オープンソースプロジェクトが GPU CI を回すには自前のランナー管理が必要
• カスタムイメージの制約：毎回 apt-get install が必要で無駄が多い

この記事では、Hugging Face Jobs を GitHub Actions のセルフホストランナーとして接続し、CPU ジョブはより高速に、GPU ジョブは低コストで実行する方法を解説します。Trackio プロジェクトで実際に採用した事例をもとに、すぐにコピペできるコードと設定を提供します。

根拠資料: Hugging Face Blog - Run GitHub Actions on Hugging Face Jobs

Step 1: Dispatcher Space の作成

Hugging Face Jobs と GitHub Actions を連携するには、Dispatcher 役の Docker Space が必要です。この Space が GitHub の workflow_job ウェブフックイベントを受け取り、HF Job を起動します。

ブラウザで設定する場合

1. huggingface/jobs-actions-dispatcher にアクセス
2. Duplicate this Space をクリック
3. Owner: 自身の HF ユーザー名または組織名
4. Name: jobs-actions-dispatcher（そのまま）
5. Hardware: cpu-upgrade を選択（本番CI用） / cpu-basic はテスト用（スリープ後のウェブフックロスに注意）
6. Space がビルドされたら、ウェブフック URL を確認：https://YOUR-HF-NAMESPACE-jobs-actions-dispatcher.hf.space/webhook

CLI で設定する場合（エージェント/自動化向け）

# 環境変数を設定
export HF_NAMESPACE=your-hf-user-or-org
export SPACE_ID="$HF_NAMESPACE/jobs-actions-dispatcher"

# Space を複製
hf repo duplicate huggingface/jobs-actions-dispatcher "$SPACE_ID" \
  --type space \
  --flavor cpu-upgrade \
  --exist-ok

# Dispatcher URL を保存
export DISPATCHER_URL="https://${HF_NAMESPACE}-jobs-actions-dispatcher.hf.space"

Step 2: GitHub App の作成とインストール

Dispatcher Space が準備できたら、GitHub App を作成してウェブフックを受信し、セルフホストランナーの登録トークンを発行できるようにします。

1. 作成した Dispatcher Space のページ（https://YOUR-HF-NAMESPACE-jobs-actions-dispatcher.hf.space）を開く
2. GitHub repo 入力欄に CI を実行したいリポジトリを入力（例：gradio-app/trackio）
3. Create GitHub App ボタンを押し、GitHub 上でアプリ名を設定
4. GitHub からアプリの credential をダウンロードするか、画面に表示された hf CLI コマンドをコピー
5. HF_TOKEN シークレットを Space に保存（Job 実行権限のあるトークンが必要）

# 例：Space にシークレットを追加（GitHub App 設定後に自動生成されるコマンド）
hf spaces secrets add "$SPACE_ID" GITHUB_APP_ID "..."
hf spaces secrets add "$SPACE_ID" GITHUB_APP_PRIVATE_KEY "..."
hf spaces secrets add "$SPACE_ID" WEBHOOK_SECRET "..."
hf spaces secrets add "$SPACE_ID" HF_TOKEN "hf_..."

6. GitHub App をリポジトリにインストール（組織設定：https://github.com/organizations/YOUR-GITHUB-ORG/settings/installations）

オプション：課金ネームスペースの変更

デフォルトでは Job は Dispatcher 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"

Step 3: GitHub Actions ワークフローの修正（たった1行！）

あとはワークフローファイルの runs-on を変えるだけです。

従来（GitHub hosted runner）

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello from GitHub"

HF Jobs に変更（CPU）

jobs:
  test:
    runs-on: hf-jobs-cpu-upgrade   # 👈 この1行だけ変更！
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello from Hugging Face Jobs"

GPU テスト（T4 small）

jobs:
  gpu-test:
    runs-on: hf-jobs-t4-small       # GPU ラベルを使用
    steps:
      - uses: actions/checkout@v4
      - run: nvidia-smi

使用可能なラベル:

• hf-jobs-cpu-upgrade
• hf-jobs-t4-small
• hf-jobs-h100 など（Hugging Face Jobs がサポートする全ての flavor）

Step 4: Docker イメージの最適化（パフォーマンス30%向上）

最初は ubuntu:22.04 のようなベースイメージを使っていましたが、毎回 Playwright や Node、ffmpeg などをインストールするのに時間がかかりました。GitHub の ubuntu-latest イメージは多くのツールがプリインストールされていますが、HF Jobs は空のイメージから始まります。

解決策: 必要なツールが既に含まれている Docker イメージを使いましょう。

CPU テスト用（Playwright イメージ）

jobs:
  test:
    runs-on: hf-jobs-cpu-upgrade
    container:
      image: mcr.microsoft.com/playwright:v1.60.0-jammy   # Node, ブラウザ, ffmpeg などを含む
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm test

GPU テスト用（CUDA イメージ）

jobs:
  gpu-test:
    runs-on: hf-jobs-t4-small
    container:
      image: nvidia/cuda:12.4.0-runtime-ubuntu22.04
    steps:
      - uses: actions/checkout@v4
      - run: python -c "import torch; print(torch.cuda.is_available())"

実績パフォーマンス（Trackio CI より）

GPU テストは 1セント未満のコストで45秒で完了しました（t4-small レート基準）。

注意点と制限

1. Dispatcher Space がスリープ中だとウェブフックが消失する可能性があります。本番では cpu-upgrade 以上のハードウェアを使用してください。
2. GitHub App の作成はブラウザベースです。完全自動化は難しいですが、CLI ガイドに従えば手動ステップを最小限にできます。
3. HF_TOKEN は Job 実行権限があるトークンでなければなりません（read-only トークンは不可）。
4. Docker イメージの選択を誤ると逆に遅くなります。 必要なツールが含まれているイメージを選びましょう。

日本開発コミュニティでの適用について

国内の ML/AI プロジェクトでは、GPU リソースの確保が常に課題です。特に個人開発者やスタートアップが GPU CI を導入するにはコスト面の壁があります。Hugging Face Jobs なら 従量課金 で GPU テストを始められるため、初期投資ゼロで GPU CI パイプラインを構築できます。

また、Qiita などでよく見られる「GitHub Actions の遅さに悩んでいる」という声に対して、この方法は実用的な代替案となります。特に hf-jobs-cpu-upgrade は、キュー待ち時間の短縮と実行時間の短縮の両方でメリットがあります。

合わせて読みたい記事

• SageMaker HyperPod Inference Operator、1クリックインストールからTerraformまで完全解説
• NVIDIA DLSS 4.5 公開：超解像度強化とダイナミックマルチフレーム生成でゲームグラフィックの新地平を拓く

まとめ：次のステップ

このガイドで GitHub Actions + Hugging Face Jobs の連携を実際に試していただけたと思います。次のステップとしては：

1. 複数の GPU flavor を試す：t4-small 以外に a10g-small、h100 など様々な GPU でテストしてみましょう。
2. ボリュームマウントを活用：CI で大規模データセットやモデルを高速にロードする必要がある場合は、HF Jobs のボリュームマウント機能を使ってみてください。
3. マルチアーキテクチャ CI の構築：CPU、GPU、ARM など複数のアーキテクチャを一つのワークフローで並列実行する戦略を検討してみましょう。

質問や問題があればコメントでお知らせください。一緒に解決していきましょう！