Projects and repositories

A project is Izri's unit of configuration: one repository, its scope config, its runs, its reports.

Install the GitHub App

The App is what lets Izri read your diffs and publish checks. OAuth login alone isn't enough — that authenticates you, not the repository.

1. From your organization settings, start the GitHub App installation.
2. Choose the repositories to grant access to.
3. GitHub redirects back to Izri with an installation_id, which gets bound to your Izri organization.

Without the App installed you can still trigger runs through the CLI, but no check runs and no sticky comments appear on pull requests — Izri has no write access to say anything.

Create a project

Create the project and point it at a repository. Izri derives an initial scope config from the file tree, which you can then export to .izri/scope.yml.

How a diff finds its project

Both the CLI and the webhook resolve in the same order:

1. an explicit --project <id> / project-id input
2. IZRI_PROJECT_ID
3. auto-match — owner/repo from the git origin remote, compared against the projects your token can see

The CLI deliberately uses the same comparison the webhook does, so a run you trigger locally and a check triggered by a push agree about which project they belong to.

When auto-match fails

Three usual causes:

• No origin remote, or one that isn't GitHub. Pass --project explicitly.
• The token belongs to a different organization. A token only sees projects in its own organization, and a cross-organization lookup surfaces as NOT_FOUND rather than a permission error. Run list_projects (MCP) or check the dashboard to see what your token can actually reach.
• The repository isn't bound to a project yet.

Multiple projects, one repository

Not supported. A repository maps to one project. For a monorepo, model the boundaries with modules in .izri/scope.yml rather than splitting into separate projects.

Related

• Organizations and roles — who can do what.
• API tokens — how the CLI and Action authenticate.