docs/github-to-huggingface-sync-plan.md

GitHub to Hugging Face Space Sync Plan

Objective

Use GitHub as the canonical source repository and Hugging Face Space as the deployment target for the Gradio app.

The desired workflow:

push to GitHub main
-> GitHub Actions runs
-> repository contents sync to Hugging Face Space
-> Hugging Face Space rebuilds and restarts the Gradio app

Recommended Repository Roles

• GitHub repository: source of truth for development, docs, tests, issues, PRs, and implementation history.
• Hugging Face Space repository: deployment target for the public Gradio demo.

Operational Sync Decision

Use token-based Hugging Face CLI sync as the preferred manual deployment path.

Reason:

• SSH push depends on the right key being loaded into ssh-agent.
• Passphrase-protected SSH keys can fail across new terminal sessions.
• During implementation, token-based hf upload successfully synced the Space without requiring SSH passphrase prompts.
• GitHub remains the canonical code repository; the Space is a deployment target.

Preferred manual sync command:

hf upload build-small-hackathon/vibe2blog . . \
  --repo-type space \
  --exclude '.git' \
  --exclude '.git/*' \
  --exclude '.venv' \
  --exclude '.venv/*' \
  --exclude '__pycache__' \
  --exclude '__pycache__/*' \
  --exclude '*/__pycache__/*' \
  --exclude '.pytest_cache' \
  --exclude '.pytest_cache/*' \
  --exclude '.DS_Store' \
  --commit-message "chore: sync Vibe2Blog Space"

Use SSH only as a fallback/debug path. If SSH is used, first verify:

ssh -T git@hf.co
git push --dry-run hf main

If SSH returns an authentication error, use hf upload instead of spending time debugging ssh-agent.

Prerequisites

1. A GitHub repository for this project.
2. A Hugging Face account.
3. A Hugging Face Space created with SDK Gradio.
4. A Hugging Face access token with write access to the target Space.
5. The target Hugging Face Space repo id, for example:

<hf-username>/vibe2blog

or, for an organization:

<hf-org>/vibe2blog

For hackathon submission, prefer the official hackathon Hugging Face organization as the Space owner when eligible/available. Use a personal Space only as a fallback or temporary deployment target.

Expected App Files

Once implementation starts, the repo should include the standard Space runtime files:

app.py
requirements.txt
README.md
src/
tests/
docs/

For a Gradio Space, Hugging Face uses the Space repository README.md metadata block to configure the Space. If the GitHub README is also synced to the Space, make sure it includes valid Space metadata once deployment begins.

Example Space metadata:

---
title: Vibe2Blog
emoji: 📝
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.0.0
app_file: app.py
pinned: false
license: gpl-3.0
---

Note: update sdk_version to the actual Gradio version used by the project.

GitHub Secret

Create this repository secret in GitHub:

HF_TOKEN

The token should come from Hugging Face user settings and must have write permission for the target Space.

Workflow File

Create this file:

.github/workflows/sync-to-huggingface.yml

Planned workflow:

name: Sync to Hugging Face Space

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  sync:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Sync to Hugging Face Hub
        uses: huggingface/hub-sync@v0.1.0
        with:
          github_repo_id: ${{ github.repository }}
          huggingface_repo_id: <hf-username-or-org>/vibe2blog
          repo_type: space
          hf_token: ${{ secrets.HF_TOKEN }}

Replace:

<hf-username-or-org>/vibe2blog

with the real Space repo id.

Branch Strategy

Recommended:

• main: production branch that syncs to Hugging Face Space.
• feature branches: development branches that do not auto-deploy.

Optional future improvement:

• Add a separate staging Space for preview deployments.
• Sync main to production Space and develop to staging Space.

Sync Timing

Recommended setup:

• Enable automatic sync on every push to main.
• Enable workflow_dispatch so deployment can be triggered manually from GitHub Actions.

This keeps normal deployment simple while still allowing manual retry when Hugging Face build behavior needs a nudge.

Manual Sync Procedure

For day-to-day hackathon work:

1. Commit locally with a Codex co-author trailer.
2. Push to GitHub origin/main.
3. Sync to the Space using token-based hf upload.
4. Verify the Space rebuilds.

Commands:

git status --short
git push origin main
hf upload build-small-hackathon/vibe2blog . . \
  --repo-type space \
  --exclude '.git' \
  --exclude '.git/*' \
  --exclude '.venv' \
  --exclude '.venv/*' \
  --exclude '__pycache__' \
  --exclude '__pycache__/*' \
  --exclude '*/__pycache__/*' \
  --exclude '.pytest_cache' \
  --exclude '.pytest_cache/*' \
  --exclude '.DS_Store' \
  --commit-message "chore: sync Vibe2Blog Space"

If it is important for hf/main to share the exact same Git commit history as GitHub, push by Git HTTPS only after confirming credentials are available:

git push --force-with-lease https://huggingface.co/spaces/build-small-hackathon/vibe2blog main

This is optional for normal Space deployment. Content sync is enough for the Space to rebuild.

Validation Steps

After adding the workflow:

1. Push a commit to main.
2. Open GitHub Actions.
3. Confirm Sync to Hugging Face Space starts.
4. Confirm the job finishes successfully.
5. Open the Hugging Face Space repository.
6. Confirm the latest commit or files appear in the Space.
7. Open the Space App tab.
8. Confirm the Gradio app rebuilds and launches.
9. Run the sample-data smoke test.
10. Confirm Markdown generation and download work.

Failure Modes

Missing or Invalid HF Token

Symptom:

• GitHub Action fails during sync.
• Manual hf upload fails with authentication or permission errors.

Fix:

• Regenerate HF_TOKEN.
• Ensure token has write access.
• Ensure the secret name is exactly HF_TOKEN.
• Run hf auth whoami to confirm the local CLI is authenticated.

SSH Agent or Passphrase Problems

Symptom:

• git push hf main fails with an authentication error.
• ssh-add must be rerun in each session.
• ssh -T git@hf.co connects as anonymous or the push is rejected.

Fix:

• Prefer token-based hf upload.
• Only debug SSH if exact Git history on the Space remote is required.
• Ensure the SSH public key is registered in Hugging Face settings.
• Ensure ~/.ssh/config has a host entry for hf.co pointing to the correct identity file.

Wrong Space Repo ID

Symptom:

• Sync fails or pushes to the wrong target.

Fix:

• Verify the Hugging Face Space URL.
• Use the repo id in the form <owner>/<space-name>.

Space Builds but App Does Not Start

Symptom:

• Sync succeeds, but the Space shows an app/runtime error.

Fix:

• Check Space logs.
• Verify app.py exists.
• Verify requirements.txt includes required dependencies.
• Verify README metadata has sdk: gradio and app_file: app.py.

README Metadata Conflict

Symptom:

• GitHub README looks fine, but Space config is wrong or missing.

Fix:

• Add the Hugging Face metadata block to the top of README.md once deployment begins.
• Keep public project documentation below the metadata block.

Acceptance Criteria

• GitHub is the canonical development repository.
• Pushing to main updates GitHub, and token-based sync updates the Hugging Face Space.
• The Space rebuilds after sync.
• The deployed app can run the sample Vibe2Blog flow.
• The workflow can also be triggered manually.

Open Decisions

• Final Hugging Face Space repo id.
• Whether the Space must be created under the official hackathon organization or can start as a personal Space.
• Whether to use a personal account or hackathon organization Space.
• Final Gradio SDK version.
• Whether to add a staging Space.
• Whether the GitHub README should include Hugging Face Space metadata from day one or only after app implementation starts.