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 on Pro tier adds AI-powered summaries and committable inline fix suggestions.

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. On Pro tier, adds AI-powered summaries and committable inline fix suggestions
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.

On Pro tier, you also get committable inline suggestions that you can apply with one click in the GitHub UI.

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."

Free vs Pro Tier

• Free: Deterministic issues table with 🎯/💡 Fix column (file, line, issue, severity, fix). GitHub check run (pass/fail).
• Pro: Everything in Free, plus AI-powered summaries, committable inline fix suggestions, coaching in builder mode, and custom review instructions.

Auto-Pro for early adopters: Teams who install the Buoy GitHub App during early access are automatically upgraded to Pro tier for free. No credit card required.

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