docs/huggingface-space-deploy_en.md

Hugging Face Space deploy

Target deployment flow:

Corporate GitLab repository
        ↓ GitLab CI
Private Hugging Face Docker Space
        ↓ CPU Basic / Free
HiveTrace Leaderboard

Hugging Face Space

The Space is created manually once.

Recommended settings:

• Visibility: Private
• SDK: Docker
• Hardware: CPU Basic / free
• App port: 5173

The project README.md already contains the Space frontmatter:

---
title: HiveTrace Leaderboard
emoji: 🛡️
colorFrom: green
colorTo: indigo
sdk: docker
app_port: 5173
pinned: true
---

Runtime secrets and variables in Hugging Face

Add the runtime secret in Space Settings:

HF_TOKEN=hf_...

This token is required by the app to read the private Hugging Face bucket. Do not expose it as a PUBLIC_* variable and do not commit it to the repository.

Variables:

HF_BUCKET_ID=hivetrace/leaderboard_frontend_v2
HF_BUCKET_PREFIX=latest
HF_BUCKET_CACHE_TTL_MS=300000
HF_BUCKET_REQUEST_TIMEOUT_MS=60000
HF_BUCKET_REQUEST_RETRIES=2

Optional:

HF_BUCKET_ENDPOINT=https://huggingface.co

GitLab CI variables

Add the following CI/CD variables in the corporate GitLab project:

HF_USERNAME=<huggingface-user-or-service-account-name>
HF_SPACE_TOKEN=<huggingface-write-token-for-space-repo>
HF_SPACE_REPO=<namespace>/<space-name>

Example:

HF_SPACE_REPO=hivetrace/guard-leaderboard

HF_SPACE_TOKEN must have write access to the Space repository.

Important: keep HF_SPACE_TOKEN and the runtime HF_TOKEN used for bucket reads as separate tokens.

In GitLab, mark HF_SPACE_TOKEN as a masked/protected variable.

Deploy flow

.gitlab-ci.yml runs two stages:

1. validate

   • pnpm install --frozen-lockfile
   • pnpm check (generates Paraglide output internally)
   • pnpm build

2. deploy:huggingface

   • runs only on the prod branch
   • pushes the current commit to the private Hugging Face Space repository
   • uses force push because the Hugging Face Space repository is a deploy repository
   • the Space automatically rebuilds the Docker image after the push

Production branch

Production deployment runs only from the prod branch.

Typical flow:

git checkout prod
git merge main
git push origin prod

After the push to prod, GitLab CI runs validation and then sends this commit to the main branch of the Hugging Face Space repository.

Local Docker smoke test

Before the first deployment, it is useful to test the Docker image locally:

docker build -t hivetrace-leaderboard .
docker run --rm -p 5173:5173 \
  -e HF_TOKEN=hf_... \
  -e HF_BUCKET_ID=hivetrace/leaderboard_frontend_v2 \
  -e HF_BUCKET_PREFIX=latest \
  hivetrace-leaderboard

After startup, open:

http://127.0.0.1:5173/