Skip to main content

External context synchronizer

Configure the standalone Git, issue-tracker and Sentry synchronizer. Run a scoped sync and verify stored context, failures and freshness.

Integrations

Use external context when investigating a method: Git history shows related changes and authors, issue trackers provide linked work, and Sentry supplies runtime errors. The synchronizer compares these records with methods in an imported CPG. Run it as a separate Python module after importing the repository.

What gets stored

The command reads methods from the project CPG. Without --pg-url, imported context is available only while the command runs. With --pg-url, source metadata is stored in PostgreSQL for later statistics and investigation. For a pilot, use a separate database or limit the source scope and back up the PostgreSQL target.

For example, Git synchronization reads commits within the requested window and matches changed files to methods in the CPG. git blame provides authorship for method lines. With --no-blame, the synchronizer uses file-level commit history.

Start an investigation with the method involved in the error. Git history identifies related changes and authors, issues explain why the change was made, and Sentry events show failure conditions. Together, these sources help you select a commit and code location to inspect. The date window and commit limit keep the investigation focused.

Prerequisites

  • a current CodeGraph CPG and reachable GoCPG gRPC runtime;
  • the matching repository checkout for Git correlation;
  • a PostgreSQL connection when you need to keep imported metadata between runs;
  • least-privilege GitHub, GitLab, Jira, or Sentry credentials for the selected source.

Run each source separately before combining them. Run these PowerShell examples from the installed CodeGraph source repository root with its Python dependencies. Replace sample paths with your own and quote paths containing spaces. Inspect arguments without synchronizing:

python -m src.services.external_context.orchestrator --help

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.

For external-system examples, load ISSUE_TOKEN, SENTRY_TOKEN, and, when needed, POSTGRES_URL from your secret store into the process environment. Check required values are nonempty before execution. This does not hide secrets from CLI process arguments. Do not use literal production secrets in examples or terminal history.

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 "$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"

Standalone --sync-sentry uses Sentry SaaS. For a self-hosted instance, supply --sentry-url with --sync-all: the combined handler forwards this URL to the adapter.

Combined run and statistics

--sync-all includes Git. It adds issues when --issue-provider is present and Sentry when both --sentry-org and --sentry-project are present. Check remaining source selectors separately. 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 "$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"

A single-source run prints a SyncResult line with the source, context type, SUCCESS or FAILED status, processed-record count, and error count. The log contains error details. Check each selected source separately; if one fails, use its message to correct the input and rerun that source. The CLI returns exit code 0 for a successful run and 1 for a failed result or nonzero error count. Check both the exit code and SyncResult in automated runs.

--stats reports the context available in the CPG and, when PostgreSQL is connected, stored context, commit, and author counts. Use these totals to check which data is available after a run. The CLI prints operator-readable text.

Troubleshooting and rollback

  • If GoCPG is unavailable, restore the runtime before retrying.
  • 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 transaction limited to the selected source. Run-local context disappears when the command ends.
Report a documentation issue