How to Build a Code Ownership Map from GitHub History

A useful code ownership map shows who has current, demonstrated context for each part of a repository. Build it from merged pull requests, reviews, file paths, and recency; use CODEOWNERS as an input, not the final answer.

This tutorial describes the same evidence model Helix uses to turn GitHub history into an explorable Engineering Graph.

1. Choose the ownership question

“Who owns the repository?” is too broad. Decide whether you need ownership by file, directory, subsystem, or service. Directory-level ownership is often the best starting point: it maps to how teams talk about the code while remaining specific enough to route a review.

Define the output before collecting data:

• primary expert for a path
• additional people with recent context
• evidence count and most recent contribution
• confidence or concentration warning
• source pull requests and reviews

2. Collect merged history

Use merged pull requests rather than commits alone. Pull requests preserve the social and decision context around a change: author, reviewers, discussion, timestamps, and the set of files that shipped together.

For every merged pull request, record the repository, author, reviewers, changed files, merge date, and referenced pull requests or issues. Normalize file paths so directories can be reconstructed consistently.

3. Separate authorship from review

Writing a change and validating it are different forms of knowledge. Track both. An author may understand the implementation; a recurring reviewer may understand constraints that are not obvious from the code.

A simple model can weight recent authorship and review independently:

score = recentAuthorship * 0.65 + recentReviews * 0.35;

The exact weights matter less than making them visible and applying them consistently. Avoid lifetime totals. Expertise decays when someone has not touched an area for a long time.

4. Build path relationships

Create nodes for repositories, directories, files, pull requests, and people. Then connect the evidence:

• a pull request MODIFIED a file
• a person AUTHORED or REVIEWED a pull request
• a directory CONTAINS a file or child directory
• a person recently TOUCHED a directory
• a person OWNS a path for the selected evidence window

This is what turns a spreadsheet of activity into a navigable ownership map. You can inspect the person, path, and change that supports every edge.

5. Detect concentration, not just leaders

The highest score is only half the answer. Compare it with the next credible contributors. If one person accounts for nearly all recent authorship and review on a critical path, label that as concentrated knowledge. Do not label the person as a problem. The system needs broader coverage.

Use that finding to schedule paired reviews, rotate maintenance, or create an onboarding task. Our guide to finding bus-factor risk turns the same data into a practical remediation plan.

6. Validate with the team

History records what happened, not every responsibility. Review the first map with maintainers and note where reorganizations, generated files, bots, or migrations distort the evidence. Exclude noise, shorten the recency window for fast-moving areas, and keep assigned ownership beside observed ownership.

In Helix, index a repository from the app, open the Graph, and select a directory or file to inspect its authors, reviewers, and source pull requests. Pulse then highlights ownership silos and expertise patterns across the indexed graph.

Keep the map alive

A code ownership map loses value when it becomes a quarterly spreadsheet. Recompute it as pull requests merge, preserve the prior evidence window, and make changes visible. The goal is not a permanent owner label. It is a current answer to: who can help us change this safely, and why?