Настройка интеграции с SCM (SVN / Git)

• СУТР Навигатор версии 0.16.0 или выше • SVN-сервер, доступный с сервера СУТР Навигатор по протоколу svn:// или http(s):// • Сервисный аккаунт SVN с правами чтения (для Import) • Доступ к SVN-серверу для установки hook-скрипта (для Webhook) • Утилиты jq, curl, openssl на SVN-сервере (для hook-скрипта)

При обновлении существующей установки: make server-migrate Или вручную: docker exec rms-navigator-api /app/packages/database/node_modules/.bin/prisma migrate deploy --schema=/app/packages/database/prisma/schema.prisma Миграция добавляет тип scm_type, таблицы scm_repositories и scm_commits. Все операции аддитивные — существующие данные не затрагиваются.

• SCM_ENCRYPTION_KEY (обязательная) — ключ шифрования паролей SVN, 64 hex-символа (32 байта). Сгенерировать: openssl rand -hex 32 • SCM_DIFF_CACHE_MAX_SIZE_MB (необязательная, по умолчанию: 100) — максимальный размер LRU-кэша для diff в МБ

Добавьте в .env.server (или .env.prod): SCM_ENCRYPTION_KEY=your-64-char-hex-key-here SCM_DIFF_CACHE_MAX_SIZE_MB=100 Затем перезапустите: make server-restart

1. Откройте Пространство → Настройки → Интеграции → Репозитории 2. Нажмите «Добавить репозиторий» 3. Заполните: Название, Тип (SVN), URL (например svn://svn.example.com/project/trunk), Логин, Пароль 4. Укажите маску commit message (regex) — первая capture-группа = код ЗИ 5. Нажмите «Проверить подключение» 6. Нажмите «Добавить репозиторий» для сохранения

Примеры regex-масок для извлечения кодов ЗИ: • ЗИ-(\d+) — совпадает с «ЗИ-42: описание» → код «42» • CR-(\d+) — совпадает с «CR-123: fix timeout» → код «123» • \[(\d+)\] — совпадает с «[456] update config» → код «456» Коммиты без совпадения с маской сохраняются без привязки к ЗИ.

Нажмите «Импорт» на карточке репозитория для загрузки существующей истории коммитов. Процесс: 1. Выполняется svn log для получения всех коммитов 2. Для каждого коммита парсится commit message по маске 3. Код ЗИ сопоставляется с существующими Запросами на Изменение 4. Если ЗИ не найден — создаётся placeholder со статусом DRAFT 5. Последующие импорты загружают только новые коммиты (инкрементально) Для больших репозиториев первый импорт может занять время.

После добавления репозитория Webhook URL отображается в диалоге: https://rm.example.com/api/v1/webhooks/scm/<REPOSITORY_ID> Секрет для HMAC-подписи (webhookSecret) можно получить через API: curl -s -b cookies.txt https://rm.example.com/api/v1/spaces/<SPACE_ID>/repositories/<REPO_ID> | jq -r '.data.webhookSecret'

На SVN-сервере создайте файл hooks/post-commit в директории репозитория: #!/bin/bash REPOS="$1" REV="$2" WEBHOOK_URL="https://rm.example.com/api/v1/webhooks/scm/REPOSITORY_ID" SECRET="WEBHOOK_SECRET" AUTHOR=$(svnlook author -r "$REV" "$REPOS") DATE=$(svnlook date -r "$REV" "$REPOS") MESSAGE=$(svnlook log -r "$REV" "$REPOS") CHANGED=$(svnlook changed -r "$REV" "$REPOS") PAYLOAD=$(jq -n --arg rev "$REV" --arg author "$AUTHOR" --arg date "$DATE" --arg message "$MESSAGE" --arg changed "$CHANGED" '{revision: $rev, author: $author, date: $date, message: $message, changed: $changed}') SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}') curl -s -X POST "$WEBHOOK_URL" -H "Content-Type: application/json" -H "X-SCM-Signature: sha256=$SIGNATURE" -d "$PAYLOAD" --max-time 10 > /dev/null 2>&1 & exit 0 Сделайте исполняемым: chmod +x hooks/post-commit Требования на SVN-сервере: jq, curl, openssl, svnlook

Откройте Запрос на Изменение → вкладка «Коммиты». Каждый коммит показывает: • Номер ревизии, автор, дата • Первая строка commit message • Количество изменённых файлов, добавленных/удалённых строк Клик на коммит раскрывает: • Полный commit message • Список изменённых файлов с типом изменения (A/M/D) • Unified diff (загружается из SVN по запросу, кэшируется на сервере)

• Проверьте доступность SVN-сервера: docker exec rms-navigator-api svn info --non-interactive --username USER --password PASS svn://server/repo • Проверьте логи API: docker compose logs api | grep scm • Убедитесь, что SCM_ENCRYPTION_KEY задан в переменных окружения

• Проверьте, что SVN-сервер может достучаться до СУТР Навигатор: curl -v https://rm.example.com/api/v1/webhooks/scm/REPO_ID • Проверьте, что секрет в hook-скрипте совпадает с webhookSecret репозитория • Проверьте формат JSON — все поля (revision, author, date, message) обязательны

• Проверьте, что формат commit message соответствует маске (regex) • Проверьте, что ЗИ с таким кодом существует в пространстве • Если ЗИ не найден, система создаёт placeholder. Проверьте список ЗИ на наличие записей «[SCM Import]»

• СУТР Навигатор версии 0.57.0 или выше • Личный токен доступа (PAT) с нужными правами: — Gitea: read:repository, read:user, право создания webhook — GitHub / GitHub Enterprise: scope repo (или public_repo для публичных), admin:repo_hook — GitLab: read_repository + api (для создания webhook) • Git-репозиторий, доступный с сервера API СУТР Навигатор по HTTPS • SSH и локальный клон НЕ поддерживаются — используйте только HTTPS + PAT

Если Git-сервер использует TLS-сертификат, подписанный внутренним УЦ, задайте NODE_EXTRA_CA_CERTS в .env.server (или .env.prod) и перезапустите API: NODE_EXTRA_CA_CERTS=/path/to/internal-ca.crt Без этого запросы к API провайдера завершатся ошибкой «unable to verify the first certificate».

1. Откройте Пространство → Настройки → Интеграции → Репозитории 2. Нажмите «Добавить репозиторий» 3. Выберите Тип = Git 4. Выберите Провайдер: Gitea / GitHub / GitLab 5. Укажите URL репозитория (HTTPS), например https://git.example.com/org/project 6. Введите Личный токен доступа (PAT) 7. Укажите маску commit message (regex) — первая capture-группа = код ЗИ 8. Нажмите «Проверить подключение» 9. Нажмите «Добавить репозиторий» для сохранения Токен шифруется AES-256-CBC перед сохранением (ключ: SCM_ENCRYPTION_KEY).

Нажмите «Импорт» на карточке репозитория для загрузки истории коммитов через API провайдера. Процесс: 1. Загружает коммиты из дефолтной ветки через REST API провайдера 2. Парсит каждый commit message по маске 3. Сопоставляет код ЗИ с существующими Запросами на Изменение 4. Если ЗИ не найден — создаётся placeholder со статусом DRAFT 5. Последующие импорты инкрементальные (только новые коммиты) Первый импорт ограничен SCM_GIT_IMPORT_MAX_COMMITS (по умолчанию: 500). Увеличьте в переменных окружения при необходимости.

После добавления репозитория Webhook URL и секрет отображаются в диалоге: https://rm.example.com/api/v1/webhooks/scm/<REPOSITORY_ID> Секрет (webhookSecret) можно получить через API: curl -s -b cookies.txt https://rm.example.com/api/v1/spaces/<SPACE_ID>/repositories/<REPO_ID> | jq -r '.data.webhookSecret'

Репозиторий → Settings → Webhooks → Add Webhook → Gitea: • Target URL: https://rm.example.com/api/v1/webhooks/scm/<REPOSITORY_ID> • HTTP Method: POST • Content Type: application/json • Secret: значение webhookSecret • Trigger On: Push Events Gitea подписывает запросы заголовком X-Gitea-Signature (HMAC-SHA256). СУТР Навигатор проверяет подпись автоматически.

Репозиторий → Settings → Webhooks → Add webhook: • Payload URL: https://rm.example.com/api/v1/webhooks/scm/<REPOSITORY_ID> • Content type: application/json • Secret: значение webhookSecret • Which events: Just the push event • Active: включено GitHub подписывает запросы заголовком X-Hub-Signature-256 (HMAC-SHA256). СУТР Навигатор проверяет подпись автоматически.

Репозиторий → Settings → Webhooks: • URL: https://rm.example.com/api/v1/webhooks/scm/<REPOSITORY_ID> • Secret token: значение webhookSecret • Trigger: Push events (отмечено) Важно: GitLab использует заголовок X-Gitlab-Token (передаёт секрет в открытом виде, а не HMAC-подпись). СУТР Навигатор поддерживает оба режима и выбирает метод проверки автоматически по заголовку запроса.

• Убедитесь, что PAT не просрочен и не отозван • Проверьте scope токена: Gitea (read:repository, webhook create), GitHub (repo + admin:repo_hook), GitLab (read_repository + api) • Убедитесь, что токен принадлежит аккаунту с доступом к репозиторию

Ошибка: «unable to verify the first certificate» Задайте NODE_EXTRA_CA_CERTS=/etc/ssl/certs/internal-ca.crt в окружении API и перезапустите сервис.

• Проверьте доступность СУТР Навигатор с платформы: curl -v https://rm.example.com/api/v1/webhooks/scm/REPO_ID • Gitea/GitHub: секрет в настройках webhook должен совпадать с webhookSecret репозитория; логи: docker compose logs api | grep webhook • GitLab: убедитесь, что поле «Secret token» заполнено (литеральное значение, не HMAC)

Первый импорт ограничен SCM_GIT_IMPORT_MAX_COMMITS (по умолчанию 500). Увеличьте значение в .env.server, перезапустите API и нажмите «Импорт» ещё раз для загрузки следующей партии.