Projects & repositories
A project groups one or more repositories and is the unit everything else hangs off: findings, schedules, and knowledge are all scoped to a project. A repository belongs to exactly one project.
Repositories with related code — a service and its shared library, say — belong in one project: repositories in the same project can be cloned alongside each other as read-only context during a review, so the agent sees how the pieces fit together.
Where the settings live#
Everything below sits on the project page, under Repositories & settings. That section starts collapsed — expand it and each connected repository shows its own controls. Trigger rules is a second collapsible inside a repository, and it appears only when that repository reviews every pull request; the other modes have nothing to filter.
Trigger modes#
Review pull requests decides when Ozone reviews a repository's pull requests:
| Mode | Behavior |
|---|---|
| Every pull request | New and updated PRs are reviewed automatically (subject to the rules below). |
| Only when mentioned | Nothing runs automatically; a maintainer asks for a review by commenting @ozone review on the PR. |
| Off | No PR reviews from GitHub events. Useful when you drive reviews yourself via the API — for example from your own GitHub Action. |
Mentions work in every mode — even on repositories set to Off, and even on PRs the rules below would skip. See Reviews & runs for the full mention syntax.
Trigger rules#
Rules filter which pull requests the automatic mode picks up. Ozone doesn't drop skipped PRs silently — it records why each recent one produced no run, and the API returns those reasons with the project.
They appear in the form in this order:
| Rule | What it does |
|---|---|
| Base branches | Only review PRs targeting matching branches. Empty means any. |
| Include paths | Review only when a changed file matches. Empty means any file. |
| Exclude paths | Changed files matching these don't count toward reviewing. Use it to ignore docs-only or generated-code changes. |
| Skip labels | Skip a PR when any of its labels matches. |
| Skip authors | Skip PRs from matching authors — usually dependabot[bot] and friends. |
| Review draft pull requests | Off by default. Turn it on to review drafts too. |
| Maximum changed files | Skip PRs touching more than this many files. Empty means no limit. |
A PR is reviewed when at least one changed file survives the path filters.
One further rule, require labels, reviews only PRs carrying at least one matching label. Set it through the API or the assistant; the settings form doesn't offer it yet, but it keeps any value you set elsewhere.
Each list field takes comma-separated values, and Save rules commits the lot. Patterns are globs: * matches within a path segment, ** crosses segments — so docs/** means everything under docs/, and *.md means markdown files at the top level.
One policy is built in and not configurable:
- Fork PRs are never reviewed automatically. Pull requests from external forks run only when someone with write access requests it (
@ozone review) — code from strangers doesn't get to trigger anything on its own.
Findings destination#
Per repository, choose where results go:
- PR comment (default) — findings go to a single sticky comment on the pull request, and to the dashboard.
- Dashboard only — no findings are posted to GitHub; they live only in Ozone.
Dashboard-only quietens findings, not Ozone itself. Every PR Ozone reviews still gets its Ozone security review check, and replies to @ozone mentions still land in the thread, because someone asked for them. Plan-limit notes are suppressed.
Managing a project#
The project page opens with open findings, schedules, tagged knowledge documents, and recent runs. Everyone sees Repositories & settings, but members see it read-only; admins can change what's in it and additionally get the danger zone. You can attach any repository your organization's GitHub installations can see, not only ones sharing an installation with the project. To start an ad-hoc analysis, ask the assistant or use the API or MCP.
Creating a project from the dashboard also switches on Continuous maintenance, the built-in task that triages open findings and refreshes project knowledge. It runs at most once a day and only when your code or findings have changed, so a quiet project costs nothing. Pause it under Schedules, or opt out up front when you create the project through the API.
Deleting a project or removing a repository is an admin action. Ozone first blocks new work and cancels active work. An admin can restore the project or repository from its project page for 30 days. After that, self-service recovery ends, but its review and activity history remains.