Skip to main content

Change reviews

Beta

Change reviews are in beta. Hyrax support turns them on per workspace — email support@hyrax.dev. Until they are on, nothing about them appears in the app.

A feature rarely lives in one pull request anymore. A change review starts from what was asked — a Linear issue, or a description you write — reads every pull request that delivers it, across every repository, together with their review discussion and the live state of the feature flags they use, and writes one review of the whole change: did it build what was asked, where is it risky, and who sees it today.

Change reviews are advisory. They never post a check run and never block a merge — use them to decide where to look closer. For line-by-line findings on a single pull request, see Pull request review; a change review shows what that review said about each of its pull requests.

Where to find them​

Open Reviews in the sidebar and stay on Change reviews, the first tab. There is one row per change:

ColumnWhat it shows
IssueThe Linear issue key (such as ENG-123), or hx-<n> for a review started in Hyrax
TitleThe issue's or the review's title
Asked vs builtHow many requirements are met
Needs attentionThe most pressing state — Failed, Not met, High risk, Partly met, Needs a person, Running, Queued or Looks good
PRsPull requests in the change, and how many are still open
UpdatedWhen the review last ran

Narrow the list with the tabs (Needs attention, Running, All), the search box (by issue key or title), or Filters: Repository once your reviews come from more than one repository, and Team once they come from more than one team. The team filter also offers Started in Hyrax, for reviews that have no Linear issue.

Getting a review​

There are two ways a change review starts.

Automatically, from a Linear issue​

Once these are in place, Hyrax writes the review on its own within a few minutes of a linked pull request opening:

  1. Connect Linear. A workspace admin saves a Linear API key under Settings → Integrations (see Linear). Hyrax reads each issue with it.
  2. Add your repositories. Hyrax only reads pull requests in repositories you have added.
  3. Link each pull request to the issue. Linear's GitHub integration does this for you. Otherwise, put the issue key in the pull request title, in capitals (ENG-123). Hyrax itself does not link a pull request by a key in its branch name or description, so a description that only mentions an older issue does not start a review of it. Linear's integration can still link the pull request, for example when the description says Fixes ENG-123.

The review is named by the issue key and covers every linked pull request, in every repository. Draft pull requests, pull requests from forks, and pull requests opened by bots are not picked up.

A review started this way stays current on its own: it re-runs when a linked pull request gets new commits, when a new pull request is linked, and when one merges. Editing the Linear issue does not re-run it — the review shows a notice that the ticket changed, with a Rewrite with the current ticket button.

Change reviews are on for every repository by default. To turn them off for one, open that repository's settings and go to PR Review Settings.

By hand, in Hyrax​

Use this when there is no Linear issue, or to review a set of pull requests or branches as one change. On Reviews, with Change reviews selected, click New change review, then choose What to review:

  • Pull requests — give the change a Title and a Description, then paste GitHub pull request links, one per line. The description is what the review checks the pull requests against, the way it would read a Linear issue, so say what the change is for and what "done" looks like.
  • Branches — paste up to 10 GitHub branch links (…/tree/branch-name) or compare links (…/compare/main...branch-name), one per line. Then pick a Linear ticket for the branches to deliver, or write Instructions instead. Branches are compared from the point they diverged, the way a pull request is, and Hyrax reads them on GitHub — work you have not pushed is not reviewed.

Click Start the review. It gets an hx-<n> ID and a Started in Hyrax badge (Started from branches for a review of branches). A review started by hand runs once; it does not re-run on new commits — click Rewrite when you want a fresh one.

No acceptance criteria found

If the review can't find clear requirements to check against, it says No acceptance criteria found. Click Add criteria, list what should be true when the change is done, then click Rewrite.

Reading a review​

Four cards across the top give the verdict at a glance:

CardWhat it tells you
Asked vs builtHow many requirements are Met, Partly met, Not met, or Need a person
Biggest riskThe highest-risk critical path, and how many more there are — or No high-risk paths
Who sees it todayThe feature flags that gate the change, and where they are on
The changeHow many pull requests, how many have merged, and any Hyrax couldn't read

Below them, a plain-language headline and summary that anyone on the team can read, followed by the review's sections. Show sections for switches between Everything, Product and Engineering, so each reader can skip to their part:

  • Asked vs built — each requirement with its status and the pull requests behind it. Unmet items come first; the met ones are folded behind a "n met · Show" toggle.
  • Before and after — what users or admins will notice, side by side.
  • Screens and How it is wired — sketches of the change: what it looks like, and how the system's parts connect.
  • Critical paths — risks rated High, Medium or Low, each with a one-line reason.
  • How it ships — the flags that gate the change and where each one is on, including flags the code reads that don't exist in LaunchDarkly (marked Not in LaunchDarkly).
  • What the Hyrax PR review said — one line per pull request from its pull request review.

The Sources panel lists everything the review read: the Linear issue (or your description), every pull request, the LaunchDarkly flags, the acceptance criteria and any sub-issues. Chips like #1458 throughout the review tie each claim to the pull request it came from — hover or click one to highlight its source.

What the four statuses mean​

StatusMeaning
MetThe pull requests deliver this requirement.
Partly metSome of it is done, but something is missing or still open — for example, a draft pull request.
Not metThe pull requests don't deliver this requirement.
Needs a personHyrax can't tell from the code and discussion alone; a reviewer should check.

Where the summary goes​

A change review is written in Hyrax first. It can also post a short summary to the Linear issue and to each of its pull requests (except a pull request in a public repository, when the change spans other repositories); Hyrax support turns posting on per workspace. The bottom of the review says which happened: Posted to … when it posted, or Summary prepared for … · not posted (dry run) when it didn't. A review started in Hyrax never posts to Linear, and a review of branches posts nothing anywhere.

When something is missing​

  • "Hyrax couldn't read this pull request" — not read (repository not added to Hyrax). The pull request is in a repository Hyrax doesn't have. Add the repository, then click Rewrite.
  • "Some inputs were shortened to fit: …" The change was too large to send in full, so some review discussion or long diffs were left out. The rest of the review stands; check the largest pull requests and the longest threads by hand.
  • "Flag state not checked." Hyrax didn't read LaunchDarkly for this review, so How it ships names the flags the code reads but not whether they're on. Check them in LaunchDarkly. If the lookup failed, Rewrite tries again.

Cost​

Every run counts toward your spend — starting a review, each automatic re-run, and each Rewrite. A single run is capped, and the cap sits under your workspace's own spending limits, never above them. Rewrite when something has actually changed — new criteria, a newly added repository — rather than to refresh the page.

Workspace admins can delete a change review from its page.

From your AI tools​

With the MCP server connected, Claude Code and other AI tools can list your change reviews, find the one covering a branch or pull request, set acceptance criteria, and start a review over pushed branches.