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