README_HF.md

How to Push Code to a New HuggingFace Space

Prerequisites

• Git installed
• A HuggingFace account
• A HuggingFace Access Token (create one at Settings > Tokens with Write permission)

---

Steps

1. Create a New Space on HuggingFace

1. Go to huggingface.co/new-space
2. Choose a Space name (e.g., My_App)
3. Select the SDK (Gradio, Streamlit, Docker, or Static)
4. Choose visibility (Public or Private)
5. Click Create Space

Your Space URL will be: https://huggingface.co/spaces/<YOUR_USERNAME>/<SPACE_NAME>

---

2. Clone the Empty Space Locally

git clone https://huggingface.co/spaces/<YOUR_USERNAME>/<SPACE_NAME>
cd <SPACE_NAME>

When prompted for credentials:

• Username: Your HuggingFace username
• Password: Your HuggingFace Access Token (NOT your account password)

---

3. Register Your Team

Create a team.yml file at the root of your Hugging Face Space folder with your team name and members. This is required for hackathon participation and helps organizers identify your team during evaluation.

display_name: Your Team Name
members:
  - name: Alice Chen, email: "alice@example.com"
  - name: Bob Martin, email: "bob@example.com"

Create a README.md file at the root of your Hugging Face Space folder with a brief description of your app. This is required for Hugging Face Spaces and helps organizers understand your app during evaluation. Replace [Your Team Name] with your actual team name. Also note that the app_file field should match the name of your main application file (e.g., app.py).

title: [Your Team Name]'s RAG App
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 4.44.1
python_version: '3.11'
app_file: app.py
pinned: false
license: apache-2.0

---

4. Add Codes

Pull the sample code Example-App-Hackathon-Gustave-Eiffel-2026 into the Space

To have a quick start, you can pull the sameple code Example-App-Hackathon-Gustave-Eiffel-2026 into your Space. You can do this by adding this repo as a second remote source and merging it into your Space:

# Inside your cloned Space folder:
cd <SPACE_NAME>

# Add the source repo as a second remote
git remote add source https://huggingface.co/spaces/millimanfrance/Example-App-Hackathon-Gustave-Eiffel-2026
# or from GitHub:
# git remote add source https://github.com/<OWNER>/<REPO>.git

# Fetch all branches from the source
git fetch source

# Merge the source's main branch into your Space
git merge source/main --allow-unrelated-histories -m "Pull code from source repo"

Add your code into the Space

If you are working in a team, your teammate can simply copy/paste your code or files into the cloned Space folder.

---

Add a .gitignore to exclude unnecessary files:

Put the following content in a .gitignore file at the root of your Space to avoid pushing large or sensitive files:

.venv
__pycache__/
**/__pycache__/
*.sqlite3
chroma_db/
.env

---

5. Commit and Push

git add .
git commit -m "Initial commit"
git push origin main
git remote remove source (if you have added the sample code Example-App-Hackathon-Gustave-Eiffel-2026 as a second remote)

---

6. Deploy to Hugging Face Spaces

1. Once you have pushed the code, (IF NOT) Push this code to the Space repository.
2. Add AZURE_API_KEY as a Space Secret (Settings → Secrets). Azure API key is a key to call the LLM APIs. The organizers will provide you one at the date of the hackathon.
3. The Space automatically installs dependencies and starts the app.
4. The hackathon will be a competition on the RAG (Retrieval-Augmented Generation) application you built. You are encouraged to learn the basics of RAG.

---

Troubleshooting reference

Binary File Rejection

HuggingFace rejects pushes containing binary files (e.g., .sqlite3, .pkl, .bin).

Fix:

1. Add the binary files to .gitignore
2. Remove them from git tracking:

   git rm -r --cached path/to/binary/file
   

3. Squash history to purge them completely:

   git add -A
   git reset --soft $(git rev-list --max-parents=0 HEAD)
   git commit -m "Clean initial commit"
   git push hfspace main --force
   

Authentication Failed

• HuggingFace does not accept account passwords for git. Use an Access Token.
• Make sure the token has Write permission.
• You can embed the token in the remote URL:

  git remote set-url hfspace https://<USERNAME>:<TOKEN>@huggingface.co/spaces/<USERNAME>/<SPACE_NAME>
  

Wrong Branch Name

Some repos use master instead of main. Check with:

git branch

Push to whichever branch your Space expects (usually main).

---

Security Reminder

• Never commit your HF token or API keys to the repo.
• If a token is accidentally exposed, revoke it immediately at huggingface.co/settings/tokens and generate a new one.
• Use environment variables or HuggingFace Space Secrets (Settings > Variables and secrets) for sensitive values.