Ingest GitHub pull requests, issues, and commits into CortexDB.

GitHub Connector

Captures pull requests, issues, comments, and commits from your GitHub org / repos as CortexDB experiences. Webhooks for low-latency ingest; cursor-based polling as a fallback.

Info

Two ways to run this connector:

  • Run it yourself (Free + paid) — pip install 'cortexdb-connectors[github]' then cortexdb-sync sync github. The connector reads your token from ~/.cortexdb/state.json (written by cortexdb init) or from env vars.
  • Managed sync (Starter and up) — CortexDB runs the connector as a worker on its infrastructure. Configure it once from your dashboard; CortexDB handles webhook registration, retries, backfill, and idempotency.

1. Prepare credentials in GitHub

  1. Settings → Developer settings → GitHub Apps → New GitHub App.
  2. Permissions:
    • Repository: Contents (read), Issues (read), Pull requests (read), Metadata (read)
    • Account: (none)
  3. Subscribe to events: issues, issue_comment, pull_request, pull_request_review, pull_request_review_comment, push.
  4. Install the App on the target org / repos.
  5. Note the App ID and generate a private key (.pem).

2. Configure in your CortexDB dashboard

  1. Sign in at cortexdb.ai/login.
  2. Settings → Connectors → Add Connector → GitHub.
  3. Paste the App ID, Installation ID, and private key (PEM contents).
  4. Set the scope template. Default: org:<your-org>/source:github/repo:{repo}. Placeholders: {owner}, {repo}, {author}.
  5. Pick sync mode: Real-time (webhooks — the dashboard provisions the delivery URL and validates with the webhook secret automatically) or Polling.
  6. Click Start sync.

What gets written

Each GitHub event becomes one experience:

EventModalityContent kindNotes
Pull request opened/editeddocumenttextTitle + body; preceded_by points to the PR's prior version
Pull request reviewfeedbackmessageReviewer's body
Issue opened/editeddocumenttextTitle + body
Comment (issue / PR)conversationmessagerole=user; context.preceded_by links to the parent
Push commitobservationtextCommit message + author

idempotency_key shape: gh:<event_type>:<owner>/<repo>/<id> — retries and backfills write once.

Permissions

CortexDB mints a service actor with scope.write on your target scope. Managed for you.

Run it yourself

If you'd rather host the connector yourself instead of using CortexDB's managed worker, every connector ships in the cortexdb-connectors PyPI package:

pip install 'cortexdb-connectors[github]'

# Step 1: get a CortexDB token + actor (one-time, free tier)
pip install cortexdb-cli
cortexdb init

# Step 2: supply the connector's third-party credentials
export GITHUB_TOKEN=...                # required

# Step 3: one-shot sync, or `watch` for a poll loop
cortexdb-sync sync github
cortexdb-sync watch github --interval 60

cortexdb-sync reads your CortexDB token + actor from ~/.cortexdb/state.json automatically. Cursor state is persisted in ~/.cortexdb/connectors-state.json, so re-running picks up where the last cycle left off.

See also