---
title: Projects and repositories
description: Connect the GitHub App, bind repositories to projects, and understand how Izri resolves which project a diff belongs to.
order: 20
---

# 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`](/docs/configure/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`](/docs/configure/scope-yml) rather than splitting into separate projects.

## Related

- [Organizations and roles](/docs/configure/organizations-and-roles) — who can do what.
- [API tokens](/docs/configure/api-tokens) — how the CLI and Action authenticate.