Review routing
Just want to do it in the dashboard? See the guide: Create a team and route its repositories to it or Create a product.
When a pull request needs a review, the team that owns the repository should hear about it, not everyone. Review routing links each repository to one or more teams. From then on, the repository’s pull requests, the findings that need review and their notifications carry those teams.
How it works
Section titled “How it works”-
OpenTremor lists your repositories. Connecting GitHub or GitLab lists every repository the App installation or the token reaches. Pull requests, GitHub installation events and Sync now on the Repositories page keep the list current.
-
Each repository gets its teams. An admin assigns teams on the Repositories page, one repository at a time or in bulk. Ownership rules and a default review team fill the gaps (see below).
-
Reviews follow the teams. When a pull request is analysed, its repository’s and product’s teams are recorded on the check and on every finding that enters
needs_review. Thepr.gate_blockedandfinding.needs_reviewnotifications carry them, so a team channel receives only its own repositories’ events. -
Each team has a queue. The Team filter on the Findings page (
GET /v1/findings?team_id=) lists the findings assigned to a team.
Who owns a repository
Section titled “Who owns a repository”Three sources, in this order:
| Source | When it applies |
|---|---|
| Teams set on the repository | Always. A person’s choice is never overwritten. |
| Ownership rules | Once, when a repository is first discovered, and when an admin clicks Apply to unowned repositories. |
| Default review team | At review time, for a repository with no team. It is never written onto the repository, so changing it re-routes every unowned repository at once. |
An ownership rule is a glob on the repository’s full name, such as acme/payments-*, and the
teams it gives. Rules are tried in order and the first match wins. Matching ignores case.
With no team and no default review team, a review goes to the whole organization, as it did before teams existed.
Products
Section titled “Products”A product groups repositories, such as an API, its web app and its infrastructure. A repository belongs to at most one product. Adding it to another product moves it there.
- When you create a product, on the Products page, pick its repositories in the same form.
To add repositories discovered later, enter a name pattern such as
acme/checkout-*. It becomes an ownership rule, placed after the existing ones. - On the product’s page, Edit repositories adds and removes repositories.
- On the Repositories page, select repositories, then Set product.
- Through the API,
POST /v1/orgs/{org_id}/productstakesrepositories. Each repository’sPATCHandPOST .../repositories/bulktakeproduct_id. In Terraform, setproduct_idon eachopentremor_repository.
Moving a repository always needs the repositories:manage permission. Creating or editing the
product also needs products:manage.
- A product’s teams review every repository in it, in addition to the repository’s own teams. The default review team applies only when neither has a team.
- Deleting a product removes its repositories from it. They keep their own teams.
From a product to its findings
Section titled “From a product to its findings”Each changeset belongs to one repository: the repository of the pull request it reviews, or the one named in an API analysis. A finding records the repositories where it was seen. The product is read through the repository, so a repository moved to another product takes its changesets and findings with it.
- Products → a product lists its repositories, each with its open findings by severity, its number of changesets and its latest revision. Its Changesets tab lists the changesets of all its repositories. Its Goals tab holds the product’s goals. Its Report tab shows the product report.
- Repositories → a repository opens on Activity, which lists its open findings and changesets, each with its pull request. Report shows the repository report. Settings, Packs, Rules, Knowledge and Scan contain the settings below.
- A changeset’s page shows its product, repository and pull request above the report.
- The Changesets page filters by product and repository. The Findings page takes
?repository=as well as the Product filter.
Open findings have the status open, needs_review or acknowledged. The product and repository
reports list them by repository, with each repository’s recent changesets, after the rules with
the most findings. They are available as Markdown, HTML or JSON (GET /v1/orgs/{org_id}/products/{product_id}/report,
GET /v1/orgs/{org_id}/repositories/{provider}/{external_id}/report). Org report templates apply
to changeset reports only, and these reports have no share link.
Changesets created before this view existed have no repository. A finding gets its repositories the next time a review sees it.
Like teams, a product grants no access.
LLM for all of a product’s repositories
Section titled “LLM for all of a product’s repositories”The LLM column on the Products page shows the connection and model used by each product’s repositories: one value when they all agree, Mixed when they differ. Set LLM writes one connection and model to every repository in the product. Use the integration’s on all clears the LLM setting on every repository, so they fall back to the integration’s.
The product stores no LLM. A repository added to the product later keeps its own setting, so apply the setting again. You need permission to manage repositories.
Rule scope
Section titled “Rule scope”A custom rule runs on every analysis by default. Turn on Only for some teams or products on the rule to limit it: it then runs on a pull request only when the repository is owned by one of its teams (its own teams or its product’s), is in one of its products, or is listed by name. Scope is one of five checks a rule passes before it runs; see How Rules Apply.
- The default review team does not count. It is a routing fallback, not an owner.
- An analysis with no repository, such as an API call that names none, runs only org-wide rules.
- A team or product deleted later stays in the scope and matches nothing. The rule is never widened to the whole organization; the Rules page flags it.
Which packs run
Section titled “Which packs run”Every pack starts off. Each pack you enable calls the model on the pull requests it applies to, so enable only what you need. Three levels each keep their own list, and they only add up:
| Level | Where | Runs on |
|---|---|---|
| Organization | Rules → Packs | every repository |
| Product | the product’s Packs tab | every repository of the product |
| Repository | the repository’s Packs card | that repository |
A pull request runs the packs of all three. To keep a pack off one repository, enable it on the products or repositories that need it, not on the organization. An analysis that names no repository, such as an API call, runs only the organization’s packs.
A repository with no pack is not reviewed. Its pull requests get a pending check that says so, and no model is called, so it runs no agent-injection scan or goal check either. Where the check is required, the pull request cannot merge until a pack is enabled and a new commit is pushed. A repository with at least one pack gets the normal check, even when a pull request only touches files whose packs are off.
Suggested packs
Section titled “Suggested packs”When a repository joins the list, OpenTremor reads its file list and suggests each pack that claims a file there and is off. It reads no file content and calls no model. A pull request review also suggests the packs of the files it skipped. The repositories list marks a repository with No pack or a count of suggestions, and its Packs card offers Enable and Dismiss. Nothing is enabled until someone clicks. A dismissed pack is not suggested on that repository again.
Repository settings
Section titled “Repository settings”Each repository’s page shows what its next review runs with and lets an admin change it. A value
an ownership rule filled shows From ownership rule pattern; changing it makes it the
repository’s own.
| Setting | Effect |
|---|---|
| Packs | Enable packs on this repository, on top of the organization’s and the product’s. |
| Rule variant | Pick the variant each pack uses, such as django for python-code-change. |
| Suggested variant | A pack can suggest a variant from the content it analysed. Nothing changes until someone clicks Apply; Dismiss keeps that suggestion from coming back. |
| Rules turned off here | Exclude a custom rule from this repository, whatever its scope. A reason is required. |
| LLM | Use another connection and model for this repository’s reviews. |
| Draft pull requests | Off by default: a draft gets a pending check but no review. The review runs when the author marks it ready. When on, every push to a draft is reviewed. An ownership rule can set this for new repositories; the bulk API and Terraform can set it for many repositories at once. |
| Code suggestions | Post code suggestions here, or not, whatever the organization’s setting. |
| Scan existing code | Review the code already on the default branch. See Repository Scan. |
A setting that breaks later never fails a review. A variant a pack dropped falls back to the pack’s default; a deleted connection falls back to the integration’s.
An API analysis can name its repository, so a CI job is reviewed like a pull request: same
settings, same scoped rules, and its findings reach the repository’s teams and product. For
server-side analysis, pass repository in the body of POST /v1/{pack}/{changeset}/analyze. For
client-led analysis, pass ?repository= on the ingest call: the revision keeps it, and every
claim of that revision returns the repository’s rules.
The teams and product are recorded on the changeset when the call is made. A pull request review records them when its job starts.
Reassigning a finding
Section titled “Reassigning a finding”A finding takes its teams when it enters needs_review. To send it elsewhere, click its Teams
cell on the Findings page, or call
PUT /v1/findings/{resource_hash}/{rule_id}/teams.
If it still needs review, the teams you add are notified.
Limits
Section titled “Limits”- No periodic re-sync. A missed GitHub delivery stays wrong until the next Sync now.
- GitLab webhooks are still set per project. The token can reach a project that has no webhook. That project is listed with no last pull request, and its merge requests are not reviewed until its webhook is added (see GitLab integration).
- One set of teams per repository. Teams per path inside a monorepo are not supported yet.
- An API analysis names its repository only if the caller says so. Without
repository, an API analysis’s findings get no team or product, and only org-wide rules run. - A changeset keeps the owners from the last call that named a repository. A later ingest of
the same changeset without
repositorydoes not clear them.
Reference
Section titled “Reference”- Repositories API
- Team channels
- Products API
- Rule scope
- Decision records:
OpenTremor-core#0020(repositories and ownership),OpenTremor-platform#0018(team-scoped channels),OpenTremor-core#0021(products),OpenTremor-core#0022(rule scope),OpenTremor-core#0023(repository settings),OpenTremor-core#0024(variant suggestions)