GitHub Actions

Add Buoy to your CI pipeline to catch design drift before it's merged. Get PR comments with health scores and specific issues.

Quick Setup

Create .github/workflows/buoy.yml:

name: Design System Check

on:
  pull_request:
    branches: [main, master]

jobs:
  buoy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Run Buoy
        run: npx @buoy-design/cli ci --threshold 60

With PR Comments

Add a comment to each PR with the health report:

name: Design System Check

on:
  pull_request:
    branches: [main, master]

permissions:
  pull-requests: write

jobs:
  buoy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Run Buoy
        run: npx @buoy-design/cli ci --threshold 60 --github-comment
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

PR Comment Example

The PR comment looks like:

## 🚢 Buoy Design System Check

**Health Score: 67/100** (Fair)

### Summary
- 23 hardcoded color values
- 14 non-standard spacing values
- 3 possible typos detected

### Files Changed in This PR
| File | Issues |
|------|--------|
| src/pages/Dashboard.tsx | 12 new issues |
| src/components/Card.tsx | 5 new issues |

### Suggested Fixes
- `#3b83f6` → `#3b82f6` (typo in Dashboard.tsx:14)
- `15px` → `16px` (use spacing token in Card.tsx:28)

---
*Run `buoy audit` locally for full report*

Configuration Options

Threshold

Set a minimum passing score:

# Fail if score below 70
npx @buoy-design/cli ci --threshold 70

# Zero tolerance - fail on any drift
npx @buoy-design/cli ci --strict

Compare Against Base Branch

Only report new issues introduced in the PR:

- name: Run Buoy
  run: npx @buoy-design/cli ci --compare-base origin/main

Monorepo Setup

For monorepos, specify the path:

- name: Run Buoy
  run: npx @buoy-design/cli ci --threshold 60
  working-directory: ./packages/web

Caching

Speed up runs with caching:

- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

- name: Install dependencies
  run: npm ci

- name: Run Buoy
  run: npx @buoy-design/cli ci --threshold 60

Multiple Frameworks

If you have multiple apps in a monorepo:

jobs:
  buoy:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        app: [web, admin, mobile]
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci
        working-directory: ./apps/${{ matrix.app }}

      - run: npx @buoy-design/cli ci --threshold 60
        working-directory: ./apps/${{ matrix.app }}

Troubleshooting

Token Not Found

If you get permission errors, ensure:

permissions:
  pull-requests: write

No Issues Detected

Verify Buoy can find your files:

npx @buoy-design/cli scan --json

Related