GitHub Actions, Hugging Face Jobs로 GPU CI까지 5분 만에 연결하는 완벽 가이드

들어가며: GitHub Actions, 이제 GPU도 필요하다

GitHub Actions는 기본적으로 ubuntu-latest 같은 hosted runner를 제공합니다. 설정이 간편하다는 장점이 있지만, 실제 프로젝트를 운영하다 보면 이런 한계가 드러납니다.

• 느린 큐: 유지보수 시간이나 트래픽이 몰릴 때 작업이 밀려서 오래 기다려야 함
• GPU 미지원: 오픈소스 프로젝트가 GPU CI를 돌리려면 자체 러너를 직접 관리해야 함
• 커스텀 이미지 제약: 미리 설치된 도구 외에는 매번 apt-get install을 해야 함

이 글에서는 Hugging Face Jobs를 GitHub Actions의 self-hosted runner로 연결하여, 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은 테스트용 (sleep 후 깨어나는 동안 웹훅 손실 가능)
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을 생성하여 웹훅을 수신하고 self-hosted runner 토큰을 발급받을 수 있게 합니다.

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   # 👈 이 한 줄만 변경!
    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가 sleep 상태면 웹훅이 유실될 수 있습니다. cpu-upgrade 이상의 하드웨어를 사용하세요.
2. GitHub App 생성은 브라우저 기반입니다. 완전 자동화는 어렵지만, CLI 가이드를 따라 수동 단계를 최소화할 수 있습니다.
3. HF_TOKEN은 반드시 Job 실행 권한이 있는 토큰이어야 합니다. (read-only 토큰은 안 됩니다)
4. Docker 이미지를 잘못 선택하면 성능이 더 나빠질 수 있습니다. 반드시 필요한 도구가 포함된 이미지를 선택하세요.

한국 개발 생태계에서의 적용 맥락

국내에서는 GPU 자원이 제한된 환경에서 AI/ML 프로젝트를 진행하는 경우가 많습니다. 특히 오픈소스 프로젝트나 스타트업에서 GPU CI를 구성하려면 비용 부담이 큰데, Hugging Face Jobs를 활용하면 사용한 만큼만 지불하는 방식으로 GPU 테스트를 도입할 수 있습니다.

또한, SI/금융권 프로젝트에서는 보안 정책상 GitHub Actions hosted runner를 직접 사용하지 못하는 경우가 있습니다. 이때 Hugging Face Jobs를 self-hosted runner처럼 활용하면, 외부 인프라를 통제된 환경에서 사용할 수 있습니다.

함께 보면 좋은 글

• 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 등 여러 아키텍처를 하나의 워크플로우에서 병렬로 실행하는 전략을 구성해보세요.

궁금한 점이나 이슈가 있다면 댓글로 남겨주세요. 함께 해결해 나가면 좋겠습니다! 😊