Link related repositories

Many applications are more than one repository: an API in one, the website that calls it in another. This guide shows how to link two such repositories in a group, see how they are related, and take one out of the group again.

Once both are learned, a review of a change to the API also reports what it breaks in the site, on the changed line.

Before you start

• You are a workspace admin. Viewers can see groups but not change them.
• Both repositories are in the workspace's Repositories list. If one is missing, open Repositories and refresh the list first (see Refresh the project list).

Link an API and the site that calls it

1. In the sidebar, under KNOWLEDGE, click Repository groups.
2. Click New group.
3. Name it after the application, for example Inventory. Add a description such as "Inventory API and the web app that calls it".
4. Choose both repositories and save.

The new group opens in a popup that lists both repositories as active. You can check from either side: Repositories → Configure → Groups shows the group.

Add a third repository, such as a worker that reads the same data, with Add repositories in the group's popup. A repository may be in several groups, for example one for the application and one for a shared library.

See how they are related

Under the repositories, How they are related shows which endpoints and packages (and any shared tables, messages or files) each repository uses from the other. Gryndel works this out from what it learned about each one, so both must be learned and their proposals merged:

1. In the Last learned column, click Learn for each repository that shows Not learned.
2. When the learn finishes, open its merge or pull request (the date in Last learned links to it), check .gryndel/contracts.yaml, and merge it.
3. Back on Repository groups, click the group's name, then Check again.

The map now shows an arrow from the site to the API, labelled with a route, and the table lists every call with the file and line on both sides. A row warning Not in the response names a field the site reads that the API's contracts don't list: check whether the site relies on something the API no longer returns. See How they are related.

See a review catch a break

With both repositories learned and their proposals merged, open a merge or pull request on the API that removes or renames a field the site reads (the relations table lists them under Fields). When the review finishes:

• A finding marked cross-repo sits on the changed line. It says the site still reads the field, and names the site's file and line.
• The summary has a Related repositories: line: checked …/inventory-web from their contracts (1 shared use touched by this change, 1 broken).

See What reviews check.

Set one aside, or take it out

You want to	Do this
Keep a repository listed but not counted for a while	Click Disable next to it. Click Enable to put it back.
Stop treating it as part of the application	Click Remove next to it and confirm.
Drop the whole link	Click Delete group and confirm. The repositories are not changed.

None of these touch the repositories' code or settings.

If something looks wrong

You see	What it means
A repository isn't offered when you create or edit a group	It isn't in the workspace's repository list yet. Refresh the list on the Repositories page.
Another group already has this name.	Group names must differ within a workspace, ignoring upper and lower case.
A limit message	A workspace can have 50 groups, and a group 50 repositories.
Left the workspace under a repository	It is no longer in the workspace's repository list. Remove it from the group.
No buttons, and a note that viewers can't change groups	Ask a workspace admin; see Members.
Not merged yet under Contracts	The learn's proposal isn't merged. Merge it, then click Check again.
Possibly out of date	A file the contracts point at changed since. Learn the repository again and merge the proposal.
Cannot read	Gryndel can't read that repository on the code host; the note says why, often a missing permission.
Related repositories: … not learned, so not checked on a review	The other repository has no contracts on its default branch. Learn it and merge the proposal.
A change that breaks the site gets no cross-repo finding	The change didn't touch a use the contracts list, and the code search didn't find it: it removes no name or route the site uses (for example it changes a type, or adds a call). Check the relations table, and correct the contracts under declared:.
Code search of … failed on a review	The code host refused the search, often its rate limit on GitHub. The next review searches again.
No arrow between two learned repositories	Neither one's contracts list a call or package the other provides. Correct the contracts under declared:; see Correct the contracts.