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

# Connecting GitHub

> Connect GitHub to ClarityQ through the GitHub MCP server, with each teammate signing in through a GitHub App your organization owns.

Connecting GitHub lets ClarityQ's agent read repositories, files, issues and pull requests while answering your questions. The connection runs through the **GitHub MCP server**, added to ClarityQ as an [MCP connector](https://docs.clarityq.ai/integrations/mcp/connecting-mcp-servers.md). Each teammate signs in with their own GitHub account, so ClarityQ sees only what that person can see, and only in the repositories your GitHub admin picked.

GitHub does not let ClarityQ register itself as an app, so your organization creates the app once and gives ClarityQ its client ID and secret. No personal access tokens are involved.

| | |
| - | - |
| **Remote MCP server URL** | `https://api.githubcopilot.com/mcp/` |
| **Authentication** | Users sign in with your OAuth app |
| **You need** | A GitHub App that your GitHub organization owns |

Three parts, in this order:

1. A **GitHub organization owner** creates a GitHub App and installs it on the repositories ClarityQ may read.
2. A **ClarityQ admin** adds the GitHub connector with the app's client ID and secret.
3. **Each teammate** connects their own GitHub account.

## Create the GitHub App

> [!NOTE]
>
> Before you start, open **Organization Settings → MCP → Add Connector** in ClarityQ, enter a name and the GitHub MCP server URL, `https://api.githubcopilot.com/mcp/`, and click **Continue**. Copy the **Redirect URL** shown there: you need it in the steps below.

**1. Open the GitHub App form**

In GitHub, open your organization's **Settings → Developer settings → GitHub Apps** and click **New GitHub App**.

**2. Name it and set the callback URL**

* **GitHub App name:** for example `ClarityQ`.
* **Homepage URL:** `https://app.clarityq.ai`
* **Callback URL:** paste the **Redirect URL** you copied from ClarityQ.

Keep **Expire user authorization tokens** on. ClarityQ renews the tokens by itself.

**3. Turn off the webhook**

Under **Webhook**, clear **Active**. ClarityQ does not receive events from GitHub.

**4. Choose the permissions**

Under **Repository permissions**, set what ClarityQ may do. For reading documents and code:

| Permission | Access |
| - | - |
| Contents | Read-only |
| Metadata | Read-only |

Add **Issues** or **Pull requests** as Read-only if your team asks about those.

**5. Create the app and its secret**

Under **Where can this GitHub App be installed?**, keep **Only on this account**, then click **Create GitHub App**.

With this setting, GitHub lets only members of the organization that owns the app sign in. Create the app in your organization, not in a personal account: an app in a personal account works for its owner only.

On the app's page, copy the **Client ID**, then click **Generate a new client secret** and copy the secret. GitHub shows it once.

**6. Install the app on your repositories**

Open **Install App** in the app's left menu, click **Install** next to your organization, and choose **Only select repositories**. Pick the repositories ClarityQ may read.

## Add the GitHub connector in ClarityQ

A ClarityQ admin does this once. Open **Organization Settings → MCP** and click **Add Connector**.

**1. Name the connector**

For example, `GitHub`.

**2. Paste the GitHub MCP server URL and continue**

In **Remote MCP server URL**, enter:

```
https://api.githubcopilot.com/mcp/
```

To expose only tools that read, use `https://api.githubcopilot.com/mcp/readonly` instead. Click **Continue**.

**3. Paste the app's client ID and secret**

ClarityQ finds that GitHub needs an OAuth app and selects **Users sign in with your OAuth app**, marked **Detected**. **Users sign in** is greyed out, because GitHub's server doesn't support it. Paste the **Client ID** and **Client secret** from GitHub. Leave **Scopes** empty: a GitHub App takes its access from the permissions you set on it.

**4. Click Add**

The connector appears in the list. Teammates now see it as an **App**.

## Connect your GitHub account

Each teammate connects individually.

**1. Open Settings → Apps**

Find the GitHub app in the list. See [Using Apps](https://docs.clarityq.ai/integrations/mcp/using-mcp-servers.md) for the full Apps page.

**2. Click Connect**

A new window opens on GitHub's authorization screen. Sign in if prompted and approve. GitHub redirects back to ClarityQ and the app shows **Connected**.

**3. Turn the app on in a chat**

In a chat, click **+ → Apps** and switch on GitHub. ClarityQ can now use GitHub tools in that conversation.

## Using a GitHub OAuth App instead

A GitHub App is the better fit: its access is limited to chosen repositories and permissions, and its tokens expire. If your organization prefers a classic OAuth App, create one under **Settings → Developer settings → OAuth Apps** with the same callback URL.

In ClarityQ, fill **Scopes**. Left empty, ClarityQ requests every scope GitHub's server lists, and that list includes write access (`repo`, `write:packages`, `project`, `gist`). Type only what you want to grant, for example `repo read:org`.

If your organization restricts third-party OAuth apps, an owner must approve the app under **Settings → Third-party Access → OAuth app policy**.

## Using one access token instead

If one shared credential is enough, you can skip the app. In the connector form choose **Shared headers** and add one header:

| Header | Value |
| - | - |
| `Authorization` | `Bearer <your-token>` |

Everyone in your organization then uses GitHub with that token's access, and nobody signs in personally. Use a fine-grained token limited to the repositories ClarityQ may read. If your organization blocks personal access tokens, use the GitHub App above.

## Troubleshooting

### GitHub says the redirect URI is not associated with this application

The app's **Callback URL** in GitHub differs from the **Redirect URL** ClarityQ shows. Copy it again from the connector form and paste it into the GitHub App's settings, exactly.

### Connect opens a GitHub "Not Found" page

**For everyone:** the **Client ID** in the connector does not match a GitHub App. Edit the connector under **Organization Settings → MCP** and paste the client ID again.

**For some users only:** GitHub does not let them sign in to the app. An app set to **Only on this account** accepts only members of the GitHub organization that owns it, and an app in a personal account accepts only its owner. Choose one:

* Add the user to the GitHub organization that owns the app.
* If the app is in a personal account, move it to the organization: in the app's settings, open **Advanced → Transfer ownership**. The client ID and secret stay the same.
* If people outside the organization need to connect, open **Advanced** and click **Make public**. They still see only the repositories their own GitHub account can access.

### Connected, but ClarityQ cannot find a repository

ClarityQ can read a repository only when both are true: the GitHub App is installed on it, and your own GitHub account has access to it. Ask your GitHub organization owner to add the repository under the app's **Install App → Configure**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.