The GitHub App, then the project

Install the App first

Hive talks to GitHub through a GitHub App installation — that is how it reads your code, posts commit statuses, and receives the webhooks that start runs. The App is public: you install it on your own account or organisation, and it issues a per-installation token scoped to the repositories you selected.

The install link is https://github.com/apps/<slug>/installations/new, where the slug comes from your instance's /api/v1/config as github_app_slug. The onboarding wizard renders it as a button; if it shows "ask your operator" instead, the instance has not been configured with its App slug and an operator has to set that before any tenant can self-serve.

Install it on the account that owns the repository — a personal account for a personal repo, the organisation for an org repo. Grant it only the repositories you want Hive to run.

Then register the project

register_project    # or POST /api/v1/projectslist_projects       # what is already registered

A project is a name plus a repo_url. Registration is a *database* action: it does not install the App, and it does not check that an installation exists. That is why the order matters — the two steps look independent and are not.

Installations belong to one tenant

The first tenant to bind an installation keeps it. If an installation is already bound elsewhere, Hive does not silently move it: the binding is an operator action, deliberately, so that a reinstall cannot transfer a repository between tenants by accident.

Verifying it actually worked

The honest check is a delivery, not a settings page. Push a commit and look for a run:

list_runsget_onboarding_state

If nothing appears, the usual causes are: the App is installed on a different account than the one owning the repo; the repository was not included in the installation's repository selection; or the project's repo_url does not match the repository the webhook is coming from.