GITHUB_SETUP.md

🚀 GitHub + Hugging Face Setup Guide

Follow these steps exactly to push TeamForge to GitHub and deploy to Hugging Face Spaces.

---

PART 1 — Push to GitHub

Step 1: Create a GitHub account (if you don't have one)

Go to https://github.com → Sign Up → free account

---

Step 2: Create a new repository on GitHub

1. Click the + button (top right) → New repository
2. Fill in:
   • Repository name: teamforge
   • Description: OpenEnv Benchmark for Autonomous Software Engineering Agents
   • Visibility: Public ✅ (required for hackathon)
   • Do NOT tick "Add README" (we have our own)
3. Click Create repository
4. Copy the URL shown — it looks like:

   https://github.com/YOUR_USERNAME/teamforge.git
   

---

Step 3: Install Git (if not installed)

Check if installed:

git --version

If not installed:

• Windows: Download from https://git-scm.com → install → restart VS Code
• Mac: Run xcode-select --install in terminal

---

Step 4: Open VS Code terminal in your teamforge folder

1. Open VS Code
2. File → Open Folder → select the teamforge folder (extracted from zip)
3. Press Ctrl + ` to open terminal

---

Step 5: Run these commands ONE BY ONE

# 1. Tell Git who you are (use your GitHub email)
git config --global user.email "your@email.com"
git config --global user.name "Your Name"

# 2. Initialize git in the folder
git init

# 3. Add all files
git add .

# 4. First commit
git commit -m "feat: TeamForge OpenEnv benchmark - initial submission"

# 5. Set main branch
git branch -M main

# 6. Connect to GitHub (paste YOUR repo URL here)
git remote add origin https://github.com/YOUR_USERNAME/teamforge.git

# 7. Push to GitHub
git push -u origin main

If it asks for username/password:

• Username: your GitHub username
• Password: use a GitHub Personal Access Token (NOT your password)
  • Go to GitHub → Settings → Developer settings → Personal access tokens → Generate new token
  • Select repo scope → Generate → Copy the token → paste as password

---

Step 6: Verify

Go to https://github.com/YOUR_USERNAME/teamforge — you should see all your files there.

---

PART 2 — Deploy to Hugging Face Spaces

Step 1: Create Hugging Face account

Go to https://huggingface.co → Sign Up → free account

---

Step 2: Create a new Space

1. Go to https://huggingface.co/spaces
2. Click Create new Space
3. Fill in:
   • Space name: teamforge
   • License: MIT
   • SDK: Gradio ✅
   • Hardware: CPU basic (free)
4. Click Create Space

---

Step 3: Add your API key as a Secret

1. In your Space → Settings tab → Repository secrets
2. Add these three secrets:

   Name: HF_TOKEN
   Value: your_groq_api_key_here
   
   Name: API_BASE_URL
   Value: https://api.groq.com/openai/v1
   
   Name: MODEL_NAME
   Value: llama3-8b-8192
   

   ⚠️ Regenerate your Groq key first at console.groq.com — the old one was shared publicly

---

Step 4: Push code to the Space

# In your VS Code terminal (inside teamforge folder)

# Add HuggingFace Space as a remote
git remote add hf https://huggingface.co/spaces/YOUR_HF_USERNAME/teamforge

# Push to HuggingFace
git push hf main

If it asks for credentials:

• Username: your HuggingFace username
• Password: your HuggingFace Access Token
  • Go to HuggingFace → Settings → Access Tokens → New token → Write access → Copy

---

Step 5: Verify deployment

1. Go to https://huggingface.co/spaces/YOUR_HF_USERNAME/teamforge
2. Wait 2–3 minutes for it to build
3. You should see the Gradio interface

---

PART 3 — Submit to Hackathon

When submitting, provide:

Field	Value
GitHub URL	https://github.com/YOUR_USERNAME/teamforge
HF Space URL	https://huggingface.co/spaces/YOUR_USERNAME/teamforge
Inference script	inference.py (in root)
API_BASE_URL	https://api.groq.com/openai/v1
MODEL_NAME	llama3-8b-8192
HF_TOKEN	your Groq API key

---

PART 4 — Test Before Submitting

Run these to confirm everything works:

# 1. Tests pass
pytest tests/test_environment.py -v

# 2. Demo runs
python demo.py

# 3. Log format is correct
set HF_TOKEN=gsk_...         # Windows
export HF_TOKEN=gsk_...      # Mac/Linux
python inference.py --task easy_bugfix_chunk_list

# Expected output:
# [START] task=easy_bugfix_chunk_list env=teamforge model=llama3-8b-8192
# [STEP] step=1 action=plan_step reward=0.02 done=false error=null
# ...
# [END] success=true steps=8 score=0.97 rewards=...

---

Common Errors & Fixes

Error	Fix
git: command not found	Install Git from git-scm.com, restart VS Code
remote: Repository not found	Check the GitHub URL — must match your username exactly
Authentication failed	Use Personal Access Token, not your password
pip install fails	Add --break-system-packages or use pip3
python: command not found	Use python3 or py instead
HF Space shows error	Check Secrets are set correctly in Space settings

---

Quick Reference — All Commands

# Push to GitHub
git init
git add .
git commit -m "feat: TeamForge OpenEnv benchmark"
git branch -M main
git remote add origin https://github.com/YOUR_USERNAME/teamforge.git
git push -u origin main

# Push to HuggingFace
git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/teamforge
git push hf main

# After making changes, update both:
git add .
git commit -m "fix: description of change"
git push origin main
git push hf main