> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> Enable the GitHub integration for one or more GitHub organizations.

This page is for the organization admin who enables the GitHub integration. For end-user usage, see [Mention Ona on a pull request](https://ona.com/docs/ona/integrations/github-pr-mentions.md).

The GitHub integration uses the Ona GitHub App. It is separate from [GitHub source control](https://ona.com/docs/ona/source-control/github.md), which configures repository access for environments.

## Prerequisites

* You are an admin of an Ona organization.
* You use GitHub.com. For GitHub Enterprise Server, use a [webhook event source](https://ona.com/docs/ona/automations/webhooks.md) for pull request triggers.
* You have admin rights on the GitHub.com organization (or personal account) where the App will be installed.

## Enable GitHub

1. In Ona, go to **Organization Settings** > **Integrations**.
2. Find **GitHub** and turn on the switch.
3. GitHub opens. Choose the organization (or your personal account) to install the App on.
4. Choose which repositories the App can access:
   * **All repositories**: the App can be mentioned on every PR in the org.
   * **Only select repositories**: pick a subset. You can change this later from GitHub.
5. Approve the permissions request and finish the install on GitHub.
6. Ona shows the enabled status on the integration page.

## Connect another GitHub organization

Connect each GitHub organization that owns repositories you want to use with Ona.

1. In Ona, go to **Organization Settings** > **Integrations**.
2. Find **GitHub** and click the ellipsis button to open **GitHub organizations**.
3. Click **Install into another GitHub organization**.
4. In GitHub, choose the organization and the repositories the App can access.
5. Approve the permissions request and finish the install.
6. Return to Ona. The organization appears in the **GitHub organizations** dialog.

## Permissions

| Permission | Access | Why |
| - | - | - |
| Pull requests | Read & write | Read PR metadata and post agent status comments. |
| Issues | Read & write | Read and post comments on PRs. GitHub treats PR comments as issue comments. |
| Contents | Read | Look up the repository associated with a PR. |
| Metadata | Read | Required by GitHub for any App. |

If a permission is missing, Ona posts a `[!CAUTION]` comment on the PR:

> Ask an organization admin to update the Ona GitHub App installation and grant read & write access to **issues** and **pull requests**.

To fix it, open the App in GitHub, accept the new permissions, then ask the user to mention the agent again.

## Verify the installation

1. Open a pull request in a repository the App can access.
2. Post a comment containing `@ona-agent`.
3. Within a few seconds, the agent will react to your comment and post a reply with the running session.

If nothing happens, see [Troubleshooting](https://ona.com/docs/ona/integrations/github-pr-mentions.md#troubleshooting).

## Change which repositories the App can access

1. Go to your GitHub organization's **Settings** > **GitHub Apps** > **Ona**.
2. Click **Configure**.
3. Under **Repository access**, add or remove repositories.
4. Save. The change takes effect immediately.

## Disable GitHub

Disable a GitHub organization if you want to stop Ona from responding to PR mentions for that organization without uninstalling the App on GitHub (for example, during a migration or incident).

1. In Ona, go to **Organization Settings** > **Integrations**.
2. Find **GitHub** and click the ellipsis button to open **GitHub organizations**.
3. Turn off the switch for the GitHub organization you want to disable.
4. Click **Done**.

While disabled:

* The App stays installed on GitHub and keeps receiving webhook events for that GitHub organization, but Ona ignores them. No new agent sessions start for `@ona-agent` mentions in repositories owned by that organization.
* Other enabled GitHub organizations keep working.

To resume, open **GitHub organizations** and turn the organization's switch back on.

## Uninstall the App

1. Go to your GitHub organization's **Settings** > **GitHub Apps** > **Ona**.
2. Click **Configure**, scroll to **Uninstall**, and confirm.

Uninstalling stops PR mention triggers for that GitHub organization. When the integration is enabled in Ona, uninstalling also cancels active PR sessions associated with that installation. If the integration is disabled, those sessions may keep running. Sessions using other installations keep running. New sessions start again only when the App is reinstalled.

## Next steps

* [Mention Ona on a pull request](https://ona.com/docs/ona/integrations/github-pr-mentions.md): what users do once GitHub is enabled.
* [GitHub source control](https://ona.com/docs/ona/source-control/github.md): repository access for environments.
* [Integrations overview](https://ona.com/docs/ona/integrations/overview.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.