GitHub Actions를 사용하여 Spaces 관리

공식 huggingface/hub-sync GitHub Action을 사용하여 Space를 GitHub 저장소와 동기화할 수 있습니다.

hub-sync은 Models와 Datasets에도 사용할 수 있습니다. 일반적인 사용법은 GitHub Actions를 참고하세요.

설정

1. Hugging Face 액세스 토큰을 사용하여 HF_TOKEN이라는 GitHub secret을 생성합니다.
2. 리포지토리에 워크플로 파일(예: .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/hub-sync@v0.3.0
        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 repos create + hf upload)를 사용하여 파일을 Hub에 미러링합니다. git-to-git 동기화가 아니며, 파일 내용을 업로드하고 .github/ 및 .git/ 디렉터리를 자동으로 제외합니다. GitHub 저장소에서 삭제된 파일은 Hub에서도 함께 삭제됩니다.

더 복잡한 워크플로(예: 빌드 단계, 사용자 정의 로직)의 경우, 워크플로에서 hf CLI를 직접 설치하여 사용할 수 있습니다.

파일 크기 고려 사항

이 액션은 hf upload를 사용하여 파일 내용을 업로드하므로, Hub를 위해 Git LFS나 git-xet를 설정할 필요가 없습니다. 대용량 파일은 자동으로 Xet에 저장됩니다. GitHub 저장소가 Git LFS로 파일을 저장하는 경우(GitHub는 100MB를 초과하는 파일에 대해 이를 요구합니다), actions/checkout 단계에서 lfs: true를 설정하여 액션이 LFS 포인터 대신 파일을 업로드하도록 하세요.

대안: 수동 git push

파일 미러링 대신 직접적인 git-to-git 동기화를 선호하는 경우, Space의 git remote에 직접 push할 수 있습니다. git push를 사용할 때 10MB를 초과하는 파일은 git-xet(권장) 또는 Git LFS로 추적해야 합니다:

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:$HF_TOKEN@huggingface.co/spaces/HF_USERNAME/SPACE_NAME main

HF_USERNAME를 사용자 이름으로, SPACE_NAME을 Space 이름으로 교체하세요.