savagedb_bot/README_GITEA_ACTIONS.md

Gitea Actions для автоматической сборки Docker образов

Обзор

В проекте настроены четыре workflow для автоматической сборки Docker образов:

1. docker-build.yml - для публикации в Docker Hub
2. docker-build-local.yml - для публикации в локальный registry
3. docker-build-test.yml - только тестирование сборки (без registry)
4. pull-request-check.yml - для проверки сборки в pull request

Настройка

1. Включение Gitea Actions

Убедитесь, что Actions включены в вашем Gitea instance:

# app.ini
[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://gitea.com

2. Настройка Secrets

Для Docker Hub (docker-build.yml):

В настройках репозитория -> Security -> Secrets добавьте:

• DOCKER_USERNAME - ваш username в Docker Hub
• DOCKER_PASSWORD - токен доступа или пароль Docker Hub

Для локального registry (docker-build-local.yml):

• DOCKER_REGISTRY_URL - адрес Docker registry (например: registry.gitlab.com, your-harbor.com)
• DOCKER_REGISTRY_USERNAME - username для локального registry
• DOCKER_REGISTRY_PASSWORD - пароль или токен для локального registry

3. Конфигурация registry

Docker Hub

Workflow использует docker.io по умолчанию. Образы будут доступны как:

docker.io/YOUR_USERNAME/salvagedb-bot:latest
docker.io/YOUR_USERNAME/salvagedb-bot:main
docker.io/YOUR_USERNAME/salvagedb-bot:v1.0.0

Локальный registry

Workflow автоматически использует URL из secrets. Образы будут доступны как:

${DOCKER_REGISTRY_URL}/salvagedb/salvagedb-bot:latest
${DOCKER_REGISTRY_URL}/salvagedb/salvagedb-bot:main
${DOCKER_REGISTRY_URL}/salvagedb/salvagedb-bot:v1.0.0

При необходимости измените IMAGE_NAME в файле .gitea/workflows/docker-build-local.yml

Триггеры сборки

Автоматические триггеры:

1. Push в ветки main или develop

   • Создает образы с тегами: latest, main, develop

2. Создание тегов начинающихся с v (например, v1.0.0)

   • Создает образы с семантическими тегами: 1.0.0, 1.0, 1, latest

3. Pull Request в main или develop

   • docker-build.yml: собирает образ для тестирования (не публикует)
   • docker-build-local.yml: собирает образ с тегом pr-XXX (не публикует)
   • pull-request-check.yml: полная проверка сборки + валидация + тесты безопасности

Ручной запуск:

Для локального registry доступен ручной запуск через веб-интерфейс Gitea:

• Actions -> Workflows -> "Build and Push Docker Image (Local Registry)"
• Можно указать произвольный тег

Структура тегов

Docker Hub workflow:

• latest - только для main ветки
• main, develop - соответствующие ветки
• v1.0.0, 1.0.0, 1.0, 1 - семантические версии
• pr-123 - для pull requests (не публикуется)

Локальный registry workflow:

• latest - для main ветки и версионных тегов
• main, develop - соответствующие ветки
• Версионные теги как есть (v1.0.0)
• pr-123 - для pull requests (не публикуется)
• Произвольные теги при ручном запуске

Docker Build Test workflow:

• Только сборка и тестирование (без registry)
• Запускается при ручном запуске или изменении Dockerfile/Python файлов
• Идеален для проверки сборки без настройки credentials
• Включает базовые проверки безопасности

Pull Request Check workflow:

• Только сборка и тестирование (не публикация)
• Валидация Dockerfile
• Проверка зависимостей
• Базовые проверки безопасности

Оптимизация

Кэширование

Workflows используют GitHub Actions cache для ускорения сборки:

• Кэшируются Docker слои между сборками
• Значительно ускоряет повторные сборки

Мультиплатформенная сборка

Docker Hub workflow собирает образы для:

• linux/amd64 (Intel/AMD)
• linux/arm64 (ARM, включая Apple Silicon)

Локальный workflow собирает только для linux/amd64 для экономии времени.

Мониторинг

Просмотр логов

1. Перейдите в Actions в веб-интерфейсе Gitea
2. Выберите нужный workflow run
3. Просмотрите детальные логи каждого шага

Troubleshooting

Ошибка "Username and password required":

::error::Username and password required

Решение:

1. Убедитесь, что настроены все необходимые secrets в Gitea
2. Secrets должны называться: DOCKER_REGISTRY_URL, DOCKER_REGISTRY_USERNAME, DOCKER_REGISTRY_PASSWORD
3. Или используйте docker-build-test.yml для тестирования без registry

Ошибки аутентификации:

• Проверьте правильность secrets
• Убедитесь, что токены имеют права на push
• Для Docker Hub используйте Access Token, не пароль

Ошибки сборки:

• Проверьте валидность Dockerfile
• Убедитесь, что все зависимости доступны
• Используйте docker-build-test.yml для локального тестирования

Проблемы с registry:

• Проверьте доступность registry
• Убедитесь в правильности URL
• Убедитесь, что registry поддерживает Docker API v2

Использование собранных образов

Запуск локально:

# Docker Hub
docker run -d --name salvagedb-bot \
  --env-file .env \
  your-username/salvagedb-bot:latest

# Локальный registry  
docker run -d --name salvagedb-bot \
  --env-file .env \
  registry.example.com/salvagedb/salvagedb-bot:latest

Docker Compose:

version: '3.8'
services:
  bot:
    image: your-username/salvagedb-bot:latest
    # или
    # image: registry.example.com/salvagedb/salvagedb-bot:latest
    env_file: .env
    restart: unless-stopped

Безопасность

• Secrets хранятся зашифрованными в Gitea
• Токены должны иметь минимальные необходимые права
• Рекомендуется использовать отдельные токены для CI/CD
• Регулярно ротируйте access tokens

Дополнительные возможности

Уведомления

Можно добавить уведомления в Slack/Discord/Telegram о статусе сборки.

Сканирование безопасности

Можно интегрировать сканеры уязвимостей (Trivy, Snyk).

Деплой

Можно расширить workflow для автоматического деплоя в staging/production.