Respond to Gryndel's findings

This guide is for developers. It follows one merge request (GitLab) or pull request (GitHub) from the moment you open it to the moment you merge, and shows how to deal with Gryndel's comments quickly. How you respond matters: it tells your team which findings are useful, and it's how admins tune Gryndel.

Before you start: to use @gryndel commands you need the Developer role (or higher) on the project in GitLab, or write access to the repository on GitHub. You don't need to sign in to Gryndel at all. In GitLab, Gryndel's comments come from the Gryndel user; on GitHub, from its GitHub App's bot account, whose name ends in [bot].

1. Open your merge or pull request

Open the merge or pull request as usual. Gryndel reviews it automatically, and again after every push. A draft is reviewed too, so you can get early feedback before you ask a person.

Within a moment Gryndel posts one comment:

⏳ Gryndel is reviewing this merge request (commit 1a2b3c4d5e6f, verified review).

You don't need to wait for it. Carry on, and come back when it changes to ✅ Gryndel finished reviewing this merge request. On GitHub it says "pull request" instead. Large changes can take several minutes. To see how far it has got, comment @gryndel status.

2. Read the summary first

The Gryndel review note lists every finding with its severity, so you can see the whole picture before you open any thread.

Severity	Means	Typical response
P0	Critical: a security hole or data loss	Fix it before merging.
P1	Realistic incorrect behaviour: a crash, a wrong result	Fix it, or explain why it can't happen.
P2	A minor real issue	Fix it if it's cheap, otherwise use your judgement.

Check the commit status too. If gryndel/review failed, at least one finding is blocking, and your repository may not let you merge until it's dealt with. On GitHub the status is in the pull request's list of checks. See Read a review in GitLab or GitHub.

3. Work through the threads

Each finding is its own thread on the line it's about. The first line tells you what kind of comment it is, for example:

issue (blocking, security): P1 · Token is logged in plain text

issue is a real problem that a verification step has checked. suggestion, nitpick and question are lighter, and never block.

For each thread, pick one response:

The finding is…	Do this	It counts as
Right, and the suggested fix is right	Click Apply suggestion in GitLab, or Commit suggestion on GitHub. The change is committed to your branch.	Fix applied in GitLab; Resolved on GitHub, once the thread is resolved
Right, and you'll fix it your own way	Fix the code, push, then resolve the thread (or let @gryndel check resolve it; see step 5).	Resolved
Wrong, or doesn't apply here	Reply @gryndel ignore this in the thread.	Dismissed
Wrong, and you want admins to notice	React 👎 on the finding. Add a reply saying why, if you can.	Disputed
Unclear	Reply @gryndel explain in the thread.	No outcome yet
Useful	React 👍.	Positive feedback

Please don't just leave threads open. A thread still unresolved when the merge or pull request is merged counts as Left open, which tells nobody whether the finding was right.

Dismiss a wrong finding

@gryndel ignore this

Write it as a reply in the finding's thread, not as a new comment. On GitHub, that's the Reply box under the finding, on the Conversation tab or the Files changed tab. Gryndel resolves the thread and won't raise that finding again on this merge or pull request, even after you push more commits. It only applies to this one. If the same wrong finding keeps coming back on other merge or pull requests, tell an admin, or teach Gryndel a rule (step 6).

Ask for an explanation

@gryndel explain

Gryndel answers in the thread with more detail, using the code around the finding. You can add a question after it, such as @gryndel explain why can this be null?.

Ask anything else

Anything after @gryndel that isn't a command is a question about the merge or pull request:

@gryndel does this change affect the billing export?

Answers use the model, so they take a little longer than commands.

4. Push your fixes

When you push, Gryndel reviews the new commit automatically. Then:

• The new review posts its own findings, in new threads.
• Gryndel marks its threads from the earlier commit as Outdated: a newer Gryndel review supersedes this commit. This does not prove the issue was fixed.
• Outdated threads that only Gryndel has written in are resolved for you. Threads where someone replied stay open, so a conversation is never closed behind your back.
• A finding you dismissed with @gryndel ignore this isn't posted again.

If a problem is still there in the new commit, the new review normally reports it again. An outdated thread being resolved doesn't mean the problem was fixed.

5. Check your fixes

Before asking a person to review, comment:

@gryndel check

Gryndel re-reads each of its open threads against your latest commit, replies in each one, and resolves the ones you've fixed. It ends with a count, such as "3 resolved, 1 still open". It checks up to 20 threads at a time.

If you want to clear all of Gryndel's threads without checking them, for example after discussing them with your team, comment @gryndel resolve.

6. Teach Gryndel something

If you notice a convention your team always wants, and Gryndel didn't flag it, teach it:

@gryndel learn: API handlers must return errors with the shared ApiError type, so clients get a consistent error format.

It becomes a rule for this repository straight away. Say what to look for and why. See Rules & learnings.

7. Merge

You're ready when:

• every P0 and P1 finding is fixed, or dismissed with a reason;
• the gryndel/review status has passed, if your repository requires it;
• a person has approved, as usual. Gryndel doesn't replace human review.

Common situations

Situation	Do this
A wrong finding is blocking your merge	Reply @gryndel ignore this in its thread, then comment @gryndel review. The new review leaves the dismissed finding out, so the status can pass.
You're mid-refactor and don't want a review on every push	Comment @gryndel pause. Comment @gryndel review when you want one, and @gryndel resume to go back to automatic reviews.
You pushed by mistake and the review is wasted	Comment @gryndel cancel.
You want a fresh review without pushing	Comment @gryndel review.
Gryndel says commands need a higher role, or write access	In GitLab, ask a Maintainer for the Developer role on the project. On GitHub, ask a repository admin for write access.
Gryndel says it's turned off	An admin has paused it. Carry on without it.
You don't know what a command does	Comment @gryndel help. See Commands in merge and pull requests.
@gryndel gets no reply at all on GitHub	Check the comment starts with @gryndel and isn't part of a review you haven't submitted yet. If it still gets nothing, ask whoever runs Gryndel which word it listens for.