docs/huggingface-space-deploy_ru.md

Hugging Face Space deploy

Целевая схема:

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

Hugging Face Space

Space создается вручную один раз.

Рекомендуемые настройки:

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

В README.md проекта уже есть Space frontmatter:

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

Runtime secrets and variables in Hugging Face

В Space Settings нужно добавить runtime secret:

HF_TOKEN=hf_...

Этот токен нужен приложению для чтения приватного Hugging Face bucket. Его нельзя делать PUBLIC_* переменной и нельзя коммитить в репозиторий.

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

Опционально:

HF_BUCKET_ENDPOINT=https://huggingface.co

GitLab CI variables

В корпоративном GitLab нужно добавить CI/CD variables:

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

Пример:

HF_SPACE_REPO=hivetrace/guard-leaderboard

HF_SPACE_TOKEN должен иметь право записи в Space repository.

Важно: HF_SPACE_TOKEN и runtime HF_TOKEN для чтения bucket лучше держать разными токенами.

HF_SPACE_TOKEN в GitLab лучше пометить как masked/protected variable.

Deploy flow

.gitlab-ci.yml делает два этапа:

1. validate

   • pnpm install --frozen-lockfile
   • pnpm check (внутри генерирует Paraglide output)
   • pnpm build

2. deploy:huggingface

   • срабатывает только на ветке prod
   • пушит текущий commit в private Hugging Face Space repository
   • использует force push, потому что Hugging Face Space является deploy-репозиторием
   • Space автоматически пересобирает Docker image после push

Production branch

Продакшн-деплой запускается только из ветки prod.

Типовой flow:

git checkout prod
git merge main
git push origin prod

После push в prod GitLab CI выполнит validate-этап и затем отправит этот commit в ветку main Hugging Face Space repository.

Local Docker smoke test

Перед первым deploy желательно локально проверить Docker image:

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

После запуска открыть:

http://127.0.0.1:5173/