Используйте внешний контекст при расследовании метода: история Git показывает связанные изменения и их авторов, трекер задач — ход работы, а Sentry — ошибки выполнения. Синхронизатор сопоставляет эти записи с методами импортированной CPG. Запускайте его отдельным Python-модулем после импорта репозитория.
Какие данные сохраняются
Команда читает методы из CPG проекта. Без --pg-url импортированный контекст доступен только
во время работы команды. С --pg-url исходные метаданные сохраняются в PostgreSQL для дальнейшей
статистики и расследований. Для пилота выберите отдельную базу либо ограничьте область источника
и сохраните резервную копию PostgreSQL.
Например, синхронизация Git читает коммиты за заданное окно и сопоставляет изменённые файлы
с методами CPG. git blame уточняет авторство по строкам метода. При --no-blame синхронизатор
использует историю коммитов файла.
При расследовании начните с метода, который вызвал ошибку. История Git покажет связанные изменения и авторов, задачи — причину изменения, а события Sentry — условия сбоя. Сопоставление этих источников помогает выбрать коммит и участок кода для проверки. Окно дат и лимит коммитов позволяют ограничить объём расследования.
Предварительные условия
- актуальная CPG CodeGraph и доступный gRPC-сервис GoCPG;
- локальная копия репозитория, соответствующая CPG, для сопоставления с историей Git;
- подключение PostgreSQL, если нужно хранить импортированные метаданные между запусками;
- минимально необходимые права GitHub, GitLab, Jira или Sentry для выбранного источника.
До комбинированного запуска проверьте каждый источник отдельно. Выполняйте примеры в PowerShell из корня установленного исходного репозитория CodeGraph с его Python-зависимостями. Пути ниже — примеры; замените их своими и заключите в кавычки, если они содержат пробелы. Сначала проверьте регистрацию аргументов без синхронизации:
python -m src.services.external_context.orchestrator --help
История Git
python -m src.services.external_context.orchestrator --duckdb 'data/projects/PROJECT.duckdb' --repo-path 'C:/work/project' --sync-git --git-since-days 30 --git-max-commits 500
По умолчанию берутся 90 дней и не более 1 000 коммитов. --no-blame снижает стоимость запуска,
но делает сопоставление авторов менее точным.
Для примеров с внешними системами получите ISSUE_TOKEN, SENTRY_TOKEN и, при необходимости,
POSTGRES_URL из хранилища секретов в окружение процесса. Перед запуском проверьте, что нужные
значения непустые. Это не устраняет видимость секретов в аргументах CLI. Не используйте литералы
боевых секретов в примерах или истории терминала.
Задачи
Для GitHub и GitLab используется --issue-repo, для Jira — --issue-project и обычно
--issue-url:
python -m src.services.external_context.orchestrator --duckdb 'data/projects/PROJECT.duckdb' --sync-issues --issue-provider github --issue-repo 'OWNER/REPOSITORY' --issue-token "$env:ISSUE_TOKEN"
python -m src.services.external_context.orchestrator --duckdb 'data/projects/PROJECT.duckdb' --sync-issues --issue-provider jira --issue-project 'KEY' --issue-url 'https://jira.example.com' --issue-token "$env:ISSUE_TOKEN"
Sentry
python -m src.services.external_context.orchestrator --duckdb 'data/projects/PROJECT.duckdb' --sync-sentry --sentry-org ORG --sentry-project PROJECT --sentry-token "$env:SENTRY_TOKEN"
Одиночный --sync-sentry обращается к Sentry SaaS. Для собственного экземпляра передайте
--sentry-url в комбинированном запуске --sync-all: этот обработчик передаёт URL адаптеру.
Общий запуск и статистика
--sync-all включает Git. Задачи добавляются при наличии --issue-provider, Sentry — при
наличии --sentry-org и --sentry-project. Проверьте остальные селекторы источника отдельно.
Передавайте --pg-url, только если намерены записывать данные в PostgreSQL.
python -m src.services.external_context.orchestrator --duckdb 'data/projects/PROJECT.duckdb' --repo-path 'C:/work/project' --sync-all --issue-provider gitlab --issue-repo 'GROUP/REPOSITORY' --issue-token "$env:ISSUE_TOKEN" --sentry-org ORG --sentry-project PROJECT --sentry-token "$env:SENTRY_TOKEN" --pg-url "$env:POSTGRES_URL"
python -m src.services.external_context.orchestrator --duckdb 'data/projects/PROJECT.duckdb' --stats --pg-url "$env:POSTGRES_URL"
Одиночный запуск печатает строку SyncResult: источник, тип контекста, статус SUCCESS или
FAILED, число обработанных записей и число ошибок. Подробности ошибок выводятся в журнал.
Проверяйте каждый источник отдельно; если запуск завершился с ошибкой, исправьте входные данные
по сообщению источника и повторите запуск. При успехе CLI возвращает код 0, при неуспешном
результате или ненулевом числе ошибок — код 1. В автоматизированном запуске проверяйте код
завершения и содержимое SyncResult.
--stats показывает контекст, доступный в CPG, и, при подключении PostgreSQL, число сохранённых
контекстов, коммитов и авторов. Используйте эти значения, чтобы проверить доступность данных
после запуска. CLI выводит результат в виде текста.
Диагностика и откат
- Если GoCPG недоступен, восстановите сервис до повтора.
- Если методы не сопоставились, проверьте путь репозитория, свежесть CPG, пути файлов и окно дат.
- Если запись в PostgreSQL не нужна, не передавайте
--pg-url. - Откатывайте сохранённые метаданные из резервной копии или транзакцией для выбранного источника. Временный контекст исчезает после завершения команды.