# GitHub connection (/docs/github)

Okae uses a GitHub App to receive PR updates and publish results. Choose which repositories the installation can access.

## Install and select repositories [#install-and-select-repositories]

Open the [GitHub App installation page](https://github.com/apps/okae-ai/installations/new), choose your organisation and select **Only select repositories**. An organisation owner may need to approve the request.

Confirm service access with [hello@okae.ai](mailto:hello@okae.ai) before expecting results. GitHub installation grants repository access; service activation is a separate step.

## Permissions [#permissions]

Review the current permissions shown by GitHub during installation. The router uses Checks and Pull requests write access to publish checks and comments. Approval reviews also need Contents write access because GitHub requires the App to have push access for its approval to count.

The organisation connection flow requires Members read access to verify organisation ownership. GitHub may ask an owner to accept updated App permissions. A permission request doesn't enable approval mode by itself.

## Change repository access [#change-repository-access]

In your organisation's GitHub settings, open **Installed GitHub Apps**, choose Okae and configure its repository selection. Add or remove the repositories you want the App to access.

A selected repository still needs service access. In real mode, Okae's dashboard uses the management API to verify current organisation-owner access and show installation state and accessible repositories. The separate fixture preview uses sample data and doesn't change GitHub access.

Public dashboard hosting and verification of the hosted sign-in and installation flow are still pending. Use GitHub's installation settings to manage repository selection and confirm access with Okae.

## Stop processing [#stop-processing]

An authorised organisation owner can suspend or uninstall Okae from the organisation's installed GitHub Apps settings.

To keep results but prevent future approval reviews, set `enable_approvals: false` in `okae.yml` on the relevant base branch, or ask Okae to disable approvals for the service. Changing a setting doesn't itself revoke an approval already submitted to GitHub. Review existing approvals and branch rules separately.

See [troubleshooting](/docs/troubleshooting) if an expected repository or result is missing.