savagedb_bot/wiki/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:

```yaml
# 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

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

### Запуск локально:
```bash
# 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:
```yaml
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.