CrossCheck/ docs

Adding your first repo

A repo in CrossCheck is a connection to one GitHub repository plus the checks that run on its PRs.

Add the repo

From your org, click Repos → New repo. You'll see:

  • A dropdown of repositories the CrossCheck GitHub App can see. Pick one.
  • A name field (defaulted to the repo's GitHub name — leave it).
  • A short description (optional).

Click Create. You land on the repo's overview page.

If the dropdown is empty, the GitHub App either isn't installed yet or isn't scoped to any repos. See Installing the GitHub App.

Automatic suggestions on your first repo

For the first repo you add to an org, CrossCheck immediately runs the Suggest checks agent against your default branch. The agent clones your repo into a sandbox, reads the manifest files and a representative slice of source, and proposes 5–20 candidate checks tailored to your stack — things like "every new Alembic migration has a non-trivial downgrade()" or "API handlers under /routes log structured request ids."

While the agent runs (typically 1–3 minutes) you'll see a Review N suggestions button appear on the repo's Checks tab. You can close the browser and come back later — the run continues server-side and the button waits for you.

For subsequent repos in the same org, you trigger this manually with the Suggest checks button on the Checks tab. The reasoning: by the time you're adding your second repo you already have a library of check groups built up, and you may want to reuse one rather than generate a fresh proposal.

Reviewing the suggestions

Click Review N suggestions to open the picker dialog. Each suggestion shows:

  • The check name and description.
  • A Grounded on line listing the file paths the agent cited as evidence. Use these to sanity-check whether the suggestion actually applies to your code — cheap-tier models occasionally confabulate, and the cited paths are the fastest way to spot it.

Tick the suggestions you want. At the bottom of the dialog you choose where to save them:

  • Existing group — pick one of your org's existing check groups from the dropdown.
  • New group — type a name and description for a new group.

Click Add N checks. The selected suggestions become real checks; the unselected ones are dropped. You can re-run Suggest checks any time to generate a fresh proposal.

The new check group isn't automatically attached to the repo. Open the Checks tab and click Attach on the group to make it run on this repo's PRs. This separation is intentional — you might want to attach the group to several repos at once, or to none until you've reviewed the checks more carefully.

Writing your own checks

Open any check group from /<your-org>/check-groups and click Add check. A check is:

  • A name (short, kebab-case is conventional but anything works).
  • A description written like a code-review note: "Production code under src/ must not contain print() statements. Use the logger from src/observability/logger.py instead."

The reviewer agent reads the description on every PR and answers pass, fail, or needs_review, with file:line evidence. See Writing good checks for description patterns that work well and ones that don't.

Trigger your first review

With at least one check group attached, open a PR against the repo (or push a new commit to an existing PR). Within a few seconds:

  • A CrossCheck check appears on the PR with status in_progress.
  • The check links to a live run page on CrossCheck where you can watch checks complete.

When the run finishes, CrossCheck posts a single sticky comment on the PR with the per-check results and updates the check to success / failure / neutral.

If a PR was opened before you finished adding checks, click Re-review on the PR's CrossCheck page to run against the current head commit.

Two ways to manage repo config

Everything on the Settings and Checks tabs can be configured two ways:

  1. In the dashboard — point-and-click, takes effect immediately.
  2. In cross-check.yaml at the root of your repo — config-as-code, reviewed alongside your code, version-controlled.

The YAML file can also declare repo-local checks that live next to the code they guard. Dashboard-attached check groups always run alongside YAML checks — the file can add, not subtract. See cross-check.yaml for the full schema.

Next