Skip to content
DashboardWebsite

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.

  1. 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.

  2. 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).

  3. 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. The pr.gate_blocked and finding.needs_review notifications carry them, so a team channel receives only its own repositories’ events.

  4. Each team has a queue. The Team filter on the Findings page (GET /v1/findings?team_id=) lists the findings assigned to a team.

Three sources, in this order:

SourceWhen it applies
Teams set on the repositoryAlways. A person’s choice is never overwritten.
Ownership rulesOnce, when a repository is first discovered, and when an admin clicks Apply to unowned repositories.
Default review teamAt 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.

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}/products takes repositories. Each repository’s PATCH and POST .../repositories/bulk take product_id. In Terraform, set product_id on each opentremor_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.

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.

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.

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.

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:

LevelWhereRuns on
OrganizationRules → Packsevery repository
Productthe product’s Packs tabevery repository of the product
Repositorythe repository’s Packs cardthat 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.

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.

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.

SettingEffect
PacksEnable packs on this repository, on top of the organization’s and the product’s.
Rule variantPick the variant each pack uses, such as django for python-code-change.
Suggested variantA 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 hereExclude a custom rule from this repository, whatever its scope. A reason is required.
LLMUse another connection and model for this repository’s reviews.
Draft pull requestsOff 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 suggestionsPost code suggestions here, or not, whatever the organization’s setting.
Scan existing codeReview 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.

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.

  • 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 repository does not clear them.
  • 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)