What is a suggested change in a GitHub pull request review, and how does it reach the branch?

## The mechanism A **suggested change** is an ordinary review comment whose body contains a fenced code block tagged `suggestion`. The content of that block is the proposed replacement for the lines the comment is anchored to. GitHub renders it as a small diff and offers the pull request author — or anyone with write access to the head branch — a button to apply it. Because the suggestion replaces the commented range wholesale, the block must contain the complete replacement text, at the correct indentation, and nothing else: no prose, no diff markers. An empty suggestion block deletes the lines. Comment on multiple lines by dragging over a line range in the diff, and the suggestion replaces the whole range, which is how you propose a three-line rewrite rather than a one-liner. ## What applying it does Clicking **Commit suggestion** creates a commit on the pull request's head branch. The commit message can be edited, and GitHub records the suggesting reviewer as a **co-author** in the commit trailer, so `git log` and blame show that the change came from the review. Because it is a genuine push, it re-triggers the pull request's checks and behaves exactly like any other commit for rules that dismiss stale approvals. When several suggestions are outstanding, **Add suggestion to batch** on each and then commit them together produces one commit and one CI run rather than a run per click — the difference between a tidy history with one pipeline execution and eight commits called "Update foo.kt" with eight builds behind them. ## Where suggestions cannot be used **Only inside the diff.** You can anchor a comment to lines shown in the pull request's diff. A fix that belongs in a file the pull request does not touch cannot be a suggestion; it has to be described in words. **Not once the lines move.** If the author pushes commits that change the region, the comment becomes **outdated**, the suggestion no longer applies cleanly, and the button goes away. Long-lived suggestions on an actively-pushed branch simply evaporate. **Write access to the head branch is required.** For a pull request from a fork, the head branch lives in the contributor's repository. Maintainers can apply suggestions there only when the contributor left "allow edits by maintainers" enabled; otherwise the contributor applies them. **Not for structural change.** A suggestion is a textual replacement of a contiguous range. Renaming a symbol across five files, extracting a function, or reordering declarations is not expressible as one, and squeezing it into a suggestion produces something that compiles in the reviewer's head and not on the branch. ## Why they are worth using Suggestions collapse the slowest loop in review. The alternative to "here is the exact line, click to accept" is: reviewer writes a sentence describing a change, author interprets it, pushes something slightly different, reviewer re-reads, and two days pass over a variable name. For small, unambiguous edits — a typo, an off-by-one boundary, a missing null guard, a clearer name — the suggestion is faster, unambiguous, and reviewable as a diff before it is accepted. They also change the tone of review. "This is wrong" invites defence; a concrete suggestion the author can accept, modify, or reject with a reason is a proposal, and proposals get discussed on their merits. ## Where they are misused Three failure modes recur. **Suggestion storms**: forty single-line suggestions on a pull request where the real feedback is that the approach is wrong — batch them or, better, write the one comment that matters. **Untested suggestions**: a snippet typed into a text box has never been compiled, and applying it can leave the branch broken until CI says so; keep them small enough that you are certain. **Suggestions as a substitute for a conversation**: when the change is a design decision, the author needs the reasoning, not a patch to click. ## The habit worth forming If your comment tells the author exactly what to type, make it a suggestion instead. If your comment is asking them to think, leave it as prose.