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

# GitHub

> Read code, pull requests, and issues from GitHub during investigations. Optional write-back for issues and PR comments.

Connect GitHub so Foggy can correlate incidents with recent code changes, find related issues and PRs, and read CI/CD history. Optionally, let Foggy file issues and comment on PRs based on an investigation's findings.

## What Foggy can do

**Read (default):**

| Tool                           | Description                                       |
| ------------------------------ | ------------------------------------------------- |
| **Repos**                      | Read repository contents and recent commits       |
| **Issues**                     | Search and read issues                            |
| **Pull requests**              | Search and read PRs, including diffs and comments |
| **Actions**                    | Read workflow runs and CI status                  |
| **Code security / Dependabot** | Read vulnerability alerts and Dependabot findings |

**Write (opt-in, only when **Enable write tools** is on):**

| Foggy can                   | Foggy cannot                         |
| --------------------------- | ------------------------------------ |
| Create and update issues    | Push code or create branches         |
| Comment on issues and PRs   | Create, update, or delete files      |
| Review PRs (leave a review) | Merge pull requests                  |
|                             | Create or fork repositories          |
|                             | Trigger GitHub Actions workflow runs |

The "cannot" list is enforced server-side via a GitHub MCP `GITHUB_EXCLUDE_TOOLS` deny-list, not by the token scope alone — even a token with broad write permissions cannot push code through Foggy.

## Setup

Go to **Connectors** → **Add Connector** → **GitHub** and fill in the form.

| Field                     | Required | Description                                                                                                                                         |
| ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**                  | Yes      | Label for this connector (e.g. "GitHub-Prod")                                                                                                       |
| **Personal Access Token** | Yes      | Fine-grained token with read access to **Contents**, **Actions**, **Issues**, and **Pull requests**. Use a service account, not a personal account. |
| **Enable write tools**    | No       | Off by default. Turn on only if you want Foggy to file issues or comment on PRs. Also add write access to Issues and Pull requests on the token.    |

<img src="https://mintcdn.com/foggy/8tZsXWR7yHUB9nRp/images/github_connector.png?fit=max&auto=format&n=8tZsXWR7yHUB9nRp&q=85&s=424102c4b1349e06cadf6ecb89656771" alt="GitHub connector setup form" width="3420" height="1900" data-path="images/github_connector.png" />

<Info>
  **Read-only by default.** Turning on **Enable write tools** does not unlock destructive operations (push, merge, repo create). Those are blocked regardless of token scope.
</Info>

## Troubleshooting

* **403 on any tool** — the token is missing a required scope. Re-issue with Contents, Actions, Issues, and Pull requests at minimum.
* **Empty results on a private repo** — fine-grained tokens require per-repository access grants. Confirm the repo is listed in the token's repository access.
* **"Foggy wanted to file an issue but couldn't"** — **Enable write tools** is off, or the token lacks write scope on Issues. Enable the checkbox and re-issue the token.
* **Rate-limit errors** — GitHub caps unauthenticated calls low. Always use a token, not anonymous access.

## Next steps

<CardGroup cols={2}>
  <Card title="Sentry" icon="bug" href="/integrations/sentry">
    Pair GitHub with Sentry to link errors to recent commits.
  </Card>

  <Card title="Kubernetes" icon="server" href="/integrations/kubernetes">
    Connect your cluster to correlate deploys with live pod state.
  </Card>
</CardGroup>