GitHub Actions

You can use GitHub Actions to automatically sync your GitHub repository to the Hugging Face Hub. The official huggingface/hub-sync action supports syncing Models, Datasets, and Spaces.

Setup

1. Create a Hugging Face access token with write permission to the target repo. For better security, use a fine-grained token scoped to only the repository you’re syncing to.
2. Add the token as a GitHub secret called HF_TOKEN in your repository settings.
3. Add a workflow file (e.g. .github/workflows/sync-to-hub.yml) to your repository.

Basic usage

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.1.0
        with:
          github_repo_id: ${{ github.repository }}
          huggingface_repo_id: username/repo-name
          hf_token: ${{ secrets.HF_TOKEN }}

By default, this syncs to a Space. To sync a model or dataset, set the repo_type parameter:

      - uses: huggingface/hub-sync@v0.1.0
        with:
          github_repo_id: ${{ github.repository }}
          huggingface_repo_id: username/my-dataset
          hf_token: ${{ secrets.HF_TOKEN }}
          repo_type: dataset

Parameters

The action mirrors your files to the Hub using the hf CLI — it is not a git-to-git sync. It automatically excludes .github/ and .git/ directories and mirrors deletions (files removed from GitHub will be removed from the Hub).

For more complex workflows (e.g. build steps, custom upload logic), you can install and use the hf CLI directly in your workflow instead.

For Spaces-specific guidance (file size limits, LFS handling), see Managing Spaces with GitHub Actions.