# GitHub Integration

Connect Brizz to GitHub so issues are traced back to the code behind them, sized by their impact, and fixed with a pull request you approve.

Connect Brizz to your GitHub organization so that issues Brizz detects in your AI agent are traced to the code that causes them. Brizz reads the repository behind a service to explain what went wrong, estimate what fixing it is worth, and — when you ask — propose a fix and open a pull request for your team to review.

## Why Connect GitHub?

Telemetry shows *what* your agent did. The code shows *why*. With both, Brizz can answer questions that traces alone cannot:

- **Root cause analysis**: Brizz follows an issue from the failing conversations into the code and explains the cause in plain terms, pointing at the files and logic involved.
- **Where the problem lives**: Brizz tells you which layer is at fault — the agent harness (prompts, tool definitions, orchestration logic), the LLM itself (model behavior or model choice), the infrastructure (timeouts, rate limits, failing dependencies), or something else, such as a downstream API or bad input data. You know who should own the fix before anyone starts digging.
- **Impact analysis**: Brizz measures how far an issue reaches — how many sessions, users, and organizations it touches, and which user intents and business outcomes it puts at risk.
- **Predicted gains**: Before you commit engineering time, Brizz estimates what fixing an issue is worth — the sessions it would recover, the quality and success-rate lift, the latency and performance improvement, and the cost it would save — so you can rank issues by return, not by volume.
- **Resolve with AI**: For issues with a code-level fix, Brizz proposes the change, shows you the diff and the reasoning behind it, and opens a pull request once you approve it. Brizz then tracks the pull request's checks, review, and merge status, so you can see in Brizz when the fix ships.
- **GitHub issues**: If an admin chooses GitHub as your issue tracker, Brizz creates GitHub issues from Brizz issues, with the affected sessions and a link back to Brizz.

## How to Connect

1. Navigate to **Settings > Integrations** in the Brizz dashboard
2. Click **Connect GitHub**
3. Sign in to GitHub. Brizz uses this sign-in to confirm you belong to the organization you are connecting
4. Install the **Brizz Bot** GitHub App on your organization and choose which repositories it can access. We recommend **Only select repositories**, limited to the repositories that hold your agents' code
5. Return to Brizz to complete the setup

Then, for each service you want analyzed:

1. Open the service's **Settings > Integrations > Resolve with AI**
2. Pick the repository, base branch, and (for a monorepo) the directory that holds the service's code

Brizz only analyzes code for services that have a repository mapped. A service with no mapping is never read.

## How It Works

Each analysis is a single, isolated run started by a user from an issue in Brizz:

- **Read access is scoped per run.** Each run uses a GitHub installation token limited to read-only access to the single mapped repository. GitHub expires these tokens after one hour.
- **Analysis is ephemeral.** The repository is cloned into a single-use sandbox created for that run only. The sandbox is destroyed when the run ends, together with the clone.
- **Writes happen only on your approval.** Brizz never changes your repository on its own. A pull request is opened only after a user reviews the proposed diff and clicks approve. Brizz always works on a new branch: it never pushes to existing branches, and it never merges. Merging stays with your team, under your existing review rules and branch protections.

## Security and Data Handling

This section is intended for security teams reviewing the integration before approval.

### What Brizz stores

**Brizz does not store your source code.** The repository exists only inside the sandbox for the duration of a run and is discarded with it.

Brizz keeps only what is needed to operate the integration and show you its results:

| Data | Why it is kept |
| --- | --- |
| The GitHub App installation (installation ID, organization name) | To link your Brizz workspace to your GitHub organization |
| Repository mapping per service (repository, base branch, directory) | To know which repository to analyze for which service |
| The connecting user's GitHub sign-in credential | To confirm organization membership when connecting |
| The analysis result: root cause, summary, and the proposed change | To show the analysis in Brizz and let you review a fix before approving it |
| Pull request reference (branch name, PR number, URL) | To link the issue in Brizz to the pull request in GitHub |

### Access control

- **Tenant isolation**: Every installation, mapping, and analysis result belongs to a single Brizz workspace and is never visible to another.
- **Admin-controlled scope**: Only organization admins in Brizz can map repositories to services. Your GitHub organization admins decide which repositories the app can see at all.
- **User-initiated only**: Analyses and pull requests are started by an authenticated Brizz user. Every run records who started it.
- **Webhook verification**: Every webhook from GitHub is verified with an HMAC-SHA256 signature before it is processed.

### GitHub App permissions

When you install the Brizz Bot app, GitHub asks you to grant the following:

| Permission | Access | Why we need it |
| --- | --- | --- |
| Metadata | Read | List the repositories and branches you can map to a service |
| Contents | Read & write | Read the code for analysis; push the branch that holds an approved fix |
| Pull requests | Read & write | Open the pull request for an approved fix, and track the review and merge status of pull requests Brizz opened or that are linked to Brizz issues |
| Issues | Read & write | Create GitHub issues from Brizz issues, when an admin chooses GitHub as the issue tracker |
| Checks | Read & write | Track the check results on pull requests Brizz opened or that are linked to Brizz issues, so their status shows in Brizz |
| Actions | Read | Track the CI workflow runs on pull requests Brizz opened or that are linked to Brizz issues |
| Commit statuses | Read | Track the commit statuses on pull requests Brizz opened or that are linked to Brizz issues |

Although the app holds write access to contents, the token used for analysis is narrowed to read-only on one repository. Write access to contents is used only to push the branch of a fix a user has approved.

### Disconnecting

1. Go to **Settings > Integrations**
2. Find the GitHub integration card
3. Click **Disconnect**

Disconnecting deletes the installation record, every repository mapping, and the stored GitHub sign-in credentials for your workspace. To revoke access fully on the GitHub side, uninstall the Brizz Bot app from your organization's **Settings > GitHub Apps**. Pull requests Brizz already opened stay in your repository.

## See also

- [Issues](/docs/platform/issues.md) — where the issues that GitHub analysis explains come from.
- [Issue trackers](/docs/integrations/issue-trackers.md) — track the fix in Linear or Monday alongside the pull request.
- [Jira](/docs/integrations/jira.md) — create a Jira ticket from the same issue.

---

[All Brizz documentation](https://docs.brizz.ai/llms.txt) · [Full documentation (single file)](https://docs.brizz.ai/llms-full.txt)