273 lines
10 KiB
Markdown
273 lines
10 KiB
Markdown
# Интеграция 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"
|
||
```
|
||
```
|
||
``` |