> ## 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](/docs/ona/integrations/github-pr-mentions).

The GitHub integration uses the Ona GitHub App. It is separate from [GitHub source control](/docs/ona/source-control/github), 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](/docs/ona/automations/webhooks) 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](/docs/ona/integrations/github-pr-mentions#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. Sessions already running keep running. New sessions start again only when the App is reinstalled.

## Next steps

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