Skip to content

Gitea Pages — Хостинг документации

📋 Обзор

Gitea Pages — аналог GitHub Pages для хостинга статических сайтов напрямую из Gitea.

URL документации: https://git.much-data.ru/claw/kwork-api/

🔧 НАСТРОЙКА

Шаг 1: Включить Pages в репозитории

  1. Зайди в https://git.much-data.ru/claw/kwork-api
  2. Settings → Pages
  3. Включить Enable Pages
  4. Выбрать источник:
  5. Source: gh-pages branch
  6. Folder: / (root)
  7. Save

Шаг 2: Настроить Gitea Token

  1. https://git.much-data.ru → Settings → Applications
  2. Создать токен с правами:
  3. write:repository
  4. write:package
  5. Скопировать токен
  6. В репозитории: Settings → Secrets
  7. Добавить секрет: GITEA_TOKEN = твой токен

Шаг 3: Первый деплой

cd /root/kwork-api

# Собрать документацию
uv run mkdocs build

# Проверить что site/ создан
ls -la site/

# Закоммитить и запушить
git add .
git commit -m "docs: initial documentation"
git push origin main

# CI/CD автоматически задеплоит на gh-pages

Шаг 4: Проверить

После успешного CI/CD:

Документация доступна: 

https://git.much-data.ru/claw/kwork-api/

Или если включён custom domain: 

https://kwork-api.much-data.ru/

🔄 АВТОМАТИЧЕСКИЙ ДЕПЛОЙ

Workflow срабатывает при: - ✅ Push в main ветку - ✅ Создании тега релиза

Что делает: 1. Собирает MkDocs документацию 2. Пушит в gh-pages ветку 3. Gitea Pages автоматически обновляет сайт

🌐 CUSTOM DOMAIN (опционально)

DNS настройка:

# В панели управления доменом much-data.ru

# CNAME запись:
kwork-api    CNAME    git.much-data.ru

# Или A запись:
kwork-api    A        5.188.26.192

В Gitea Pages:

  1. Settings → Pages
  2. Custom Domain: kwork-api.much-data.ru
  3. Save

Создать CNAME файл:

# В корне проекта (не в site/)
echo "kwork-api.much-data.ru" > static/CNAME
git add static/CNAME
git commit -m "docs: add custom domain"
git push

📊 СТРУКТУРА ВЕТКИ

main (исходный код)
├── src/
├── docs/
├── mkdocs.yml
└── .github/workflows/ci.yml

gh-pages (автоматически, только сайт)
├── index.html
├── api-reference/
├── search/
└── ...

🔍 TROUBLESHOOTING

Pages не включаются:

# Проверить что Gitea версия >= 1.19
# Админ должен включить Pages в настройках сервера

CI/CD ошибка деплоя:

# Проверить токен
# Проверить права токена (write:repository)
# Проверить что gh-pages ветка существует

404 на странице:

# Подождать 1-2 минуты (Gitea обрабатывает)
# Проверить что site/ не пустой
# Проверить workflow логи

📋 ЧЕКЛИСТ

  • Включить Pages в настройках репозитория
  • Создать Gitea Token
  • Добавить токен в Secrets (GITEA_TOKEN)
  • Запушить изменения в main
  • Дождаться CI/CD
  • Проверить https://git.much-data.ru/claw/kwork-api/
  • (Опционально) Настроить custom domain

🎯 АЛЬТЕРНАТИВЫ

Если Gitea Pages не работает:

1. Netlify (бесплатно)

# Подключить репозиторий
# Build command: uv run mkdocs build
# Publish directory: site/

2. Vercel (бесплатно)

# Аналогично Netlify
# Автоматический деплой из Git

3. Cloudflare Pages (бесплатно)

# Быстрый CDN
# Автоматический HTTPS

4. Своё сервер (nginx)

# Скопировать site/ на сервер
# Настроить nginx на /var/www/kwork-api-docs/

📞 ССЫЛКИ