GitHub Actions

GitHub Actions

GitHub Actions로 GitHub 저장소를 Hugging Face Hub에 자동으로 동기화할 수 있어요. 공식 huggingface/hub-sync 액션은 Models, Datasets, Spaces 동기화를 지원해요.

[!TIP] 저장하거나 교체할 HF_TOKEN 시크릿 없이 출판하려면 Trusted Publishers를 참고하세요. 이것은 각 실행 시작 시 GitHub Actions의 내장 OIDC 토큰을 단기 수명·저장소 범위의 Hub 토큰으로 교환해요.

출처: 문서

본문

설정

  1. 대상 저장소에 write 권한이 있는 Hugging Face 액세스 토큰을 만든다. 더 나은 보안을 위해, 동기화할 저장소에만 범위가 지정된 fine-grained 토큰을 사용하세요.
  2. 저장소 설정에서 HF_TOKEN이라는 GitHub 시크릿으로 토큰을 추가한다.
  3. 저장소에 워크플로 파일(예: .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/repo-name
          hf_token: ${{ secrets.HF_TOKEN }}

기본적으로 이건 Space로 동기화해요. 모델이나 데이터셋을 동기화하려면 repo_type 파라미터를 설정하세요:

      - uses: huggingface/[email protected]
        with:
          github_repo_id: ${{ github.repository }}
          huggingface_repo_id: username/my-dataset
          hf_token: ${{ secrets.HF_TOKEN }}
          repo_type: dataset

파라미터

파라미터 필수 기본값 설명
github_repo_id 예 — GitHub 저장소 (${{ github.repository }} 사용)
huggingface_repo_id 예 — Hub의 대상 저장소 (username/repo-name)
hf_token 예 — Hugging Face 액세스 토큰
repo_type 아니요 space space, model, dataset
space_sdk 아니요 gradio gradio, streamlit, docker, static
private 아니요 false 저장소를 private으로 만들지 여부
subdirectory 아니요 . 특정 서브디렉터리 동기화 (모노레포에 유용)

이 액션은 hf CLI로 파일을 Hub에 미러링해요 — git-to-git 동기화가 아니에요. .github/와 .git/ 디렉터리를 자동으로 제외하고 삭제를 미러링해요(GitHub에서 제거된 파일은 Hub에서도 제거돼요).

빌드 단계, 커스텀 업로드 로직 같은 더 복잡한 워크플로는 워크플로에서 직접 hf CLI를 설치해 사용할 수 있어요.

Spaces 관련 지침(파일 크기 제한, LFS 처리)은 GitHub Actions로 Spaces 관리하기를 참고하세요.

더 알아보기 (Learn more)