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

# GitHub

> Connect GitHub to CloudThinker for repository, pull request, CI failure, and issue context, and to power Review

Connect your GitHub account to let CloudThinker agents read repositories, pull requests, failing checks, and issues — and to run [Review](/guide/code-review/setup) on the repositories you select. GitHub authenticates through a **GitHub App** installation, so you never paste a token into CloudThinker.

## Prerequisites

* A **GitHub account** with access to the repositories you want CloudThinker to reach.
* Permission to install GitHub Apps — installing to a GitHub organization requires the **Organization Owner** role.
* A CloudThinker workspace where GitHub is not already connected.

<Info>
  The GitHub App requests access to the repositories you select, read and write permissions for pull requests, and webhook events for code review.
</Info>

## Setup

<Steps>
  <Step title="Open CloudThinker">
    Navigate to **Connections → GitHub** in your CloudThinker workspace and click **Connect**.
  </Step>

  <Step title="Install the GitHub App">
    Click **Install GitHub App**. CloudThinker redirects you to GitHub.
  </Step>

  <Step title="Select repositories and authorize">
    Pick the account or organization, choose all repositories or a subset, and approve the installation.
  </Step>

  <Step title="Return to CloudThinker">
    After you authorize, CloudThinker stores the installation and shows a **Connected** status.
  </Step>
</Steps>

<Note>
  The GitHub App registers its own webhooks — no manual webhook configuration is needed.
</Note>

## Connection details

GitHub uses an app installation — there are no connection fields to enter manually.

| Field                       | Description                                                                       |
| --------------------------- | --------------------------------------------------------------------------------- |
| **GitHub App installation** | Created on GitHub during setup and stored automatically; no manual entry required |

## Required permissions

CloudThinker reaches only the repositories you grant during installation.

* **Read operations** cover repositories, pull requests, check and workflow results, and issues.
* **Write operations** such as branch changes and pull request updates require explicit [approval](/guide/approval) in CloudThinker.

<Tip>
  Follow least privilege: grant the app only the repositories CloudThinker should work with. You can change repository access later in GitHub under the app's installation settings.
</Tip>

## Repository access

On top of the GitHub App's installation scope, the connection carries a CloudThinker-side repository policy. Open the connection's detail panel and find **Repository access** under **Settings**:

| Mode         | Behavior                                                                                                        |
| ------------ | --------------------------------------------------------------------------------------------------------------- |
| **All**      | Every repository the installation can reach is listed and readable; new repositories are included automatically |
| **Selected** | Only the repositories you pick are listed and readable; new repositories are excluded until you add them        |

The policy only ever narrows what the installation already grants, and it is separate from choosing which repositories run [Review](/guide/code-review/setup). Switching from **Selected** to **All** and back restores your previous selection.

## Agent capabilities

Once connected, agents can:

| Capability        | Description                                                       |
| ----------------- | ----------------------------------------------------------------- |
| **Repositories**  | List and inspect the repositories the installation covers         |
| **Pull requests** | Review open pull requests, their discussions, and what is blocked |
| **CI failures**   | Investigate failing checks and workflow runs                      |
| **Issues**        | Read issues for delivery and triage context                       |
| **Changes**       | Branch and pull request changes — **requires approval**           |

### Verify the connection

```text theme={null}
@alex list the GitHub repositories CloudThinker can reach and summarize their open pull requests
```

### Example prompts

```text theme={null}
@alex #report which open pull requests across our GitHub repositories are blocked
@alex #recommend a fix for the failing checks on the payments repository
@alex #report this week's merged pull requests and open issues
```

## Write access

Reads run without approval. Any change to a branch or a pull request is approval-gated: CloudThinker states the effect and the exact inputs, then waits for your confirmation before touching the repository.

## Troubleshooting

<Accordion title="Installation does not complete">
  You may be signed in to the wrong GitHub account, or the redirect was interrupted. Sign in to the intended account and restart the connection from **Connections → GitHub**.
</Accordion>

<Accordion title="Cannot install to an organization">
  Installing CloudThinker to a GitHub organization requires the **Organization Owner** role. Ask an owner to install the app, or request installation approval through GitHub.
</Accordion>

<Accordion title="Agent cannot find an expected repository">
  The installation covers only the repositories selected during setup. Open the app's installation settings on GitHub and extend **Repository access** to include the missing repository.
</Accordion>

<Accordion title="GitHub shows as already connected">
  A workspace holds one GitHub connection. Use the existing connection, or remove it before connecting a different account or organization.
</Accordion>

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Scoped installation** — the GitHub App reaches only the repositories you grant; widen or narrow access any time from GitHub's installation settings.
- **Approval for writes** — keep branch and pull request changes approval-gated in CloudThinker.

## Related

<CardGroup cols={2}>
  <Card title="Review Setup" icon="gear" href="/guide/code-review/setup">
    Turn on automated AI code reviews for your GitHub repositories
  </Card>

  <Card title="Provider Authentication" icon="key" href="/guide/code-review/provider-auth">
    Authentication details for every Review provider
  </Card>
</CardGroup>