CI and pull requests

The PR comment is the point. Every comment is read by every reviewer, in context, at the moment it matters.

The action

.github/workflows/crust.yml

name: crust

on: pull_request

permissions:
  contents: write        # push snapshots to perf-history
  pull-requests: write   # post the comment

jobs:
  crust:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - run: npx next build
      - uses: moumen-soliman/crust/action@main
        with:
          working-directory: .
          baseline: main

It fetches snapshot history, runs the check, posts or updates one comment, and publishes the new snapshot. The Next production build happens before the action because crust reads its output; the action never changes how the application is bundled.

What fails without configuration

Once a comparable baseline exists, no budget file is required for strict regressions:

a route became less static
a new uncached read appeared
a route stopped emitting a static shell

Those are statements about direction against the project’s own previous build, not guessed thresholds. crust ci exits non-zero when one is detected.

New routes are not regressions. A transition involving unknown is reported but not assigned a direction. Different bundlers, Next.js majors, or snapshot schemas are not compared.

Add project-specific ceilings

Create .perf/budgets.json at the workspace root for limits crust cannot choose for you:

.perf/budgets.json

{
  "defaultFirstLoadBytes": 250000,
  "firstLoadBytes": {
    "/products/[slug]": 180000
  },
  "maxGrowth": 0.05,
  "defaultMinShellRatio": 0.6,
  "minShellRatio": {
    "/checkout": 0.8
  },
  "allowRegression": ["/admin/[...slug]"]
}

allowRegression exempts only automatic rendering-mode, cache, and shell-disappearance checks for the named route. Explicit byte, growth, and shell-ratio ceilings still apply.

See the regression model for the certainty rules and the budgets reference for every field.

The comment

### crust: `/products/[slug]` is no longer static

**`/products/[slug]`**

- rendering: **static → partial**
- static shell: **100% → 45%**
- Cause: `uncached fetch at lib/http.ts:3`
- Introduced by: `<ProductGallery>`

**Failing check**

- `/products/[slug]` — rendering mode dropped static -> partial

The comment carries a hidden  marker so the action updates the existing one instead of stacking a new comment on every push. Regressions receive prose and source blame; improvements and neutral changes stay behind a disclosure. If the builds are incomparable, no route deltas are printed. crust ci exits non-zero on a breach.

Snapshot history

A fresh CI checkout has no .perf/ directory, so the baseline lives on an orphan branch:

npx @moumen/crust history fetch   # pull snapshots into .perf/
npx @moumen/crust history push    # publish this build's snapshot

An orphan branch shares no history with your code, so it can grow and be truncated freely without polluting git log or complicating rebases.

Fork pull requests get the comment but skip the push. A fork’s GITHUB_TOKEN is read-only on the base repository, so history push reports and exits cleanly rather than failing the check. Diffs still work from whatever snapshots the branch already holds.

Run the check without the action

npx @moumen/crust history fetch
npx @moumen/crust ci main --comment crust-comment.md
npx @moumen/crust history push

This is useful on other CI providers. --comment writes Markdown only; posting it is the CI provider’s responsibility.

Retention

npx @moumen/crust prune

Full fidelity for the newest 50 builds, then one snapshot per commit, then module detail dropped after 90 days. Route totals and shell ratios are kept forever — they are tiny, and they are what anyone looks at a year later.

Getting started

Concepts

Guides

Reference

CI and pull requests

The action

What fails without configuration

Add project-specific ceilings

The comment

Snapshot history

Run the check without the action

Retention

​The action

​What fails without configuration

​Add project-specific ceilings

​The comment

​Snapshot history

​Run the check without the action

​Retention

The action

What fails without configuration

Add project-specific ceilings

The comment

Snapshot history

Run the check without the action

Retention