Roll Gryndel out to your team

This guide takes you from "Gryndel works" to "the team uses it every day", whether your code is on GitLab or GitHub. You start with one pilot repository, choose safe starting settings, tell the team what to expect, watch the first week, then adjust and widen. Plan on about an hour of setup and ten minutes a day for the first week.

Before you start

• You're a workspace admin in Gryndel. By default, GitLab Owners and Maintainers of the group are admins, and on GitHub the account's owner, or an organization's owners. See Members and roles.
• On GitLab, you have the Maintainer role on the pilot project. Gryndel adds its webhook using your own GitLab access.
• On GitHub, Gryndel's GitHub App is installed on the account, with access to the pilot repository. Nothing else is needed: the App's webhook already covers every repository it can see.
• A model provider is set up and System health shows it as ready. If your workspace doesn't exist yet, see Create a workspace.

1. Pick a pilot repository

Start with one repository, not every repository in the GitLab group or GitHub account. A pilot lets you tune settings before a noisy week puts people off.

Choose a repository that…	Why
Gets several merge requests (GitLab) or pull requests (GitHub) a week	You need enough reviews to judge Gryndel in a week.
Has a team that is open to trying it	Early feedback (👍, 👎, replies) is what you tune with.
Is ordinary application code	Generated code, vendored libraries or huge data files make early results look worse than they are.
Isn't your most critical code	Save payments or authentication for later, with stricter settings.

Avoid a repository that is about to freeze or migrate, or one whose merge or pull requests are mostly automated dependency updates.

2. Choose starting settings

Open Repositories, click Configure on the pilot repository, and set these. Each one is explained on the Findings tab and the tabs next to it.

Tab	Setting	Start with	Why
Reviews	Review mode	Verified · draft and verify (the built-in default)	A second step checks every finding before it's posted, so fewer false alarms. Try Agents · specialist reviewers later.
Findings	Comment level	💬 Chat (the default)	Only used in Agents mode. Chat adds at most three suggestions.
Findings	Min. severity to publish	P2 · all findings (the default)	During the pilot you want to see everything, to judge quality. Raise it later if it's too chatty.
Findings	Suggested fixes	Suggest fixes (the default)	One-click suggestions in GitLab or GitHub. Leave Suggest and apply fixes (GitLab only) until the team trusts Gryndel.
Findings	Fail commit status on	Never fail for the first week, then P0 findings	Nobody is blocked by a tool they've never seen. Switch to P0 findings once the team has seen a week of results.
Scope	Excluded paths	Generated and vendored code, for example vendor/**, **/generated/**, **/*.min.js	Gryndel wastes time and money reviewing code nobody writes by hand.

Click Save settings. The settings apply to reviews created from now on.

Teach Gryndel the repository first

On the Profile tab, click Learn this repository. Gryndel proposes a short description of the code's layout and conventions as a merge or pull request. Merge it (after correcting anything wrong) and reviews follow it. See Learn a repository.

If your team already has written conventions, add the most important ones as rules now. See Write a rule that works. Keep it to a handful; you can add more once you see what Gryndel misses.

3. Turn it on

GitLab

1. On Repositories, tick the pilot repository.
2. Click Enable selected. If GitLab asks you to allow Gryndel to make changes as you, allow it, then click Enable now.
3. Check that the Webhook column says configured (or existing) and Reviews says Enabled.

GitHub

1. On Repositories, tick the pilot repository. If it isn't listed, add it to the App's installation on GitHub (the account's Settings → GitHub Apps, or Applications on a personal account, then Configure), and click Refresh repositories in Gryndel. Gryndel also reads the list again when you open the page and its copy is more than 15 minutes old.
2. Click Enable selected. Gryndel doesn't change anything on GitHub.
3. Check that the Webhook column says configured and Reviews says Enabled.

Gryndel also picks up merge or pull requests that are already open, so they get reviewed within a few minutes.

Check it worked: open a small test merge or pull request (a draft is fine). Shortly afterwards Gryndel posts Gryndel is reviewing this merge request (or pull request), and the review appears on Pull requests. If nothing happens, see A review never starts.

4. Tell the team

People react better to a bot when they know it's coming and what it wants from them. Post something like this in your team channel. Change the bits in brackets.

Starting [Monday], Gryndel will review [merge/pull] requests in [repository] as a trial.

- It posts as [the "Gryndel" user / gryndel-acme[bot]]: one progress comment, a summary,
  and a thread per finding.
- For the first week it never blocks a merge. Treat its comments like a colleague's.
- If a finding is right: fix it and resolve the thread, or click
  ["Apply suggestion" / "Commit suggestion"].
- If it's wrong: reply "@gryndel ignore this" in the thread, or react 👎. That's how we tune it.
- Not sure? Reply "@gryndel explain" in the thread.
- Want a fresh look after pushing? Comment "@gryndel review".
- "@gryndel help" lists everything else.

Questions and complaints to [name]. We'll review how it went on [date].

On GitHub, use the name your Gryndel's GitHub App comments as (it ends in [bot]), so people recognise it.

Point developers at Respond to Gryndel's findings, which covers their side in more detail.

5. Watch the first week

Spend a few minutes each day on these:

Where	What to look for	What it tells you
Pull requests, status filter failed	Failed reviews	Model or connection problems. Fix them and replay; see Investigate a review.
Pull requests, Status column	How long reviews take	Developers stop waiting for a review that takes longer than their CI.
A few merge or pull requests in GitLab or GitHub	Replies and reactions on Gryndel's threads	Whether people find the findings useful, and which ones annoy them.
Reports	Acceptance, and Held back by Gryndel	Accepted versus dismissed or disputed findings. Acceptance only counts merge or pull requests that are merged or closed, so it fills in over the week.
Costs	Total cost	Whether the spend is in line with what you expected.

Ask two or three developers directly at the end of the week. A quick "what was useful, what was noise?" tells you more than any chart.

6. Adjust, then widen

Use what you saw to tune the settings:

You saw	Do this
Too many comments, or too many wrong ones	Follow Make Gryndel quieter and more accurate.
Real problems it missed, specific to your code	Add rules. See Write a rule that works.
Reviews too slow or too expensive	See Control costs.
Findings are mostly accepted	Set Fail commit status on to P0 findings, so critical issues block.

Widen the rollout when acceptance looks healthy and the team isn't complaining:

1. Put the settings that worked into Organization settings (at the top of the Repositories page), so every repository starts from them. See How settings combine.
2. Turn on reviews for the next few repositories with Enable selected. You can select up to 100 at a time.
3. Repeat the announcement for each new team.

If something goes wrong during the rollout, you can stop reviews for one repository or the whole workspace without losing anything. See Pause reviews.