--- title: "Cross-repository reviews · Docs · SourceAnt" description: "Documentation: Set up multi-repo code review: group repositories into a system, find the connections, and read a review that follows a change into everything it reaches." url: "https://sourceant.ai/docs/cross-repository-reviews/" --- # Cross-repository reviews Cross-repository review is what Systems makes possible. Group related repositories into a system, and a review can check how a change affects the code in every repository that system reaches. Group related repositories into a system and record their connections so reviews can follow those relationships. This guide shows you how to set that up. For an introduction to parts, connections and discovery results, see [Systems](https://sourceant.ai/docs/systems). ## Before you start - The repositories are connected, on the cloud or on your own instance. - You are an **owner** or **admin** of the workspace, or it is your personal one. Without that the buttons below are not rendered at all. ## 1\. Read each repository A repository does not go into a system as a bare part. Reading it derives a system of its own, named `owner/repo`, and the bigger system is then made of those smaller ones. Open **Systems** in the sidebar. If nothing has been modelled you will see _Nothing modelled yet_ and a **Create a system** button; otherwise use the **+** in the header, which is tooltipped _New system_. The drawer is titled **Draw a system**. Near the bottom, under **Not read yet**, every connected repository with no system behind it is listed with a **Read it** button. Read the ones you want in the system. You can also do this from a repository's own page, where the button is **Initialize from GitHub**, or **Read again** if it has been read before. ## 2\. Create the system that holds them In the same drawer: 1. **Read the repositories**, under _What looks like one system_, proposes groupings. Each suggestion says where it came from: _From a declared dependency_, _From imports across repositories_, or _From names only_. It creates nothing on its own. 2. **Name** the system, for example `Billing`. 3. **What it is**: one line on what has to be understood together to change it. 4. **Inside another system**: leave it on _Nothing. This is a system of its own_ unless you are nesting it. 5. **Systems in it**: tick the repository systems you read in step 1. They become part of this system rather than systems of their own. 6. **Create system**. _From names only_ is worth reading carefully. A suggestion resting on nothing but a matching name is the weakest evidence there is, and it is the one most worth checking by hand. ## 3\. Find the connections Open the system. Click the **share-shaped icon** just to the left of the **+** button in the header. Its tooltip is **Find connections**: _read what these are joined to, from what each one publishes and what its code says_. It appears once the system has repository systems inside it. It reads the repositories in the background and reports progress, for example _Reading 3 repositories._ then _Read 3 repositories. 1 could not be read._ When it finishes the page moves itself to the **Parts** tab. On a large estate it can take several minutes; leaving the page does not stop it. ## 4\. Approve what is real Everything inference finds arrives **pending**. Nothing it proposes is treated as fact until a person says so. Three places to work through them, all doing the same thing: - The triage card at the top of the Systems page, headed **N connections to look at** and ordered _Weakest evidence first_. **Approve** or **Reject** each one. - The **Connections** section under each system on the **Parts** tab. - **Architecture → Interactive**, which adds **Keep all N** and **Dismiss all** for working through a pile quickly. Work weakest-evidence-first, which is the order the triage card already puts them in. A connection read from a declared dependency is usually right. One resting on a name match deserves the ten seconds it takes to open the file it cites. ## What approving actually changes This is the part worth understanding, because it is not what most people assume. A review crosses into another repository **whether or not the link is approved**. Approval does not gate the reach. It changes how the review is allowed to talk about it. | Link state | What the review does | | --- | --- | | **Approved** | States the reach as fact, and says where the change could break the other side. | | **Pending** | Raises what the link would mean as a question. It does not assert it, and it attaches no suggestion to it. | So an unapproved graph is not a broken one. It is a quieter one. Approving is how you tell the reviewer it is allowed to be certain. ## 5\. Read a review Open a pull request in one of the repositories. The review gains a section for what the change reaches: the systems on the other end, the sibling code it went and read, quoted with the repository and the revision it came from. A sibling repository is read at the revision it was last indexed, because a pull request pins only its own. Where that revision is old, the review says so rather than presenting it as current. ## What it could not read A repository the review failed to reach is **named in the review, with the reason**. It is not quietly skipped. That is the difference between a reviewer you can rely on and one you cannot. A reviewer that silently skips half your system looks identical to one that read everything and found nothing. The usual causes, in order of how often they turn out to be the answer: - The repository was never read, so it has no system behind it. Go back to step 1. - It is connected but not inside the same system. - The app is not installed on it, so there is nothing to fetch. ## Parts that are not repositories Plenty of what a system depends on has no code to read. On the Parts tab, expand a system and use **\+ Add** to add **A resource**: a _Service_, _Database_, _Queue_, _External API_, _Deployment_, _Schema_, _Document_, or something else you name yourself. Give it a **Name** and an **Identifier**, which is what it is called where it actually lives, so somebody reading the review can go and find it. ## Joining things by hand Inference only proposes what it can point at a file for. When you know about a joint it cannot see, use **Add connections** on the Parts tab: pick **From** and **To**, then **How they are joined**. The choices are _Depends on_, _Consumes_, _Provides_, _Exposes_, _Contains_, _Deploys_, _Tests_ and _Documents_. A connection you add yourself is approved immediately. You are the person who would have approved it. ## Next - [Code review](https://sourceant.ai/docs/code-review): what else a change is judged against. - [Knowledge management](https://sourceant.ai/docs/knowledge-management): the decisions and constraints a review reads alongside the graph. - [Systems and cross-repository reviews](https://sourceant.ai/systems): how the map is built and kept honest.