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

# Connect GitHub

> Grant the hosted Nodal MCP read-only access to your context repo — the default is the Nodal GitHub App, with a read-only token as an alternative.

The hosted Nodal MCP endpoint serves your **context repo** — the Markdown + YAML your analyst
curates — to your team's agents. To do that, it needs to **read** that repo. That's the entire
access footprint: read-only, GitHub-only, and revocable at any time.

<Note>
  **Nodal never needs access to your database.** Warehouse SQL still runs through your own read-only
  connector. [See exactly what we access →](/mcp/data-access)
</Note>

You can grant read-only access two ways. The onboarding flow defaults to the **Nodal GitHub App**.

## Install the Nodal GitHub App

From the [Nodal admin](https://aiden.nodaldata.io):

1. Open **Settings → Connect repository** and select **GitHub**.
2. Click **Install GitHub App**. You'll be redirected to GitHub's installation screen.
3. Choose the **organization** (or personal account) that owns your context repo.
4. Under **Repository access**, select **Only select repositories** and pick your
   analytics-context repo. *(Optional: also select your dbt project repo to enable the lineage
   connector.)*
5. Review the read-only permissions and click **Install**. GitHub returns you to the Nodal admin
   with the connection confirmed.

<Note>
  You must have **organization ownership or admin permissions** on the repo to install the app. If you
  don't, GitHub sends an install **request** to an org owner, who approves it once — after that the
  repo appears in Nodal.
</Note>

<Tip>
  Scope the app to **only the repositories Nodal needs**. You can add or remove repos later without
  reinstalling — see [Manage repository access](#manage-repository-access).
</Tip>

## Permissions

The Nodal GitHub App requests the **minimum read-only** scopes needed to serve your context — and
**no write access of any kind**.

| Permission | Access    | Why                                                                              |
| ---------- | --------- | -------------------------------------------------------------------------------- |
| `metadata` | Read-only | Basic repository information (default for every GitHub App)                      |
| `contents` | Read-only | Read the Markdown + YAML context files (and dbt files, if you connect that repo) |

Nodal cannot open branches, push commits, create pull requests, or trigger deployments. Contrast
this with a docs or CI app, which needs write scopes — Nodal deliberately does not.

## Manage repository access

The app installation is managed entirely from **your** GitHub org, so you stay in control:

* **Add or remove repos:** in GitHub, go to **Settings → GitHub Apps → Nodal → Configure** and edit
  the selected repositories. Changes take effect immediately.
* **Review activity:** GitHub logs every action the app takes under the app's installation.
* **Revoke access:** from the same **Configure** screen, click **Uninstall**. Nodal loses all
  access the moment you do — no token to hunt down or expire.

## Prefer a token instead?

If your org would rather manage the credential directly, you can skip the app and paste a
**read-only personal access token (PAT)** instead:

1. In GitHub, create a **fine-grained personal access token** scoped to your context repo (and,
   optionally, your dbt repo) with **Contents: Read-only**.
2. In the [Nodal admin](https://aiden.nodaldata.io), choose **Use a token instead** and paste it.

The access footprint is identical — read-only, GitHub-only. The only difference is that **you** hold
and rotate the token, whereas the GitHub App has no token to rotate. Most teams prefer the app.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Nodal can't see my repo after installing">
    Confirm the repo is in the app's **selected repositories** (GitHub → **Settings → GitHub Apps →
    Nodal → Configure**). If you installed on a personal account but the repo lives in an org — or
    vice versa — reinstall against the account that owns the repo.
  </Accordion>

  <Accordion title="The install button sent a request instead of installing">
    You don't have owner/admin rights on that GitHub org. An org owner needs to approve the pending
    install request once; then the repo appears in the Nodal admin.
  </Accordion>

  <Accordion title="Answers stopped reflecting recent context changes">
    The endpoint reads your repo; make sure your latest changes are **pushed** to the connected
    branch. If access looks broken, uninstall and reinstall the app from GitHub's **Configure**
    screen to refresh the connection.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="What Nodal can access" icon="shield-check" href="/mcp/data-access">
    The full access footprint — and what Nodal can never touch.
  </Card>

  <Card title="Share with your team" icon="users" href="/mcp/share-with-your-team">
    The `.mcp.json` file to hand out once you're connected.
  </Card>
</CardGroup>