Buoy GitHub App

The Buoy GitHub App runs the same open-source scanner on every pull request automatically. It posts a review with a deterministic issues table and committable inline fix suggestions, and can add a short summary or coaching paragraph written by an LLM. Findings are always deterministic.

Quick Setup

1. Install the Buoy GitHub App from the GitHub Marketplace
2. Select the repositories you want to monitor
3. Open a PR — Buoy scans automatically and posts a review

That's it. No workflow files, no configuration, no API keys needed.

How It Works

The GitHub App runs the same @buoy-design/scanners and @buoy-design/core engine that powers the CLI. When a PR is opened or updated:

1. Buoy scans the changed files for design drift
2. Posts a GitHub PR review with a summary and issues table
3. Adds committable suggestions for supported high-confidence fixes, and in some cases a short LLM-written summary
4. Creates a check run (pass/fail) based on configured thresholds

PR Review Format

The PR review includes an issues table with a Fix column that distinguishes between verified token matches and suggested new tokens:

## 🛟 Buoy Design Review

### Summary
3 design drift issues found in this PR.

<details>
<summary>Issues Table</summary>

| File | Line | Issue | Severity | Fix |
|------|------|-------|----------|-----|
| Card.tsx | 12 | Hardcoded color #3b82f6 | warning | 🎯 var(--color-primary) |
| Card.tsx | 31 | Hardcoded spacing 24px | warning | 🎯 var(--spacing-lg) |
| Modal.tsx | 8 | Hardcoded radius 8px | info | 💡 --radius-md |

</details>

Fix Column Indicators

• 🎯 Verified match — The fix maps to an existing design token in your system. Safe to apply immediately.
• 💡 Suggested token — Buoy suggests a new token name that doesn't exist yet. Consider extracting this value into a new token.

The app also posts committable inline suggestions for high-confidence fixes.

Two Modes

Established Mode (Maturity ≥50)

For teams with mature design systems. Enforcement tone with a summary and detailed issues table.

Builder Mode (Maturity <50)

For teams early in their design system journey. Coaching tone that identifies repeated patterns and helps you build tokens. "You're using this blue in 4 places — that's your primary."

CLI and GitHub App

• CLI: Local deterministic scanning, fix suggestions, and project checks under the MIT license.
• GitHub App: Hosted pull-request reviews and checks, committable suggestions where supported, and LLM-written summaries and coaching.

Pricing: The first 100 GitHub App installs are free for life. After that, Team is $49 a month per design system, with no seats, and public repos stay free. See pricing, and the privacy page for what the app sends where.

Design health badge

Every repository the GitHub App scans gets a live score badge for its README:

[![design health](https://api.buoy.design/badges/OWNER/REPO.svg)](https://buoy.design)

Green at 80 and above, yellow at 60, red below. It reflects the latest scan within five minutes. The first-scan issue Buoy opens includes the snippet with your repository filled in.

Dashboard

The GitHub App includes access to the Buoy Dashboard at app.buoy.design:

• Repository list with health scores (0-100%, color-coded)
• Per-repo view: issues, design graph (tokens + components)
• Settings: enable/disable checks, set severity, configure ignored paths
• Scan history and drift trends over time

Configuration

You can configure Buoy's behavior via the dashboard or a .buoy.yaml file in your repo:

# .buoy.yaml
checks:
  hardcoded-color: error
  hardcoded-spacing: warning
  arbitrary-tailwind: error
  inline-style: warning
  magic-number: info

ignore:
  - "**/*.test.tsx"
  - "src/legacy/**"

CLI Authentication

To manage your Buoy Cloud account from the CLI, use buoy ahoy:

buoy ahoy login      # Authenticate with Buoy Cloud
buoy ahoy status     # Check account and connection status
buoy ahoy github     # Connect GitHub from the CLI

See buoy ahoy for the full command reference.

Related

• buoy drift — CLI drift detection commands
• Configuration — .buoy.yaml options
• Health Scoring — How scores work