GitHub Actions로 Spaces 관리하기

공식 huggingface/hub-sync GitHub Action을 사용하면 Space를 GitHub 저장소와 동기화 상태로 유지할 수 있어요.

출처: 문서

본문

hub-sync는 Models와 Datasets에서도 동작해요. 일반적인 사용법은 GitHub Actions를 참고하세요.

설정

Hugging Face 액세스 토큰을 담은 HF_TOKEN이라는 이름의 GitHub 시크릿을 만드세요.
저장소에 워크플로 파일(예: .github/workflows/sync-to-hub.yml)을 추가하세요.

name: Sync to Hugging Face Hub
on:
  push:
    branches: [main]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: huggingface/[email protected]
        with:
          github_repo_id: ${{ github.repository }}
          huggingface_repo_id: username/my-space
          hf_token: ${{ secrets.HF_TOKEN }}

Space SDK는 space_sdk로 설정할 수 있어요(기본값은 gradio). 모든 파라미터를 살펴보세요.

동작 방식

이 액션은 hf CLI(hf repo create + hf upload)를 사용해 파일을 Hub로 미러링해요. git-to-git 동기화가 아니라 파일 내용을 업로드하는 방식이고, .github/와 .git/ 디렉토리는 자동으로 제외해요. GitHub 저장소에서 제거된 파일은 Hub에서도 제거돼요.

더 복잡한 워크플로(예: 빌드 단계, 사용자 지정 로직)가 필요하면 워크플로 안에서 hf CLI를 직접 설치해 사용할 수 있어요.

파일 크기 고려사항

10MB보다 큰 파일은 Spaces가 Git-LFS를 요구해요. 동기화 전에 GitHub 저장소의 대용량 파일이 LFS로 추적되고 있는지 확인하세요.

대안: 수동 git push

파일 미러링 대신 git-to-git 동기화를 직접 하고 싶다면 Space의 git 원격으로 바로 푸시할 수 있어요.

name: Sync to Hugging Face hub
on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  sync-to-hub:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
          lfs: true
      - name: Push to hub
        env:
          HF_TOKEN: ${{ secrets.HF_TOKEN }}
        run: git push https://HF_USERNAME:[email protected]/spaces/HF_USERNAME/SPACE_NAME main

HF_USERNAME을 사용자 이름으로, SPACE_NAME을 Space 이름으로 바꾸세요.

더 알아보기 (Learn more)

hub-sync는 파일 내용을 업로드하는 미러링 방식이라 .github/·.git/을 자동 제외해요. 10MB 초과 파일은 미리 Git-LFS로 추적해 두는 게 핵심이에요. git-to-git 동기화가 필요하면 대안 섹션의 직접 push 방식을 쓰면 돼요.