> For the complete documentation index, see [llms.txt](https://docs.upriverdata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.upriverdata.com/integrations/github.md).

# Github

Github integration guide for Upriver

## Connecting GitHub to Upriver

Upriver requires limited, read-only GitHub access so the agent can analyze your codebase and provide accurate insights related to your data pipelines, transformations, and operational logic. By reading the relevant repository contents, Upriver can help identify issues, debug pipeline behavior, and enhance end-to-end understanding of how your code generates and processes data.

You can connect GitHub in one of two ways:

| Method                                       | Best for                                                                        |
| -------------------------------------------- | ------------------------------------------------------------------------------- |
| **Upriver GitHub App** (recommended)         | Organizations that want secure, scoped access without managing a personal token |
| **Fine-grained personal access token (PAT)** | Users who cannot install apps on the org, or who prefer token-based auth        |

***

### Option A: Connect via the Upriver GitHub App (recommended)

The GitHub App is the preferred method. Upriver receives short-lived installation tokens automatically—no personal access token to create, rotate, or paste.

#### 1. Start the integration in Upriver

1. In Upriver, go to **Settings → Integrations**.
2. Click **Add integration** and choose **GitHub**.
3. On the connect step, click **Install GitHub App**.

#### 2. Install the app on GitHub

1. GitHub opens the installation flow for the **Upriver** app.
2. Choose the **organization** (or personal account) that owns the repositories Upriver should analyze.
3. Under **Repository access**, select **Only select repositories** and pick the repositories you want Upriver to access.
4. Review the requested permissions (read-only repository access) and click **Install** (or **Authorize**).

#### 3. Return to Upriver

1. After installation, GitHub redirects you back to Upriver.
2. Wait for the **GitHub App connected** confirmation.
3. Click **Go to integrations** and complete any remaining setup steps in the wizard.

**Notes**

* You do not need to enter a token or repository URLs when the GitHub App is connected; Upriver discovers access from the installation.
* To add or remove repositories later, use **Install GitHub App** again (or manage the installation under your GitHub organization’s **Settings → GitHub Apps**).

***

### Option B: Connect via a fine-grained personal access token

Use this path if you cannot install the Upriver GitHub App on your organization, or if your security policy requires a personal access token.

#### 1. Access your personal settings

1. In the upper-right corner of any GitHub page, click your profile picture.
2. Select **Settings** from the dropdown menu.

#### 2. Navigate to developer settings

1. In the left sidebar, click **Developer settings**.
2. Under **Personal access tokens**, select **Fine-grained tokens**.

**Tip:** You can also go directly to the [Generate new fine-grained personal access token](https://github.com/settings/personal-access-tokens/new) page.

#### 3. Generate a new token

Click **Generate new token**.

#### 4. Configure the token

| Field                      | Guidance                                                                    |
| -------------------------- | --------------------------------------------------------------------------- |
| **Token name**             | Use a descriptive name (e.g. `upriver-agent-access`).                       |
| **Expiration**             | Choose an expiration date. Shorter durations provide better security.       |
| **Description** (optional) | Add a brief note about the token's purpose.                                 |
| **Resource owner**         | Select the organization containing the repositories Upriver should analyze. |

#### 5. Set repository access and permissions

**Repository access**

* Select **Only select repositories** (recommended).
* Choose only the repositories that you want Upriver to access.

**Permissions**

Under **Repository permissions**, set:

| Permission        | Access         |
| ----------------- | -------------- |
| **Contents**      | Read and Write |
| **Metadata**      | Read-only      |
| **Deployments**   | Read-only      |
| **Pull requests** | Read and Write |

These are the only permissions Upriver requires for PAT-based access.

#### 6. Finalize token creation

1. Click **Generate token**.
2. **Important:** The token value (beginning with `github_pat_...`) will be displayed only once. Copy it immediately and store it securely.
3. If you lose it, you'll need to generate a new token.

#### 7. Enter the token in Upriver

1. In Upriver, go to **Settings → Integrations** and add or edit your **GitHub** integration.
2. If you are not using the GitHub App, enter the token and repository URLs in the finalize step, as prompted in the UI.
3. Save the integration.

***

### Choosing between the two methods

* **Prefer the GitHub App** when your org allows it: clearer scope, no long-lived PAT in Upriver, and easier revocation from GitHub's app settings.
* **Use a fine-grained PAT** when app installation is blocked or you need a user-owned credential instead of an org app installation.

For in-product setup, use **Settings → Integrations → GitHub**.