Initial commit

2026-09-16 17:00:24 +03:00
commit 08e551c8bc
@@ -0,0 +1,273 @@
+# Интеграция GitFlic → PT Sandbox
+
+PoC-скрипт для автоматической выгрузки релизов из **GitFlic** в **PT Sandbox** на анализ.
+
+## Содержание
+
+- [Как это работает](#как-это-работает)
+- [Подготовка: данные и ключи](#подготовка-данные-и-ключи)
+  - [GitFlic: создание API-токена](#gitflic-создание-api-токена)
+  - [PT Sandbox: получение API-ключа](#pt-sandbox-получение-api-ключа)
+- [Установка и запуск](#установка-и-запуск)
+  - [Зависимости](#зависимости)
+  - [Настройка config.yaml](#настройка-configyaml)
+  - [Запуск](#запуск)
+- [Конфигурация (справочник)](#конфигурация-справочник)
+- [Файл состояния state.json](#файл-состояния-statejson)
+- [Примеры запуска](#примеры-запуска)
+
+---
+
+## Как это работает
+
+Скрипт выполняет один проход (или бесконечный цикл):
+
+1. Загружает конфигурацию из `config.yaml`
+2. Загружает историю отправленных релизов из `state.json`
+3. Авторизуется в GitFlic по **API-токену** пользователя
+4. Получает список проектов (все / по списку / компании / команды)
+5. Для каждого проекта получает релизы
+6. Фильтрует уже отправленные (ключ: `project_id + release_id + tag + version`)
+7. Для каждого нового релиза:
+   - Скачивает **архив исходного кода** по тегу релиза
+   - Скачивает **прикреплённые файлы** (assets), если они есть
+   - Каждый файл отправляет в **PT Sandbox** отдельной задачей
+   - Помечает релиз как отправленный в `state.json`
+8. Логирует всё в консоль и/или файл
+9. Если включён цикл — ждёт заданный интервал и повторяет
+
+---
+
+## Подготовка: данные и ключи
+
+### GitFlic: создание API-токена
+
+Скрипт использует **персональный API-токен** пользователя GitFlic с правами на чтение.
+
+**Как создать:**
+
+1. Войдите в GitFlic под своей учётной записью.
+2. Перейдите в **Профиль → Настройки профиля → Ключи → API токены**.  
+   _(или откройте ссылку: https://gitflic.ru/settings/tokens)_
+3. Нажмите **«Создать токен»**.
+4. Задайте имя, например: `sandbox-integration`
+5. В разделе **Scopes (области)** отметьте:
+   - ✅ **api** — полный доступ к API (требуется для чтения проектов и релизов)
+   - ✅ **read_repository** — чтение репозиториев (для скачивания архива)
+6. Нажмите **«Создать»**.
+7. **Скопируйте токен сразу** — после закрытия страницы он будет недоступен.
+
+> **Важно:** токен даёт доступ ко всем проектам, в которых ваш пользователь является участником. Храните его в безопасном месте, не добавляйте в публичные репозитории.
+
+В `config.yaml` токен указывается в поле:
+
+```yaml
+gitflic:
+  api_token: "glpat-XXXXXXXXXXXXXXXXXXXX"
+
+### PT Sandbox: получение API-ключа
+
+Способ получения API-ключа зависит от версии PT Sandbox и способа развёртывания.
+
+**Вариант 1. Веб-интерфейс Sandbox**
+
+1. Войдите в веб-интерфейс PT Sandbox.
+2. Перейдите в **Настройки → API → Ключи доступа**.
+3. Нажмите **«Создать ключ»**, скопируйте сгенерированный ключ.
+
+**Вариант 2. Конфигурационный файл сервера**
+
+Найдите файл конфигурации Sandbox (обычно `config.yml`, `settings.py` или `.env`).  
+В нём может быть определён параметр наподобие:
+
+```yaml
+api_keys:
+  - "your-api-key-here"
+```
+
+**Вариант 3. Обратиться к администратору**
+
+Если Sandbox развёрнут вашей командой — уточните у DevOps/администратора, какой заголовок и значение используются для авторизации.
+
+**Типовые параметры авторизации (могут отличаться):**
+
+| Параметр | Наиболее частое значение |
+|---|---|
+| Заголовок (`auth_header`) | `X-API-Key` или `Authorization` |
+| Передача | Просто ключ в заголовке или `Bearer <key>` |
+
+В `config.yaml`:
+
+```yaml
+pt_sandbox:
+  api_key: "ваш-ключ"
+  auth_header: "X-API-Key"   # или "Authorization"
+
+
+## Установка и запуск
+
+### Зависимости
+
+- Python 3.9+
+- Установка зависимостей:
+
+```bash
+pip install -r requirements.txt
+```
+
+### Настройка config.yaml
+
+Скопируйте шаблон из `config.yaml` и заполните обязательные поля:
+
+```yaml
+gitflic:
+  base_url: "https://gitflic.ru"        # или ваш self-hosted URL
+  api_token: "glpat-..."                # API-токен пользователя (обязательно)
+
+pt_sandbox:
+  base_url: "http://192.168.1.100:8080" # URL вашей инсталляции Sandbox
+  api_key: "..."                        # API-ключ (обязательно)
+```
+
+### Запуск
+
+Однократный проход:
+
+```bash
+python main.py
+```
+
+Циклический запуск (каждый час):
+
+```yaml
+# config.yaml
+loop:
+  enabled: true
+  interval_seconds: 3600
+```
+
+```bash
+python main.py   # работает до Ctrl+C
+```
+
+
+## Конфигурация (справочник)
+
+### `gitflic` — подключение к GitFlic
+
+| Поле | Тип | Обяз. | По умолч. | Описание |
+|---|---|---|---|---|
+| `base_url` | строка | да | `https://gitflic.ru` | Базовый URL GitFlic |
+| `api_token` | строка | **да** | — | API-токен пользователя |
+| `project_source` | строка | нет | `all` | `all` / `list` / `company` / `team` |
+| `project_list` | массив | при list | `[]` | `["namespace/project"]` |
+| `project_ids` | массив | при list | `[]` | `[123, 456]` |
+| `company_id` | число | при company | `null` | ID компании |
+| `team_id` | число | при team | `null` | ID команды |
+| `scan_mode` | строка | нет | `latest` | `latest` или `all` |
+| `per_page` | число | нет | `50` | Страница пагинации |
+| `download_chunk_size` | число | нет | `8388608` | Чанк скачивания (8 МБ) |
+
+### `pt_sandbox` — подключение к PT Sandbox
+
+| Поле | Тип | Обяз. | По умолч. | Описание |
+|---|---|---|---|---|
+| `base_url` | строка | да | `http://localhost:8080` | URL Sandbox |
+| `upload_endpoint` | строка | нет | `/api/v1/files/upload` | Путь загрузки файла |
+| `auth_header` | строка | нет | `X-API-Key` | Заголовок авторизации |
+| `api_key` | строка | **да** | — | Ключ API |
+| `file_field_name` | строка | нет | `file` | Имя поля multipart |
+| `extra_fields` | словарь | нет | `{source: gitflic}` | Доп. поля запроса |
+| `timeout_connect` | число | нет | `30` | Таймаут соединения (с) |
+| `timeout_read` | число | нет | `300` | Таймаут чтения (с) |
+
+### `state`, `logging`, `loop`
+
+| Раздел | Поле | Тип | По умолч. | Описание |
+|---|---|---|---|---|
+| `state` | `file_path` | строка | `state.json` | Файл состояния |
+| `logging` | `level` | строка | `INFO` | DEBUG, INFO, WARNING, ERROR |
+| `logging` | `format` | строка | `%(asctime)s...` | Формат лога |
+| `logging` | `file` | строка | — | Файл лога (иначе только консоль) |
+| `loop` | `enabled` | bool | `false` | Вкл. бесконечный цикл |
+| `loop` | `interval_seconds` | число | `3600` | Интервал (с) |
+
+
+## Файл состояния `state.json`
+
+Автоматически создаётся при первом запуске и хранит историю отправленных релизов.
+
+```json
+{
+  "sent_releases": {
+    "1:42:v1.0:v1.0": {
+      "project_id": 1,
+      "project_name": "org/my-project",
+      "release_id": 42,
+      "release_tag": "v1.0",
+      "release_version": "v1.0",
+      "files": [
+        {
+          "filename": "source_org_my-project_v1.0.zip",
+          "type": "source_archive",
+          "sandbox_task_id": "task-uuid-12345"
+        }
+      ],
+      "sent_at": "2026-09-16T12:00:00+00:00"
+    }
+  }
+}
+```
+
+Чтобы **переотправить** релиз — удалите соответствующую запись из `state.json` и перезапустите скрипт.
+
+
+## Примеры запуска
+
+**1. Однократно, только последний релиз:**
+
+```bash
+python main.py
+```
+
+**2. В цикле, проверка каждые 30 минут:**
+
+```yaml
+# config.yaml
+loop:
+  enabled: true
+  interval_seconds: 1800
+```
+
+```bash
+python main.py  # Ctrl+C для остановки
+```
+
+**3. Только проекты компании ID=5:**
+
+```yaml
+gitflic:
+  project_source: "company"
+  company_id: 5
+```
+
+**4. Конкретные проекты по имени:**
+
+```yaml
+gitflic:
+  project_source: "list"
+  project_list:
+    - "my-namespace/app-frontend"
+    - "my-namespace/app-backend"
+  project_ids: [101, 203]
+```
+
+**5. Детальное логирование:**
+
+```yaml
+logging:
+  level: "DEBUG"
+  file: "debug.log"
+```
+```
+```