GITHUB_ACTIONS_SETUP.md

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

• Created GitHub repository directory: F:\github-fleetmind-team
• Copied all HF Space code to GitHub repo
• 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:

# 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:

# 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:

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:

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:

# 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

# 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

# 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:

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! 🚀