Skip to main content

External context synchronizer

This advanced operator tool correlates Git history, GitHub/GitLab/Jira issues, and Sentry events with methods found in an existing CPG.

Integrations

This advanced operator tool correlates Git history, GitHub/GitLab/Jira issues, and Sentry events with methods found in an existing CPG. It is useful for ownership, change-history, incident, and hotspot investigations. Run it as the documented external-context workflow; normal repository import uses the standard project-import command.

Storage and effect

The CLI reads the project CPG through GoCPG gRPC using the explicit --duckdb path. Its synthetic tags and edges are compatibility objects held for the current run. The project CPG remains unchanged by these run-local objects. When --pg-url is supplied, source metadata can be inserted or updated in PostgreSQL tables such as external_context, file_commit_history, and runtime metrics.

Therefore:

  • items_synced, tags_created, and edges_created describe work in the run, not durable CPG mutation;
  • without PostgreSQL, raw external records are not persisted;
  • back up and scope the PostgreSQL target before a pilot synchronization.

The authoritative implementation is src/services/external_context/orchestrator.py.

Prerequisites

  • a current CodeGraph CPG and reachable GoCPG gRPC runtime;
  • the matching repository checkout for Git correlation;
  • optional PostgreSQL schema when durable external metadata is required;
  • least-privilege GitHub, GitLab, Jira, or Sentry credentials for the selected source.

Run each source separately before combining them.

Git history

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

Git synchronization defaults to 90 days and 1,000 commits. Add --no-blame when blame cost is not acceptable, understanding that author correlation becomes less precise.

Issues

GitHub and GitLab use --issue-repo; Jira uses --issue-project and normally --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 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 TOKEN

The current CLI accepts tokens as arguments. They may be visible in shell history or process inspection. Run these commands only through a protected operator wrapper that prevents recording secrets; do not paste production tokens into shared terminals or documentation.

Sentry

python -m src.services.external_context.orchestrator --duckdb data/projects/PROJECT.duckdb --sync-sentry --sentry-org ORG --sentry-project PROJECT --sentry-token TOKEN

Use --sentry-url for a self-hosted instance. The same command-line secret exposure caveat applies.

Combined run and statistics

--sync-all always includes Git and adds issues or Sentry only when their required selectors are present. Add --pg-url only when durable PostgreSQL writes are intended.

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 TOKEN --sentry-org ORG --sentry-project PROJECT --sentry-token TOKEN --pg-url POSTGRES_URL
python -m src.services.external_context.orchestrator --duckdb data/projects/PROJECT.duckdb --stats --pg-url POSTGRES_URL

Exit text contains per-source errors. A partially failed combined result must be handled per source; do not treat a nonempty item count as overall success.

Troubleshooting and rollback

  • If GoCPG is unavailable, restore the runtime before retrying; do not open the CPG directly from a second writer.
  • If no methods correlate, verify repository path, CPG freshness, file paths, and lookback window.
  • If PostgreSQL writes are not intended, omit --pg-url.
  • Roll back durable metadata using the customer’s database backup or a source-scoped transaction; synthetic run-local tags disappear when the process ends.

Source of truth

  • Orchestrator and CLI: src/services/external_context/orchestrator.py
  • Read and persistence boundary: src/services/external_context/base.py
  • Source adapters: src/services/external_context/git_sync.py, issue_sync.py, sentry_sync.py
  • General data handling: LLM security
Report a documentation issue