Skip to main content

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.

The Driftless GitHub App connects your repositories to your workspace. Once installed, it observes pull requests and pushes, surfaces context on PRs, and tracks drift when files change.

​
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 (using a short-lived installation token)
  2. Matches each file against all workspace topic patterns
  3. Posts a sticky comment listing matched topics with their “what” summary and links to the dashboard
The comment is updated in place on new commits. It is never re-posted.

​
Push staleness

On push events to tracked branches (default branch plus any custom branches):
  1. Matches changed files against topics
  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

​
Installation tracking

The installation ID is linked to your workspace automatically during setup by matching the GitHub organization name or existing connected repos.

​
PR comment format

<!-- driftless-context -->
### Driftless · context for this PR

auth-boundaries applies to: src/auth/session.ts, src/auth/tenant.ts
how: 2 endpoints, 1 service, 1 guard
decisions: Multi-tenant, uses org_id from token
gotchas: All endpoints require auth; do not add @Public() without review
Each matched topic gets its own block. The HTML marker (<!-- driftless-context -->) lets Driftless find and update the comment on subsequent pushes.

​
Permissions

PermissionLevelReason
ContentsReadFetch changed files in PRs and pushes
Pull requestsRead & writePost and update context comments
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. PR comments and push-driven staleness require the app to be installed.