GitHub CI를 Hugging Face Jobs로 마이그레이션하기

jobs-actions Dispatcher

Hugging Face Jobs에서 GitHub Actions 실행

`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 레포지토리에 동일한 설정을 재현하는 방법을 단계별로 설명합니다. 만약 에이전트(agent)를 사용하신다면, 저희가 사람을 위한 브라우저 기반 지침과 함께 CLI 명령어를 제공하기 때문에 이 문서를 가리키도록 설정할 수 있습니다.

Hugging Face Jobs에 대한 간단한 소개부터 시작하겠습니다!

Hugging Face Jobs는 거의 모든 하드웨어 종류에서 Hugging Face의 서버리스 인프라를 통해 명령어 또는 스크립트를 실행할 수 있게 해줍니다. Job은 본질적으로 다음과 같습니다:

t4-small`` 또는 h200``
GPU를 예로 들어, 다음을 실행할 수 있습니다:

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 작업은 이미 명령어 기반이며, 깨끗한 환경에서 실행되고, 종종 정확히 맞는 하드웨어를 선택하는 것에서 이점을 얻습니다. ML 라이브러리의 경우 GPU 사례가 특히 설득력이 있습니다: 자체적으로 항상 켜져 있는 러너(runner)를 유지 관리할 필요 없이 실제 GPU 하드웨어에서 테스트 스위트를 실행할 수 있기 때문입니다.

핵심 단계는 GitHub Actions를 HF Jobs에 연결하는 것인데, 이는 아래에서 설명합니다.

이 설정을 위해 저희는 huggingface/jobs-actions을 만들었습니다.

, 즉 GitHub Actions 작업을 HF Job 내에서 실행되는 임시(ephemeral) 자체 호스팅 러너로 변환하는 작은 다리 역할을 합니다.

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

runs-on 레이블이 사용 가능하지 않은 경우, 예를 들어 hf-jobs-cpu-upgrade 또는 hf-jobs-t4-small과 같은 레이블을 사용하여 GitHub App을 통해 디스패처(dispatcher)로 서명된 workflow_job.queued 웹훅을 전송합니다. 이 과정에서 해당 hf-jobs-* 레이블에 맞는 단기 GitHub 러너 등록 토큰을 발급하고, 일치하는 하드웨어에서 HF Job을 시작합니다. GitHub의 관점에서는 단순히 자체 호스팅 러너일 뿐이지만, Hugging Face의 관점에서는 리포지토리의 GitHub Actions로부터 워크플로우 단계를 실행하기 위해 컨테이너를 실행하는 Job에 불과합니다.

가장 먼저 필요한 것은 디스패처입니다. 이것은 GitHub workflow_job 웹훅 이벤트를 수신하고 응답으로 HF Job을 시작하는 작은 Docker Space입니다.

이것부터 생성해야 합니다. 왜냐하면 GitHub App은 웹훅 URL이 필요하며, 그 URL은 이 Space에서 나오기 때문입니다. 이 Space는 사용자 자신의 네임스페이스 또는 쓰기 접근 권한이 있는 Hugging Face 조직(org) 아래에 있어야 합니다.

huggingface/jobs-actions-dispatcher로 이동하여 **Space 복제(Duplicate this Space)**를 클릭합니다.

사용할 설정은 다음과 같습니다:

Owner: 사용자 자신의 HF 사용자 또는 org
Name: jobs-actions-dispatcher
Hardware: cpu-upgrade

실제 CI를 위해 cpu-upgrade를 사용해야 디스패처가 GitHub 웹훅에 대해 항상 이용 가능하게 유지됩니다. cpu-basic은 테스트용으로는 괜찮고 작동할 가능성이 높지만, 비활성 상태 후 잠들 수 있습니다. 만약 이 Space가 깨어나는 동안 GitHub의 웹훅이 도착하면, 워크플로우가 영원히 대기열에 머무를 수 있습니다.

Space 생성이 완료되면 복제된 Space를 엽니다.

다음으로, 디스패처(dispatcher) Space 자체에서 GitHub 앱을 생성하고 설치해야 합니다. 이 앱은 대기열에 있는 워크플로우 작업을 수신하고 임시 자가 호스팅 러너 등록 토큰을 생성할 권한이 필요합니다.

복제된 디스패처 Space를 엽니다:

설정 양식에 CI(Continuous Integration)가 실행되어야 하는 GitHub 리포지토리의 이름을 입력합니다:

YOUR-GITHUB-ORG/YOUR-REPO

그런 다음 GitHub 앱을 생성하는 버튼을 클릭합니다. GitHub는 앱의 이름을 선택하도록 요청할 것이며, 이 이름은 사용 가능한 것이라면 무엇이든 상관없습니다. 제출한 후, 최종 화면에서 hf CLI를 사용하여 디스패처 Space에 앱 자격 증명(App credentials)을 업로드하는 방법을 정확하게 알려줍니다.

중요 참고 사항: Jobs를 실행할 권한을 가진 Hugging Face 토큰이 필요하며, 이 토큰은 개인 계정 또는 Jobs가 청구되어야 하는 조직(org)에 해당해야 합니다. 이 토큰은 디스패처 Space의 HF_TOKEN 비밀로 저장되어야 합니다.

마지막으로, Space에 입력한 것과 동일한 GitHub 리포지토리에 앱을 설치합니다. Trackio 설정에서는 gradio-app/trackio에 설치했습니다.

GitHub 앱 매니페스트(manifest) 흐름은 여전히 브라우저 기반이지만, 에이전트도 동일한 Space 기반 경로를 따를 수 있습니다:

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"

$GITHUB_REPO를 Space에 붙여넣고, GitHub 앱 생성 버튼을 클릭하고, 사용 가능한 아무 앱 이름이나 선택한 다음, 생성된 GitHub 지침을 따릅니다.

앱이 존재하는 후에는 앱 설정 페이지에서 리포지토리에 설치합니다. GitHub 조직의 경우, 설치 설정은 다음 위치에 있습니다:

이 시점에서 디스패처 Space가 구성되었어야 합니다. GitHub 앱 설정 흐름은 앱 자격 증명, 웹훅 비밀(webhook secret), 그리고 Hugging Face 토큰을 Space에 업로드하는 명령들을 생성했습니다.

기본적으로 HF Jobs는 디스패처 Space와 동일한 네임스페이스에서 실행됩니다. 다른 Hugging Face 사용자나 조직에 작업을 청구하려면, Space 변수로 HF_NAMESPACE를 설정할 수 있습니다:

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"

2단계에서 설정한 토큰은 이 네임스페이스와 일치해야 합니다.

실제 워크플로우 변경은 작습니다. 다음 대신:

runs-on: ubuntu-latest

dispatcher가 처리하는 레이블 중 하나를 사용하세요:

runs-on: hf-jobs-cpu-upgrade

GPU 테스트의 경우, GPU 레이블을 사용하세요:

runs-on: hf-jobs-t4-small

HF Jobs에서 실행하려는 모든 GitHub Action에 대해, 이 1줄 변경만 필요합니다!

CLI에서 최소한의 스모크 테스트 워크플로우를 추가하려면:

mkdir -p .github/workflows
cat > .github/workflows/hf-jobs-test.yml <<'EOF'
name: HF Jobs Test
...

CLI에서 확인하려면:

gh run list --repo YOUR-GITHUB-ORG/YOUR-REPO --limit 5
hf jobs ps --namespace "$HF_NAMESPACE"
hf spaces logs "$SPACE_ID"

일반 GitHub Action처럼 로그를 볼 수 있을 것입니다. 예를 들어, 이 Trackio PR #565에서 보듯이 말입니다.

그리고 끝입니다!

적절한 Docker 이미지 선택에 대한 참고 사항

저희의 첫 CPU 설정은 ubuntu:22.04를 사용했고, 실행할 때마다 누락된 시스템 패키지를 설치했습니다. 작동했지만, 필요한 것보다 느렸습니다. GitHub의 ubuntu-latest 이미지는 기본적으로 많은 개발자 도구를 포함하고 있지만, 순수한 Ubuntu 이미지는 그렇지 않습니다.

Trackio의 경우, UI 테스트에 Playwright 브라우저, Node, ffmpeg, sqlite, git 및 일반적인 Linux 빌드 종속성이 필요합니다. Hugging Face Jobs는 모든 Docker 이미지 사용을 지원하므로, 잘 작동한 Microsoft Playwright 이미지로 전환했습니다:

mcr.microsoft.com/playwright:v1.60.0-jammy

GPU 작업의 경우 다음을 사용했습니다:

nvidia/cuda:12.4.0-runtime-ubuntu22.04

여기에 Trackio CI에서 나온 수치들이 있습니다:

Runner setup	Runtime	Compared to GitHub average
GitHub ubuntu-latest baseline	1m40s	baseline
HF Jobs CPU, Playwright image	1m10s	-30s, about 30% faster
HF Jobs GPU, t4-small label	45s	no GitHub-hosted GPU baseline

가장 큰 개선점은 GPU CI였습니다. Trackio의 GPU 검사는 HF Jobs에서 실행되었고 45s 만에 통과했으며, 이 시간 동안 t4-small 속도로는 1센트도 채 비용이 들지 않았습니다.

CPU 결과 역시 고무적이었습니다. 적절한 이미지를 사용하자 Linux 테스트 작업 시간이 GitHub 호스팅 기준선보다 빨랐습니다. 이는 HF Jobs가 사용자 지정 이미지나 가속기가 필요한 ML 프로젝트에 특히 실용적인 CI 백엔드가 될 수 있음을 시사합니다.

로그도 또 하나의 좋은 점이었습니다. GitHub Actions 로그는 유용하지만, 웹 UI는 대용량 로그의 경우 무거울 수 있습니다. HF Jobs 로그는 CLI에서 쉽게 가져올 수 있습니다:

hf jobs logs <job_id> > logs.txt

이를 통해 로컬 도구나 코딩 에이전트로 쉽게 검사할 수 있습니다. 저희 브릿지에서는 GitHub Actions 작업 로그를 HF Job 로그로 미러링(mirroring)하여, 두 시스템 모두 실행을 디버깅하는 데 충분한 정보를 갖게 했습니다.

마지막으로, Trackio의 CI에는 필요하지 않았지만, HF Jobs는 볼륨 마운트도 지원합니다. 이는 CI의 일부로 Hugging Face에서 데이터셋이나 모델을 빠르게 로드해야 할 때 매우 유용할 수 있습니다.

이 정보가 여러분이 GitHub Actions를 실행하기 위해 HF Jobs를 시도하는 데 필요한 모든 것이기를 바랍니다!