Skip to main content
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.
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.

​
Installation

Install from the dashboard:
1

Open GitHub Integration settings

Go to Settings > GitHub Integration in the dashboard.
2

Start installation

Click Install on GitHub. You’ll be redirected to GitHub’s app installation flow.
3

Select repositories

Choose the account or organization, then select specific repositories. You can expand access later from the same settings page.
4

Return to dashboard

GitHub redirects you back. Driftless auto-links the installation to your workspace by matching the org name or existing repos.

​
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. 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: 
driftless branches add staging

​
PR comment format

<!-- 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

PermissionLevelReason
ContentsReadFetch changed files in PRs and pushes
Pull requestsRead & writePost and update the Auditor’s comment
IssuesRead & writePR comments use the Issues API
MetadataReadRequired 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.
The CLI works without the GitHub App. Auditor PR comments and push-driven staleness require the app to be installed.