GitHub CI를 Hugging Face Jobs로 이전하기

Source: Hugging Face Blog

Back to Articles

GitHub 저장소가 있고 GitHub Actions를 사용하고 있다면, 대부분의 프로젝트가 기본으로 사용하는 GitHub‑hosted runner를 CI에 활용하고 있을 것입니다. 워크플로우에 runs-on: ubuntu-latest 를 적고, GitHub이 머신을 제공해 주면 끝이니까요.

이 기본 설정은 편리하지만 한계도 있습니다. GitHub Actions는 가끔 느리거나 유지보수로 다운될 수 있고, 제공되는 머신은 범용적이며 GPU 접근 권한은 대부분의 오픈소스 프로젝트가 바로 켤 수 있는 것이 아닙니다. Trackio 에서는 이러한 제한이 실제로 문제되었습니다. 기본 유닛 테스트와 프론트엔드 검증을 위한 신뢰성 높은 CPU CI와, 실제 CUDA 하드웨어가 필요한 테스트를 위한 GPU CI가 모두 필요했기 때문이죠.

그래서 우리는 대안을 만들었습니다: GitHub Actions가 CI를 관리하되, 작업 자체는 Hugging Face Jobs 에서 실행하도록 만든 것입니다.

그 결과, Trackio의 CI는 이제 Hugging Face Jobs에서 실행되며 실시간 로그를 스트리밍합니다. CPU 작업의 CI 시간이 약 30% 단축되고, GPU 머신에서 실행되는 새로운 테스트 스위트도 사용할 수 있게 되었습니다!

이 글에서는 여러분의 GitHub 레포지토리에서도 동일한 구성을 단계별로 구현하는 방법을 설명합니다. 에이전트를 사용한다면 이 글을 그대로 안내서로 넘겨줄 수 있습니다. 인간인 우리를 위해 브라우저 기반 안내와 CLI 기반 안내를 모두 제공하고 있으니 편한 방법을 골라 주세요.

Hugging Face Jobs란?

Hugging Face Jobs 은 거의 모든 하드웨어 사양에서 명령어나 스크립트를 실행할 수 있게 해 주는 서버리스 인프라입니다. Job 은 본질적으로 다음 요소들로 구성됩니다.

• 실행할 명령
• Docker Hub 혹은 Hugging Face Space 에서 가져온 Docker 이미지
• cpu, t4-small, h200 과 같은 하드웨어 사양
• 선택적인 환경 변수와 시크릿

예를 들어 다음과 같이 실행할 수 있습니다.

hf jobs run python:3.12 python -c "print('Hello world')"

또는

hf jobs uv run --flavor a10g-small "https://raw.githubusercontent.com/huggingface/trl/main/trl/scripts/sft.py"

이러한 특성 때문에 Jobs 은 CI 와 매우 잘 맞습니다. CI 작업은 이미 명령 중심이며, 깨끗한 환경에서 실행되고, 적절한 하드웨어를 선택하면 큰 이점을 얻을 수 있습니다. 특히 머신러닝 라이브러리의 경우, GPU 를 직접 유지하지 않아도 실제 GPU 하드웨어에서 테스트 스위트를 돌릴 수 있다는 점이 매력적이죠.

핵심 단계는 GitHub Actions 와 HF Jobs 를 연결하는 것이며, 아래에서 자세히 설명합니다.

아키텍처

이번 설정을 위해 우리는 huggingface/jobs-actions 라는 작은 브릿지를 만들었습니다. 이 브릿지는 GitHub Actions 작업을 HF Job 안에서 실행되는 일시적인 self‑hosted runner 로 변환합니다.

전체 흐름은 다음과 같습니다.

1. Pull request 가 GitHub Actions 워크플로우를 트리거합니다.
2. runs-on 라벨이 매칭되지 않을 경우 (예: hf-jobs-cpu-upgrade 혹은 hf-jobs-t4-small) GitHub 은 해당 작업을 대기열에 올리고, GitHub App 을 통해 서명된 workflow_job.queued 웹훅을 디스패처에 보냅니다.
3. 디스패처 Space 가 웹훅을 검증하고, hf-jobs-* 라벨을 확인한 뒤, 짧은 수명의 GitHub runner 등록 토큰을 발급하고, 매칭되는 하드웨어에서 HF Job 을 시작합니다.
4. HF Job 은 일시적인 GitHub Actions runner 를 부팅하고, 방금 만든 토큰으로 레포에 등록합니다.
5. GitHub 은 대기 중이던 워크플로우 작업을 해당 runner 에 할당합니다. runner 가 CI 작업을 실행하고, 상태를 GitHub 에 보고한 뒤 종료됩니다.

GitHub 입장에서는 단순히 self‑hosted runner 로 보이고, Hugging Face 입장에서는 레포의 GitHub Actions 스텝을 실행하는 컨테이너 를 띄우는 Job 으로 보입니다.

Step 1: 디스패처 Space 복제하기

먼저 필요한 것은 디스패처입니다. 이 디스패처는 GitHub workflow_job 웹훅 이벤트를 받아 HF Jobs 를 실행하는 작은 Docker Space 입니다.

GitHub App 이 웹훅 URL 을 필요로 하므로, 먼저 Space 를 복제해 URL을 확보해야 합니다. 이 Space 는 여러분 자신의 네임스페이스 혹은 쓰기 권한이 있는 Hugging Face 조직 아래에 있어야 합니다.

웹 설정

1. huggingface/jobs-actions-dispatcher 로 이동한 뒤 Duplicate this Space 를 클릭합니다.

   

2. 다음과 같이 입력합니다.

   Owner: 여러분의 HF 사용자명 또는 조직명
   Name: jobs-actions-dispatcher
   Hardware: cpu-upgrade

   실제 CI 용으로는 cpu-upgrade 를 사용해 디스패처가 GitHub 웹훅을 언제든 받을 수 있게 합니다. 테스트 용이라면 cpu-basic 도 괜찮지만, 비활성 상태가 오래 지속되면 슬립 모드에 들어가 웹훅 도착 시 워크플로우가 영원히 대기열에 머무를 수 있습니다.

3. 빌드가 완료되면 복제된 Space 를 엽니다. “Required Space secrets” 섹션이 보이겠지만 지금은 무시해도 됩니다. 메인 페이지에 GitHub App 웹훅 URL 이 표시됩니다. 형태는 다음과 같습니다.

   https://YOUR-HF-NAMESPACE-jobs-actions-dispatcher.hf.space/webhook

CLI 설정

에이전트나 CLI 로 디스패처 Space 를 만들고 싶다면 다음 명령을 사용합니다.

export HF_NAMESPACE=your-hf-user-or-org
export SPACE_ID="$HF_NAMESPACE/jobs-actions-dispatcher"

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

그 다음 URL 을 설정합니다.

export DISPATCHER_URL="https://${HF_NAMESPACE}-jobs-actions-dispatcher.hf.space"

Step 2: GitHub App 만들고 설치하기

다음으로, 디스패처 Space 내부에서 GitHub App 을 생성하고 설치합니다. 이 App 은 대기 중인 워크플로우 작업을 감시하고, 일시적인 self‑hosted runner 등록 토큰을 생성할 권한이 필요합니다.

웹 설정

복제한 디스패처 Space 로 이동합니다.

https://YOUR-HF-NAMESPACE-jobs-actions-dispatcher.hf.space

설정 폼에 CI 를 HF Jobs 로 실행하고 싶은 GitHub 레포 를 입력합니다.

YOUR-GITHUB-ORG/YOUR-REPO

그 뒤 “GitHub App 생성” 버튼을 클릭합니다. GitHub 은 App 이름을 물어보는데, 여러분 계정이나 조직에서 사용 가능한 이름이면 무엇이든 괜찮습니다. 제출 후 최종 화면에서 hf CLI 로 App 인증 정보를 디스패처 Space 에 업로드하는 방법을 알려줍니다.

중요: Jobs 를 실행할 권한이 있는 Hugging Face 토큰(https://huggingface.co/settings/tokens) 을 제공해야 합니다. 이 토큰은 개인 계정이든, 비용 청구 대상 조직이든 상관없으며, HF_TOKEN 시크릿으로 디스패처 Space 에 저장합니다.

마지막으로, 방금 만든 App 을 앞서 입력한 같은 GitHub 레포에 설치합니다. Trackio 예시에서는 gradio-app/trackio 레포에 설치했습니다.

에이전트 지원 설정

GitHub App 매니페스트 흐름은 여전히 브라우저 기반이지만, 에이전트에서도 동일한 과정을 수행할 수 있습니다.

export HF_NAMESPACE=your-hf-user-or-org
export GITHUB_REPO=YOUR-GITHUB-ORG/YOUR-REPO
open "https://${HF_NAMESPACE}-jobs-actions-dispatcher.hf.space"

Space 에 $GITHUB_REPO 를 붙여넣고, “GitHub App 생성” 버튼을 클릭한 뒤 사용 가능한 이름을 정하고, 화면에 표시되는 GitHub 지침을 따라 주세요.

App 이 생성되면, App 설정 페이지에서 레포에 설치합니다. 조직용 App 은 다음 URL 에서 설치할 수 있습니다.

https://github.com/organizations/YOUR-GITHUB-ORG/settings/installations

Step 3: 디스패처 최종 설정

이 시점에서 디스패처 Space 가 모두 구성되었습니다. GitHub App 설정 흐름에서 생성된 명령어를 실행해 App 인증 정보, 웹훅 시크릿, Hugging Face 토큰을 Space 에 업로드했을 것입니다.

기본적으로 HF Jobs 는 디스패처 Space 와 동일한 네임스페이스 아래에서 실행됩니다. 필요에 따라 HF_ 로 시작하는 환경 변수를 지정해 다른 네임스페이스나 조직으로 작업을 위임할 수도 있습니다. (이후 내용은 원문이 잘려 있어 여기까지 번역합니다.)