GitHub suggested changes: when and how to use them well
Othman Shareef · September 22, 2026 · 6 min read
GitHub suggested changes are the closest thing code review has to a fast path: the reviewer proposes the exact replacement lines, and the author lands them with one click. Used well, they turn a comment round trip that costs hours into a commit that costs seconds. Used badly, they become a way to rewrite someone else’s pull request from the review pane. This piece covers how the feature actually behaves, verified against the GitHub docs, when a suggestion beats a prose comment, and the etiquette that keeps suggestions welcome.
How GitHub suggested changes work
On the reviewer side, the mechanics live inside an ordinary review comment. Per the GitHub docs on PR comments, you comment on a line or range of lines, click the suggestion button in the comment toolbar, and edit the text within the suggestion block that appears. Whatever the block contains is your proposed replacement for the commented lines. On the author side, the docs on incorporating feedback describe the apply flow: clicking Commit suggestion creates a single commit on the pull request’s compare branch. Applying requires write access to the repository; on a pull request from a fork, maintainers can apply suggestions if the author allowed edits from maintainers. Everyone whose suggestion lands in a commit is recorded as a co-author, so attribution survives the shortcut.
When a suggestion beats a prose comment
The test is whether the code is shorter than the explanation. A typo, a better variable name, a missing await, an off-by-one in a range check, a doc sentence that should read differently: writing “consider renaming this to reflect that it returns a list” forces the author to reverse-engineer your intent, apply it, and hope they landed where you pointed. The suggestion is the intent, byte for byte, and it removes an entire round trip along with the ambiguity. This makes suggestions the natural container for nits in particular: as we argued in our piece on nitpicks, small feedback should cost the author almost nothing to accept, and one click is almost nothing. If your nit is not worth typing out as a suggestion, that is useful information about whether it was worth raising at all.
Batch suggestions into one commit
Applying eight suggestions one by one produces eight commits, eight CI runs, and a branch history that reads like a woodpecker. The docs describe the fix: instead of Commit suggestion, click Add suggestion to batch on each change you want, then click Commit suggestions once to land the whole set as a single commit, with every suggester co-authored. Authors should default to batching whenever a review contains more than a couple of suggestions. One caveat worth knowing before you click: an applied suggestion is a real commit, so it triggers CI like any push, and in repositories configured to dismiss stale approvals when the diff changes, it can invalidate the very approval the reviewer just gave. The polite reviewer flow is to approve and let the author apply, rather than leaving suggestions dangling behind a request for changes.
Where suggestions stop working
A suggestion can only say one thing: replace the lines this comment is anchored to with these lines. Everything outside that shape falls back to prose. Changes that span multiple files cannot be expressed, which rules out the most common real refactor (rename the function here, update its call sites there). Moved code has the same problem: a suggestion can delete lines in place or add lines in place, but it cannot say “this block belongs in the other module.” And because suggestions anchor to the diff a reviewer can comment on, code far from the visible changes is, as of this writing, out of reach. None of this is a flaw to work around with heroics. When a proposed fix outgrows the suggestion box, that is the feature telling you the change deserves a conversation, or its own pull request, not a bigger box.
Etiquette: an offer, not an order
A suggestion carries more force than a comment, because accepting it takes one click while declining it takes a written justification. That asymmetry is why etiquette matters. A suggestion is an offer: the author may apply it, adapt it, or decline it, and a declined suggestion is a completed interaction, not an opening bid. Reviewers who pave a pull request with dozens of style suggestions are not reviewing; they are ghost-writing, and they teach authors to stop thinking about the feedback and start clicking through it. Keep suggestions for changes you would be content to see merged exactly as written, mark the optional ones as optional, and put anything you actually require behind an explicit request instead. The distinction is worth stating in the review itself, because the author cannot read your mind about which suggestions are load-bearing; we cover that boundary in when to request changes and the phrasing side in review comments that land. The feature works best when it stays what it is: the smallest possible gift.