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

# GitHub App integration

> What the Driftless GitHub App watches on your PRs and pushes, and how it keeps context from going stale.

The GitHub App is what lets Driftless watch the work as it happens. Once it is installed on your repositories, it reads the pull requests and pushes going by, surfaces what the team already recorded about the files you touched, and marks a topic as drifted the moment its files change.

<Note>
  The GitHub App is a **different surface** from a GitHub Broker Connection. This App (`type: github`) is an observation surface: it watches PRs and pushes to drive drift and feed the Auditor, and it exposes no `invoke`. A GitHub Broker Connection (`type: nango:github`) for write operations like creating an issue is **not shipped**. See [Integrations and Connections](/integrations/overview#provider-availability).
</Note>

## Installation

Install from the dashboard:

<Steps>
  <Step title="Open GitHub Integration settings">
    Go to **Settings > GitHub Integration** in the dashboard.
  </Step>

  <Step title="Start installation">
    Click **Install on GitHub**. You'll be redirected to GitHub's app installation flow.
  </Step>

  <Step title="Select repositories">
    Choose the account or organization, then select specific repositories. You can expand access later from the same settings page.
  </Step>

  <Step title="Return to dashboard">
    GitHub redirects you back. Driftless auto-links the installation to your workspace by matching the org name or existing repos.
  </Step>
</Steps>

## What the app does

### PR observation

On `pull_request.opened`, `synchronize`, `reopened`, and `ready_for_review` events:

1. Fetches the list of changed files via the GitHub API
2. Matches each file against all workspace topic patterns using glob intersection
3. **Records** every PR↔topic match (powers the dashboard's PR activity) and **queues the Auditor**

The only comment Driftless posts is the **Auditor's**, and only when it has a finding. When it does, the affected topics' recorded context (gotchas, decisions, invariants, stale flags) rides along with it. A clean PR, or a workspace without the Auditor configured (no model key), gets no comment. See [PR Comments](/concepts/pr-bot).

The comment **informs; it never blocks**. Findings land as proposals a human approves. It is updated in place on new commits, never re-posted.

### Push staleness

On `push` events to tracked branches (default branch plus any custom branches):

1. Matches changed files against topics using glob pattern intersection
2. Marks matching topics as **stale** with a reason (e.g., "3 files changed in commit abc1234")

Add custom tracked branches:

```bash theme={"theme":"github-light"}
driftless branches add staging
```

### PR comment format

```text theme={"theme":"github-light"}
<!-- driftless-auditor -->
## 🔎 Driftless Auditor

This change may affect 1 thing the team recorded. Queued for review.
These are proposals; a human approves.

- `auth-boundaries` (needs a human): new route bypasses the workspace guard

### What the team already knows

#### `auth-boundaries`: workspace-scoped auth
**Gotchas**
- All endpoints require auth; do not add @Public() without review
```

The HTML marker (`<!-- driftless-auditor -->`) lets Driftless find and update the comment on subsequent pushes.

## Permissions

| Permission        | Level        | Reason                                |
| ----------------- | ------------ | ------------------------------------- |
| **Contents**      | Read         | Fetch changed files in PRs and pushes |
| **Pull requests** | Read & write | Post and update the Auditor's comment |
| **Issues**        | Read & write | PR comments use the Issues API        |
| **Metadata**      | Read         | Required by GitHub for all apps       |

The app never clones your repository and never reads secrets or environment files.

## Deactivation

Remove the integration from **Settings > GitHub Integration**, or uninstall the app directly on GitHub. The `installation/deleted` webhook automatically deactivates the integration in your workspace.

<Note>
  The CLI works without the GitHub App. Auditor PR comments and push-driven staleness require the app to be installed.
</Note>