# GitHub
URL: https://docs.clearly-ai.com/docs/integrations/code/github
Description: Connect Clearly AI to GitHub.
## Overview [#overview]

Connect GitHub so Clearly AI can use your repositories as project context and review the code in them.

An admin sets up the GitHub integration once for the workspace with one of two authentication methods:

* **Shared API Token**: a GitHub fine-grained personal access token.
* **OAuth 2.0**: signing in to GitHub, plus the Clearly AI GitHub App.

For help choosing between them, see [Which method should you use?](#which-method-should-you-use).

## Set up GitHub [#set-up-github]

### Prerequisites [#prerequisites]

* Access to **Integrations** in **Organization settings**
* A GitHub account that can access the repositories you want Clearly AI to review. For the workspace connection, a bot or service account keeps the connection from depending on one employee's account.

<Steps>
  <Step>
    ### Open the GitHub integration [#open-the-github-integration]

    In Clearly AI, open **Organization settings**, select **Integrations**, then click **Set up** on the GitHub card.
  </Step>

  <Step>
    ### Choose an authentication method [#choose-an-authentication-method]

    Under **Authentication**, select **Shared API Token** or **OAuth 2.0**.

    #### Option A. Shared API Token [#option-a-shared-api-token]

    1. In GitHub, [create a fine-grained personal access token](https://github.com/settings/personal-access-tokens/new). Select the organization and repositories Clearly AI should access, and grant **Contents** and **Pull requests** read and write. GitHub adds **Metadata** read automatically.
    2. Paste the token into **Shared API Token**.

    #### Option B. OAuth 2.0 [#option-b-oauth-20]

    <Note>
      Only the owner of the GitHub account, or an owner of the GitHub organization, can install the Clearly AI GitHub App on its repositories.
    </Note>

    1. Check **I understand** under the shared-credential notice, then click **Connect**. **Connect** stays disabled until you check it. Sign in to GitHub if prompted, and approve Clearly AI's access request.
    2. Install the [Clearly AI GitHub App](https://github.com/apps/clearly-ai-app/installations/new) on the organization or account that owns the repositories, and grant it access to those repositories.

    <Callout>
      Clearly AI shows a green **Connected** label as soon as you sign in to GitHub, before it has found a Clearly AI GitHub App installation. **Connected** doesn't mean repository access works. Install the App before you add the credential.
    </Callout>
  </Step>

  <Step>
    ### Add the credential [#add-the-credential]

    Check **I understand** under the shared-credential notice if you haven't already, then click **Add workspace credential**. Clearly AI tests the credential and enables the integration only when the test passes. Projects can then add GitHub repositories as sources.
  </Step>
</Steps>

To change the token or the GitHub account later, click **Configure** on the GitHub card, open the **Connections** tab, click **Edit authentication**, then click **Apply and test**.

People can also connect their own GitHub account as a &#x2A;*Personal (User)** connection: open **Customize**, go to the **Yours** tab, and click **Connect** on GitHub. GitHub appears there only after an admin installs its connector. Sources and Workflows that run as that person use their personal connection. A personal connection reaches only repositories where the Clearly AI GitHub App is installed, so install the App there first.

## Which method should you use? [#which-method-should-you-use]

| Method               | Best when                                                                                          | Notes                                                                       |
| -------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| **Shared API Token** | You want the quickest setup and prefer to manage the token yourself                                | Access is limited to the repositories and permissions granted to that token |
| **OAuth 2.0**        | You want GitHub to handle signing in and grant repository access through the Clearly AI GitHub App | Requires the App installed on the repositories                              |

## GitHub App and GitHub user permissions [#github-app-and-github-user-permissions]

OAuth 2.0 combines two separate pieces of GitHub access. Both are required, and each does a different job:

| Piece                                         | Grants                                                                                                 | Configured by                                                                                                                                                                                  |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Clearly AI GitHub App** install             | Which organizations, accounts, and repositories Clearly AI can read (for example, repository contents) | The personal account owner, or a GitHub organization owner for org-owned repositories, from the [Clearly AI GitHub App install page](https://github.com/apps/clearly-ai-app/installations/new) |
| **GitHub user** who signs in with **Connect** | Which of those App installations Clearly AI can see and use                                            | The person who signs in through OAuth in Clearly AI                                                                                                                                            |

Neither piece alone is enough:

* The App install without a connected GitHub user leaves Clearly AI with no signed-in identity to look up the installation.
* A connected GitHub user without the App install leaves Clearly AI with no repository permissions. GitHub App permissions come from the App's install configuration, not from OAuth consent scopes, so signing in doesn't grant repository access by itself.

For a &#x2A;*Shared (Workspace)** connection, use a dedicated GitHub bot or service account to sign in, instead of a personal account. This keeps the connection working if the employee who set it up changes teams or leaves.

## Which GitHub account writes a wiki page [#which-github-account-writes-a-wiki-page]

The **Upsert GitHub Wiki Page** workflow tile publishes a review to a GitHub wiki. GitHub stores wiki pages in a separate git repository, so Clearly AI clones that repository and pushes the page with a GitHub token.

Clearly AI picks the token from the person who created the workflow:

* Their &#x2A;*Personal (User)** GitHub connection, when they have one.
* Otherwise the &#x2A;*Shared (Workspace)** GitHub connection.

GitHub accepts the push when that GitHub account can write to the repository and the Clearly AI GitHub App is installed there. The App install chooses which repositories Clearly AI may open. The connected GitHub account still needs its own write permission on the repository.

To publish to a repository that account can't write to, connect a GitHub account with write access. Use the workflow creator's &#x2A;*Personal (User)** connection, or the &#x2A;*Shared (Workspace)** connection when the creator has no personal one.

## Refresh a repository on a project [#refresh-a-repository-on-a-project]

Clearly AI keeps the commit it downloaded until you refresh the source. To pick up later commits, open the project, open **Manage Sources**, and choose **Refresh source** on the branch. When processing finishes, re-run the review. See [Update a review when sources change](https://docs.clearly-ai.com/docs/reviews#update-a-review-when-sources-change).

## FAQs [#faqs]

<Accordions>
  <Accordion title="Why does Clearly AI reject my Shared API Token?">
    Confirm the token is still active, covers the repositories Clearly AI needs, and grants **Contents** and **Pull requests** read and write.
  </Accordion>

  <Accordion title="Why does Connect do nothing?">
    Check whether your browser is blocking pop-ups or redirects for Clearly AI.
  </Accordion>

  <Accordion title="Why are some repositories missing after OAuth 2.0 succeeds?">
    Confirm that the GitHub account you authorized can access those repositories and that any required SSO or organization approval has been completed.
  </Accordion>

  <Accordion title="Why does OAuth show Connected but the credential or repository links fail?">
    **Connected** confirms GitHub sign-in succeeded, not that the Clearly AI GitHub App is installed. [Install the App](https://github.com/apps/clearly-ai-app/installations/new) and grant it access to the target repositories, then click **Add workspace credential** again, or add the repository or pull request link again. See [GitHub App and GitHub user permissions](#github-app-and-github-user-permissions) for details.
  </Accordion>

  <Accordion title="Why does the Organization dropdown only show one org after I installed the GitHub App?">
    The dropdown lists only the organizations and accounts where the Clearly AI GitHub App is installed. If you need repositories from your personal account as well as an organization, install the App separately on your personal account from the [Clearly AI GitHub App install page](https://github.com/apps/clearly-ai-app/installations/new). Your personal account then appears as its own entry in the Organization dropdown.
  </Accordion>

  <Accordion title="Is Personal (User) OAuth the same as the Shared (Workspace) GitHub connection?">
    No. A Shared (Workspace) OAuth connection and a Personal (User) OAuth connection are independent. Expanding personal OAuth access does not change the shared connection's repository scope, and the reverse is also true.
  </Accordion>

  <Accordion title="Why does Clearly AI need both a GitHub App install and a connected GitHub user?">
    They grant different things. The Clearly AI GitHub App install grants repository permissions. The connected GitHub user is the identity Clearly AI uses to look up which App installations it can use. See [GitHub App and GitHub user permissions](#github-app-and-github-user-permissions).
  </Accordion>

  <Accordion title="Should I connect a personal GitHub account or a service account?">
    For a &#x2A;*Personal (User)** connection, connect your own account. For a &#x2A;*Shared (Workspace)** connection, use a dedicated GitHub bot or service account so the connection doesn't depend on one employee's account.
  </Accordion>

  <Accordion title="Why does Upsert GitHub Wiki Page return 403 Write access to repository not granted?">
    The tile pushes as the GitHub account in [Which GitHub account writes a wiki page](#which-github-account-writes-a-wiki-page). GitHub returns that 403 when the account cannot write to the repository.
  </Accordion>
</Accordions>

## Related [#related]

* [Integrations](https://docs.clearly-ai.com/docs/integrations) - Choose an authentication method for an integration
* [Concepts](https://docs.clearly-ai.com/docs/concepts) - Learn how integrations provide project context in Clearly AI