I was reviewing a PR today — someone adding nightly cron triggers and splitting Bazel cache into restore-everywhere vs save-only-on-main. I had two comments. One about a path asymmetry (~/.cache/bazelisk in save but not restore), another about uv.lock being in the cache key when Bazel doesn’t even read it.
Two related comments. Different files, different lines. I typed the first one and stared at the two buttons: Add single comment and Start a review.
I had no idea what the difference was.
The two buttons
Turns out they do very different things.
Add single comment posts immediately. One comment, one notification, done. It’s the equivalent of tapping someone on the shoulder mid-conversation to say one thing.
Start a review holds your comment as pending. Nobody sees it yet. You can keep going — click on other lines, add more comments — and they all accumulate in a draft review. When you’re done, you submit the whole batch at once.
If you have two related observations about a PR, “Add single comment” twice means two separate notifications, two separate threads, no indication they’re related. “Start a review” means one cohesive package that lands together.
For my case — two observations about cache configuration that are conceptually connected — “Start a review” was obviously the right call. I just didn’t know it existed ten minutes ago.
The submit dialog
After you click “Start a review” and add all your comments, there’s a green “Finish your review” button. This opens a dialog with:
- A text box at the top — for an optional summary comment on the whole review
- Three radio buttons — this is the part that confused me
The three options:
| Option | What it does | When to use |
|---|---|---|
| Comment | Posts your feedback, no verdict | You have observations but aren’t signing off |
| Approve | Feedback + green checkmark | You’re a required reviewer saying “ship it” |
| Request changes | Feedback + blocks merging | Something must be fixed before merge |
The trap: using “Request changes” for optional suggestions. If you’re saying “hey, this cache key might cause unnecessary cold builds” — that’s a Comment, not a change request. You’re not blocking the PR. You’re offering context.
And “Approve” isn’t just “I read it.” It’s a formal sign-off. If you’re not a required reviewer and you’re just leaving observations, don’t hit Approve — it sends the wrong signal.
The full flow
So now I know the actual workflow:
- Click a line in the diff, type your comment, hit “Start a review” — creates a pending review
- Click another line, type another comment, hit “Add review comment” — adds to the pending batch
- Click the green “Finish your review” button at the top
- Write an optional summary, pick your verdict (Comment / Approve / Request changes), submit
Everything lands at once. One notification. One coherent review.
The thing that got me: steps 1 and 2 look almost identical in the UI. The only difference is the button label changes from “Start a review” to “Add review comment” after you’ve started one. Easy to miss if you’re not looking for it.
Why this is a TIL and not a tutorial
There are a hundred guides on “how to review PRs on GitHub.” I could have read any of them. But I didn’t need a guide until I was actually staring at two buttons on a real PR with real comments I wanted to leave.
The context matters. I wasn’t reading docs about GitHub review mechanics — I was trying to tell someone their cache key includes a file Bazel doesn’t read. The UI question was incidental. And that’s how most learning works. You don’t seek out the knowledge until the moment you need it, and then it clicks instantly because you have the exact right context.
Two buttons. Three radio buttons. Five minutes of confusion. Now I know.