@variel/brand-check

GitHub composite action that runs the Variel on-brand conformance check on every pull request. Scores changed .ts/.tsx/.js/.jsx/.css files against your active brand, posts a summary comment, and sets a commit status (variel/on-brand).

Consumer workflow (copy-paste)

Create .github/workflows/brand-check.yml in your repository. The CLI is self-contained — no checkout, no pnpm, no monorepo. It fetches the PR's changed files via the GitHub API, so the only steps are Node + npx:

name: Brand Check

on:
  pull_request:
    types: [opened, synchronize, reopened]

# statuses: write      — to post the variel/on-brand commit status
# pull-requests: write — to upsert the summary comment
# contents: read       — to fetch per-file content via the GitHub contents API
permissions:
  statuses: write
  pull-requests: write
  contents: read

jobs:
  brand-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: >
          npx --yes -p @variel/brand-check@latest variel-brand-check
          --min-score 80
          --variel-url https://variel.ai
        env:
          VARIEL_API_KEY: ${{ secrets.VARIEL_API_KEY }}
          GITHUB_TOKEN: ${{ github.token }}

GITHUB_REPOSITORY, GITHUB_SHA, and GITHUB_EVENT_PATH are set automatically by GitHub Actions; you only pass VARIEL_API_KEY and GITHUB_TOKEN.

Add VARIEL_API_KEY to Settings → Secrets and variables → Actions in your GitHub repository. The value is the API key shown in your Variel project dashboard.

Prefer a one-liner? The composite action in this repo (.github/actions/brand-check) wraps the same npx call with typed inputs and defaults — reference it as uses: <owner>/<repo>/.github/actions/brand-check@main.

Input reference

| Input | Required | Default | Description | |-------|----------|---------|-------------| | api-key | yes | — | Your Variel API key (VARIEL_API_KEY). Must be passed via with: — GitHub does not forward secrets into composite actions automatically. | | min-score | no | "80" | Minimum overall brand score (0–100). A passed:false hard-block from a contract violation cannot be overridden by raising this floor. | | variel-url | no | "https://variel.ai" | Base URL of the Variel API. Override for staging/dev environments. |

Behavior summary

• Key absent / 401 / 404 (unbound) — sets status to pending with a "bind your project key" hint comment. Check does not block the PR.
• Network failure / 5xx (unreachable) — sets status to failure with a "couldn't reach Variel" message distinct from a brand failure.
• No in-scope files changed — sets status to success, comment says "nothing eligible to check".
• On-brand — sets status to success with score.
• Off-brand or hard contract violation — sets status to failure, lists per-file violations in the PR comment. Hard blocks (passed:false) fail even at min-score: 0.

GET /api/brand-by-key endpoint contract

This is the observable API contract consumed by the action. You do not call this endpoint directly; the action wires it automatically.

Request

GET https://variel.ai/api/brand-by-key
Authorization: Bearer <api_key>

The API key travels only in the Authorization header — never in the URL or query string.

Responses

200 OK — active brand found

{
  "data": { /* BrandObject — design tokens, voice, components */ },
  "projectId": "proj_abc123",
  "version": 1
}

401 Unauthorized — missing, malformed, or empty Authorization header.

{ "error": "Unauthorized" }

404 Not Found — key is valid but no active brand is linked to it, or the key does not correspond to any project.

{ "error": "Not found" }

The action maps both 401 and 404 to the unbound path (neutral pending status). 5xx and network errors map to unreachable (failure status).