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

# GitHub

Connect GitHub to Athena to browse repositories, read code, issues, and pull
requests in chat, power the GitHub toolkit, and inject a short-lived token into
computer environments — all without pasting a personal access token.

<Info>
  You connect GitHub live in the UI. Each repository you connect becomes a
  catalog you can open in Drive, reference in chat with `@`, and use with
  Athena's tools and agents.
</Info>

## What connecting GitHub unlocks

* **Browse and read** repository contents in Drive, and read files, issues, and
  pull requests directly in chat.
* **GitHub toolkit** in any session — list directories, read files, and more,
  with no secret to paste.
* **Computer environments** — inject a scoped `GITHUB_TOKEN` into a computer so
  the developer agent can use `git`, the `gh` CLI, and the GitHub API.

## Choose how you connect

Athena supports four connection methods. **We recommend GitHub App — OAuth for
most teams** — it gives each member their own GitHub identity through a quick
in-browser sign-in, with fine-grained, org-approved repository access and
automatic token rotation. Pick whichever your organization's GitHub policies
allow — you can set up more than one (for example, a GitHub App plus a fallback
token).

| Method                                   | How you sign in                              | Best for                                                                             |
| ---------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------ |
| **GitHub App — OAuth**  ·  *Recommended* | Authorize in a GitHub popup                  | The default "sign in with GitHub" experience, with per-user identity and permissions |
| **GitHub App — Installation**            | No sign-in; a shared, org-approved app token | A workspace-wide service connection with fine-grained, org-approved repo access      |
| **OAuth App**                            | Authorize in a GitHub popup                  | Organizations that use classic OAuth Apps instead of GitHub Apps                     |
| **Personal Access Token**                | No sign-in; one shared token                 | Organizations that don't allow GitHub Apps or OAuth Apps                             |

Setup is two steps: **set up the connection** once, then **connect your
repositories**.

## Step 1 — Set up the connection

In Athena, open **Integration Definitions**
(**[Workspace Settings → Treasury → Integration Definitions](https://app.athenaintel.com/dashboard/workspace-settings/treasury/?tab=integration-definitions)**),
click **New integration**, and choose provider **GitHub**. Then follow the tab
for the method you picked above.

For every method that uses a GitHub App or OAuth App, the **callback URL** is:

```
https://api.athenaintel.com/api/github-direct/oauth/callback
```

<Tabs>
  <Tab title="GitHub App — OAuth (Recommended)">
    **On GitHub**

    1. Create a GitHub App: **Organization settings → Developer settings →
       GitHub Apps → New GitHub App**.
    2. Set **Callback URL** to
       `https://api.athenaintel.com/api/github-direct/oauth/callback`.
    3. Enable **"Request user authorization (OAuth) during installation"** and
       **"Expire user authorization tokens"** (recommended — this gives Athena
       rotating refresh tokens).
    4. Under **Repository permissions**, grant **Read** for **Contents**,
       **Pull requests**, **Issues**, and **Metadata** (add write scopes only
       if you need them later).
    5. **Install** the App on your organization and choose which repositories it
       may access.
    6. Copy the **Client ID** and generate a **Client secret**.

    **In Athena**

    Set **Auth method** to `oauth2`, paste your **Client secret** into the
    **Client secret** field, and use this config:

    ```json theme={null}
    {
      "name": "GitHub OAuth",
      "authorization_url": "https://github.com/login/oauth/authorize",
      "access_token_url": "https://github.com/login/oauth/access_token",
      "scopes": [],
      "connection": { "client_id": "<your client id>" }
    }
    ```

    Leave `scopes` empty — a GitHub App's access is defined by the repository
    permissions you granted when installing it, not by OAuth scopes.
  </Tab>

  <Tab title="GitHub App — Installation">
    **On GitHub**

    Use a GitHub App (create one as in the OAuth tab, or reuse an existing one).
    OAuth does **not** need to be enabled for this method.

    1. **Install** the App on your organization and choose which repositories it
       may access.
    2. Copy the **App ID**.
    3. Note the **Installation ID** — the number in the installation's settings
       URL (`.../installations/<installation id>`).
    4. Generate a **private key** and download the `.pem` file.

    **In Athena**

    Set **Auth method** to `github_app`, paste the full contents of the `.pem`
    into the **App private key (PEM)** field, and use this config:

    ```json theme={null}
    {
      "name": "GitHub App",
      "app_id": "<your app id>",
      "installation_id": "<your installation id>",
      "connection": {}
    }
    ```

    This is a shared workspace connection: everyone uses the app's
    org-approved access, and no individual sign-in is required.
  </Tab>

  <Tab title="OAuth App">
    **On GitHub**

    1. Create an OAuth App: **Organization settings → Developer settings →
       OAuth Apps → New OAuth App**.
    2. Set **Authorization callback URL** to
       `https://api.athenaintel.com/api/github-direct/oauth/callback`.
    3. Copy the **Client ID** and generate a **Client secret**.

    (Organization access may require approval under your **Third-party
    application access policy**. Tokens from a classic OAuth App do not expire.)

    **In Athena**

    Set **Auth method** to `oauth2`, paste your **Client secret** into the
    **Client secret** field, and use this config:

    ```json theme={null}
    {
      "name": "GitHub OAuth",
      "authorization_url": "https://github.com/login/oauth/authorize",
      "access_token_url": "https://github.com/login/oauth/access_token",
      "scopes": ["repo", "read:org", "read:user"],
      "connection": { "client_id": "<your client id>" }
    }
    ```

    Unlike a GitHub App, an OAuth App's access is defined by **scopes** —
    request the ones your team needs.
  </Tab>

  <Tab title="Personal Access Token">
    **On GitHub**

    Create a **fine-grained personal access token** (recommended), scoped to
    your organization and repositories with **Read** access to **Contents**,
    **Pull requests**, **Issues**, and **Metadata**. A classic token with the
    `repo` scope also works. Because this token is shared across the workspace,
    a service account is recommended over a personal account.

    **In Athena**

    Set **Auth method** to `pat`, paste the token into the **Personal access
    token** field, and use this config:

    ```json theme={null}
    {
      "name": "GitHub PAT",
      "connection": {}
    }
    ```

    Rotate the token any time by re-saving the secret — it lives only on the
    integration and is never copied elsewhere.
  </Tab>
</Tabs>

<Tip>
  **GitHub Enterprise Server:** add your host to the config's `connection`
  block (e.g. `"connection": { "host": "https://github.your-company.com" }`)
  and point the OAuth URLs at that origin. The REST base is derived
  automatically as `{host}/api/v3`.
</Tip>

## Step 2 — Connect your repositories

Go to **[Integrations](https://app.athenaintel.com/dashboard/integrations/)** and
click **GitHub → Connect**.

* **OAuth methods** open a GitHub authorization popup, then a repository picker.
* **Installation** and **Personal Access Token** methods skip straight to the
  repository picker.

Select the repositories you want. Each one becomes a catalog you can open in
Drive, reference in chat with `@`, and use with the GitHub toolkit and computer
environments.

<Tip>
  Your credentials are encrypted at rest, and OAuth connections use per-user
  tokens scoped to your own GitHub identity. You can disconnect a repository at
  any time from the Integrations page.
</Tip>