# GitHub Actions Auto-Sync Setup Guide

This guide walks you through setting up automatic synchronization from your GitHub repository to your Hugging Face Space using GitHub Actions.

## ✅ What's Already Done

- [x] Created GitHub repository directory: `F:\github-fleetmind-team`
- [x] Copied all HF Space code to GitHub repo
- [x] Created GitHub Actions workflows:
  - `.github/workflows/sync-to-huggingface.yml` - Auto-sync on push
  - `.github/workflows/check-file-size.yml` - Check file sizes on PRs

## 🎯 What You Need to Do Now

### STEP 3: Get Your Hugging Face Token

1. **Go to:** https://huggingface.co/settings/tokens

2. **Click:** "Create new token"

3. **Fill in:**
   - Name: `GitHub Actions Sync`
   - Type: **Write** (important!)
   - Scope: Select **all** or at least:
     - ✅ Write access to repos
     - ✅ Write access to spaces

4. **Click:** "Generate token"

5. **COPY THE TOKEN** (you won't see it again!)
   - It looks like: `hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`

---

### STEP 4: Push Code to GitHub

Open PowerShell or Command Prompt:

```bash
# Navigate to the GitHub repo
cd F:\github-fleetmind-team

# Add all files
git add .

# Commit
git commit -m "Initial commit: FleetMind MCP with GitHub Actions sync"

# Add GitHub remote (REPLACE YOUR-USERNAME with your actual GitHub username)
git remote add origin https://github.com/YOUR-USERNAME/fleetmind-mcp.git

# Push to GitHub
git push -u origin main
```

**If you get an error about 'main' branch:**
```bash
# Rename branch to main
git branch -M main

# Push again
git push -u origin main
```

---

### STEP 5: Add HF_TOKEN as GitHub Secret

1. **Go to your GitHub repo:**
   - URL: `https://github.com/YOUR-USERNAME/fleetmind-mcp`

2. **Click:** Settings (top right of repo page)

3. **In left sidebar, click:**
   - Secrets and variables → Actions

4. **Click:** "New repository secret"

5. **Fill in:**
   - Name: `HF_TOKEN`
   - Secret: Paste the Hugging Face token you copied in Step 3

6. **Click:** "Add secret"

---

### STEP 6: Add HF Space as Git Remote (Optional but Recommended)

This allows you to manually push to HF Space if needed:

```bash
cd F:\github-fleetmind-team

# Add HF Space as a remote
git remote add space https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai

# Verify remotes
git remote -v
```

You should see:
```
origin  https://github.com/YOUR-USERNAME/fleetmind-mcp.git (fetch)
origin  https://github.com/YOUR-USERNAME/fleetmind-mcp.git (push)
space   https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai (fetch)
space   https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai (push)
```

---

### STEP 7: Test the Auto-Sync

Let's make a test change to verify everything works:

```bash
cd F:\github-fleetmind-team

# Make a small change to README
echo "\n\n## 🤖 Auto-Synced with GitHub Actions" >> README.md

# Commit the change
git add README.md
git commit -m "Test: GitHub Actions auto-sync"

# Push to GitHub
git push origin main
```

**What happens next:**

1. ✅ Code pushes to GitHub
2. ✅ GitHub Actions triggers automatically
3. ✅ Workflow runs and pushes to HF Space
4. ✅ HF Space rebuilds with new code

**Check the progress:**

1. **On GitHub:**
   - Go to: `https://github.com/YOUR-USERNAME/fleetmind-mcp/actions`
   - You'll see "Sync to Hugging Face Space" workflow running
   - Wait for green checkmark ✅

2. **On Hugging Face:**
   - Go to: https://huggingface.co/spaces/MCP-1st-Birthday/fleetmind-dispatch-ai
   - Check the "Files" tab - you should see the new commit
   - Space will rebuild automatically

---

## 🎉 Success! Your Setup is Complete

From now on:

### **Team Members Workflow:**

```bash
# 1. Clone the GitHub repo (one time)
git clone https://github.com/YOUR-USERNAME/fleetmind-mcp.git
cd fleetmind-mcp

# 2. Make changes
# ... edit files ...

# 3. Commit and push to GitHub
git add .
git commit -m "Add new feature"
git push origin main

# 4. GitHub Actions automatically syncs to HF Space
# ✨ DONE! Nothing else needed!
```

### **What GitHub Actions Does:**

Every time someone pushes to the `main` branch on GitHub:

1. ✅ GitHub Actions workflow starts
2. ✅ Checks out the code
3. ✅ Pushes to HF Space using your HF_TOKEN
4. ✅ HF Space rebuilds automatically
5. ✅ Your app goes live with the new changes

---

## 📋 Adding Team Members

### On GitHub (Full Access):

1. Go to: `https://github.com/YOUR-USERNAME/fleetmind-mcp/settings/access`
2. Click "Add people"
3. Enter their GitHub username
4. Select role: **Write** (they can push directly)
5. Click "Add"

### On Hugging Face (Documentation Only):

Team members don't need HF access! The GitHub Actions bot handles all HF Space updates using your HF_TOKEN.

Just make sure they're listed in the README:
- Edit `README.md` lines 29-42
- Add their real names and HF usernames
- Commit and push

---

## 🔧 Troubleshooting

### ❌ "Error: Process completed with exit code 128"

**Solution:** Check that HF_TOKEN is correctly set in GitHub Secrets
- Go to: `https://github.com/YOUR-USERNAME/fleetmind-mcp/settings/secrets/actions`
- Verify `HF_TOKEN` exists
- If not, add it (see Step 5)

### ❌ "Error: failed to push some refs"

**Solution:** HF Space has newer commits
```bash
# Pull from HF Space first
git pull space main --allow-unrelated-histories

# Then push again
git push origin main
```

### ❌ GitHub Actions workflow doesn't run

**Solution:** Check that workflow file is in correct location
- Must be: `.github/workflows/sync-to-huggingface.yml`
- Check GitHub repo → Actions tab
- Click "I understand my workflows, go ahead and enable them"

### ❌ Files larger than 10MB

**Solution:** Use Git LFS
```bash
# Install Git LFS
git lfs install

# Track large files
git lfs track "*.psd"  # Example: Photoshop files
git lfs track "*.pkl"  # Example: Model files

# Commit .gitattributes
git add .gitattributes
git commit -m "Add Git LFS tracking"
git push
```

---

## 🚀 Advanced: Manual Sync

If you ever need to manually sync to HF Space:

```bash
cd F:\github-fleetmind-team

# Option 1: Push directly to HF Space remote
git push space main

# Option 2: Trigger GitHub Actions manually
# Go to: https://github.com/YOUR-USERNAME/fleetmind-mcp/actions
# Click "Sync to Hugging Face Space"
# Click "Run workflow" → "Run workflow"
```

---

## 📊 Workflow Diagram

```
Developer → GitHub Repo → GitHub Actions → HF Space → Live App
   ↓            ↓              ↓              ↓          ↓
 Codes      Receives       Triggers       Updates    Rebuilds
           Push Event       Sync         with new    & Serves
                                          code
```

---

## 🎯 Benefits of This Setup

✅ **Team Collaboration:** Everyone works on GitHub (familiar workflow)
✅ **Automatic Deployment:** Push to GitHub = Deploy to HF Space
✅ **No Permission Issues:** GitHub Actions uses your HF_TOKEN
✅ **Version Control:** Full history on GitHub
✅ **CI/CD Ready:** Can add tests, linting, etc.
✅ **Hackathon Compliant:** Final Space is on HF organization

---

## 📝 Next Steps

After setup is complete:

1. **Invite team members to GitHub repo**
2. **Update README with team information**
3. **Continue building your project**
4. **Create demo video (1-5 minutes)**
5. **Post on social media**
6. **Submit before November 30, 2025**

---

## 📚 Resources

- **GitHub Actions Docs:** https://docs.github.com/en/actions
- **HF Spaces Docs:** https://huggingface.co/docs/hub/spaces
- **Git LFS:** https://git-lfs.github.com/
- **Hackathon Info:** https://huggingface.co/MCP-1st-Birthday

---

**You're all set! Happy coding! 🚀**