GitHub Event → Graph Mapping

Status: Not started — verified against the codebase on 2026-07-03 by an automated audit.

The spec is a comprehensive design document (Status: Design / requirements) specifying how GitHub webhook events should map to knowledge-graph nodes and edges across 50+ event types. All 6 implementation checklist items remain unchecked. The GitHub connector's parseWebhookEvent currently handles only 8 events and explicitly excludes all Tier 2-3 events. No new node labels, relationship types, inferred-edge jobs, or capability documentation have been implemented.

Implementation evidence

• docs/specs/github-event-graph-mapping/spec.md — 6 unchecked implementation checklist items confirming spec remains unimplemented
• packages/ingestion/src/connectors/github/index.ts parseWebhookEvent (lines 352-414) — handles only 8 events; comment states 'create, delete, fork, star, check_run have no ingestable data record'
• Zero commits to packages/ingestion/src/connectors/github/index.ts since spec added 2026-06-27; no extension of event parsing
• No codebase references to new node labels (:Branch, :Tag, :CheckSuite, :CheckRun, :Deployment, :Discussion, :Team, :Label, :Milestone, :SecurityAlert, :Advisory, :BranchProtectionRule, :Ruleset, :Project, :ProjectItem)
• No codebase references to new relationship types (MODIFIES, REVIEWED_BY, CLOSES, ON_BRANCH, CHECKED_BY, DEPLOYED, DEPLOYED_TO, RELEASED_FROM, AFFECTS, PROTECTS, BLOCKS, TAGGED)
• No evidence of inferred-edge Inngest jobs (ownership inference, intent→code, deploy provenance)

Known gaps at time of archive

• Tier 1-3 event parsing: extend parseWebhookEvent to handle create, delete, check_run, check_suite, status, workflow_run, workflow_job, deployment, deployment_status, label, milestone, discussion, code_scanning_alert, secret_scanning_alert, secret_scanning_alert_location, secret_scanning_scan, dependabot_alert, repository_advisory, branch_protection_rule, repository_ruleset, custom_property, deploy_key, and 30+ more
• Node label registration: Branch, Tag, CheckSuite, CheckRun, Deployment, DeploymentStatus, Discussion, DiscussionComment, Team, Label, Milestone, SecurityAlert, CodeScanningAlert, SecretScanningAlert, DependabotAlert, Advisory, BranchProtectionRule, Ruleset, Project, ProjectItem
• Relationship type registration: MODIFIES, REVIEWED_BY, CLOSES, ON_BRANCH, CHECKED_BY, DEPLOYED, DEPLOYED_TO, RELEASED_FROM, AFFECTS, PROTECTS, BLOCKS, DEPENDS_ON, TAGGED
• Upsert handlers and identity resolution (login → User/Person) for new entity types
• Post-ingestion Inngest jobs: ownership inference, intent→code edge derivation, deploy provenance tracing
• docs/capabilities/ documentation for GitHub webhook event coverage

Source documents (archived verbatim below)

• docs/specs/github-event-graph-mapping/spec.md

Spec — spec.md

GitHub Webhook Events → Knowledge-Graph Mapping

Status: Design / requirements Owner: Knowledge graph + connectors Related: ADR-012 Connector dual-write · Workspace schema registry · webhook handler apps/api/src/routes/v1/github-webhook.ts · GitHub connector packages/ingestion/src/connectors/github/index.ts

Purpose

This document defines, per GitHub webhook event, how the Oxagen knowledge graph should react. The north star: every event should leave an agent knowing more about the code, the people, the process state, and the risk surface than it did before — and able to act on that knowledge with fewer round-trips. A webhook is not a notification; it is a fact about the world that belongs in the graph.

We design for the agent first. For each event we ask: what could an agent now answer that it couldn't a second ago? If the answer is "nothing useful," we don't subscribe.

---

Graph model primer (read this before the tables)

The mappings below use Oxagen's existing conventions. Do not invent parallel ones.

Node labels

GitHub-ingested nodes are customer-scoped (is_system: false) and carry the :GraphNode anchor label plus a first-class domain label (e.g. :PullRequest). During the transition off :EntityNode {entityType} (see registry spec §3.3), the resolver in upsert-entity.ts may still fall back to :EntityNode — the target labels below are the contract.

Relationship types

Reuse the registered types where they fit; the ones marked ➕ must be added to the workspace schema registry (it is the allow-list — unregistered types are rejected by assertValidLabel).

Existing: AUTHORED_BY, ASSIGNED_TO, CONTAINS, PART_OF, IMPLEMENTS, REFERENCES, APPROVED_BY, MEMBER_OF, OWNS, TRIGGERED, TRIGGERED_BY, DERIVED_FROM, SOURCED_FROM, BRANCHED_FROM, REPLIES_TO.

New (➕): MODIFIES (commit→file), REVIEWED_BY (PR→person), CLOSES (PR→issue), ON_BRANCH (commit/PR→branch), CHECKED_BY (commit→check), DEPLOYED (deployment→commit), DEPLOYED_TO (deployment→environment), RELEASED_FROM (release→commit/tag), AFFECTS (alert→file/package/repo), PROTECTS (rule→branch), BLOCKS / BLOCKED_BY (issue dependencies), DEPENDS_ON (package→package), TAGGED (tag→commit).

Required properties (every GitHub node)

Carried on every ingested node, per the dual-write pipeline:

• externalId, externalUrl, naturalKey = {connectorId}:{connectionId}:{externalId} (dedup key)
• displayName — the only thing the UI shows as the primary identifier (never the UUID — see citation rule / NodeRef)
• connectionId, workspaceId, orgId — tenant scope; is_system: false
• label = domain entityType; properties = full normalized JSON blob
• createdAt, updatedAt, syncedAt
• embedding (1536-dim) on nodes with meaningful text (PR/issue/commit/discussion/release/comment) for semantic retrieval

Cross-cutting rules

1. Upsert, never duplicate. Key on naturalKey. Re-deliveries (GitHub retries, edited actions) must converge, not fan out.
2. Dual-write ordering. Postgres cursor write is the ACID source of truth; the Neo4j write is async/retryable via Inngest. If the graph write fails, the cursor does not advance.
3. Identity resolution. Resolve a GitHub login to a known :User when possible (org membership map); otherwise materialize a lightweight :Person. Never create two nodes for the same human.
4. Soft-delete, don't hard-delete. deleted/removed actions set deletedAt + detach hot edges; they don't DETACH DELETE history an agent may need for "what changed and when."
5. Tombstone unmaterialized targets. An edge to a not-yet-ingested node (e.g. a referenced issue we haven't synced) gets id: null + a described candidate, per the knowledgeNodeRef shape — never a bare UUID.
6. Every event stamps provenance = {deliveryId, eventName, action, deliveredAt, sender} so an agent can explain why a node looks the way it does and de-dupe on deliveryId.

---

Subscription tiers (which events to actually enable)

Don't "send me everything" — noise costs ingestion budget and dilutes the graph. Subscribe in tiers:

• Tier 1 — Code & collaboration spine (always on): Pushes, Pull requests, Pull request reviews, Pull request review comments, Issues, Issue comments, Branch/tag creation & deletion, Releases, Repositories.
• Tier 2 — Process & quality signal (on for any repo with CI): Check runs, Check suites, Statuses, Workflow runs, Workflow jobs, Deployments, Deployment statuses, Labels, Milestones, Sub-issues, Issue dependencies.
• Tier 3 — Risk & governance (on for any repo we secure): Code scanning alerts, Secret scanning alerts (+ locations, + scans), Dependabot alerts, Repository vulnerability alerts, Repository advisories, Branch protection rules/configurations, Repository rulesets, Security & analyses, all dismissal/bypass request events.
• Tier 4 — Org & social (sample or skip): Stars, Watches, Forks, Memberships, Teams, Org blocks, Page builds, Wiki, Visibility changes. Mostly low graph value; ingest as metadata, not first-class nodes, unless a customer asks.

---

Event → graph update tables

Reading the "Graph update" column: it lists the node(s) upserted, the edge(s) created/updated, the key properties set, and — in italics — the agent value (what an agent can now do/answer).

Code: pushes, branches, tags

Pull requests & reviews

Issues, labels, milestones, dependencies

CI/CD: checks, statuses, workflows, deployments

Releases & packages

Security & risk

Governance & policy

Repository, org, collaborators, teams

Discussions, projects, wiki, social

Lifecycle / infrastructure (handled, not graphed as domain nodes)

---

Derived / inferred edges (the real leverage)

The raw events above are the substrate. The agent-multiplying value comes from second-order edges the ingestion pipeline infers once the primitives exist:

1. Intent → code: (:Issue)<-[:CLOSES]-(:PullRequest)-[:PART_OF]-(:Commit)-[:MODIFIES]->(:SourceFile) lets an agent walk from "the bug" to "the exact lines that fixed it."
2. Ownership inference: frequent AUTHORED_BY/APPROVED_BY over files under a path → a derived (:Person)-[:OWNS]->(:SourceFile dir) so an agent knows who to ask / who to tag.
3. Risk → fix readiness: (:SecurityAlert)-[:AFFECTS]->(:SourceFile)<-[:MODIFIES]-(:Commit) tells an agent whether an alert's file has been touched since.
4. Deploy provenance: (:Deployment)-[:DEPLOYED]->(:Commit)-[:PART_OF]->(:PullRequest)-[:CLOSES]->(:Issue) answers "is the fix for issue N actually in prod."
5. Flakiness: repeated :WorkflowRun {runAttempt>1, conclusion:"success"} on the same commit → mark the failing :CheckRun flaky.

These are computed in the ingestion functions, not pushed by GitHub — but every one depends on the primitive nodes/edges being modeled correctly above. That is why we subscribe broadly within Tiers 1–3 and model first-class labels rather than dumping everything into :EntityNode.

---

Implementation checklist

• Register the ➕ node labels and relationship types in the workspace schema registry (allow-list gate).
• Extend packages/ingestion/src/connectors/github/index.ts parseWebhookEvent to map the Tier 1–3 events to sourceRecordTypes (today it covers pull_request, issues, issue_comment, pull_request_review_comment, pull_request_review, release, repository, push).
• Add upsert handlers for the new entity types in the entity-received pipeline, including identity resolution (login → :User/:Person).
• Add the inferred-edge jobs (ownership, intent→code, deploy provenance) as post-ingestion Inngest steps.
• Verify no secret material (secret-scanning values, deploy keys, PAT contents) is ever persisted to Postgres or Neo4j.
• Add the GitHub event coverage to docs/capabilities/ and confirm UI cites every node via NodeRef (displayName + label, never the UUID).