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:

## 🛟 Buoy Design Review

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

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

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

</details>

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 (file, line, issue, fix token). 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.

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

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