This article explains where to start when a colleague sends you a pull request and asks you to look at the code. After reading it, you can open the diff on the Review page in the sidebar, write a comment on a specific line, offer replacement code with a suggestion block when you need to, and submit Approve, Request changes, or Comment.
A pull request is a request to merge the changes on one branch into another branch. AngusGit calls it a pull request. The sidebar page is Pull Requests. GitLab calls the same thing a merge request, and GitHub calls it a pull request. Line comments and suggestions are written on the Review page in the sidebar. The pull request page itself has no entry for them. To make the repository require a review before merge, see the branch protection article linked at the end.
The open example is xlliu/test-cicd-example #1. Its title is "SC-02/SC-04 PR trigger verification". It merges source branch verify-pr-sc0204 into target branch main. Angus's review on this request is still Pending, and you can expand the diff under Files changed. To read a finished review conversation, open two merged examples: #1 on xlliu/test-pr-example and #1 on xlliu/test-review-example.
1. What the three decisions mean
The last step of a review is to pick one of three decisions. Know the difference first, so you know what to look for while you read the code.
| Decision | Meaning | Effect on merge |
|---|---|---|
| Approve | I have read it, and I agree to merge it | Counts toward the approval number. The merge card allows the merge only after the number is high enough |
| Request changes | These problems have to be fixed first | Until the author changes the code and receives an approval again, the merge card says This pull request is not ready to merge |
| Comment | I have a question or a suggestion, and it does not block the merge | Does not count as an approval, and does not block the merge |
On the screen, the line under Approve is "Approve this review request". The line under Request changes is "Submit feedback that must be addressed before merging". The line under Comment is "Submit general feedback without explicit approval".
When you are unsure, pick Comment, write the question clearly, and decide between approve and request changes after the author answers. If a problem would cause an error in production, pick Request changes. After you approve, adding "please remember to fix this" does not block the merge.
2. Open the request you need to review
- Open the review list
Click Review in the sidebar. The page heading is Code Review. It opens on the Pending tab, which lists requests still waiting for you. A card marked Overdue can go first. If the same pull request is assigned to several reviewers, the list shows one row per reviewer.
- Find the request
When there are many requests, search by title in the "Search reviews..." box, or change the repository filter from All Repositories to one repository.
- Open the review
Click the card to open the review. The counts at the top show how many commits and files this change contains, and how many lines were added and deleted. You can click View pull request at any time to go back to the original request page.
On Angus's review list, Pending is 6 and Reviewed is 18. The top has a search box, All Repositories, and Select reviewer. The list has three requests: "docs: 说明空购物车不计算折扣 #9" on xlliu/test-pr-example (the description contains Closes #4), "docs: cross-repo review list count fixture (round 25) #2" on anguskit/Markdown, and "SC-02/SC-04 PR trigger verification #1" on xlliu/test-cicd-example. The last two are marked Overdue. Each request is assigned to two reviewers (for example #9 is assigned to Angus and admin), so each one takes two rows in the list.
3. Read what the author is trying to do
After you open the review, read the author's description on the Conversations tab before you read the code: what problem this solves, how large the change is, and whether there is a place they especially want you to look at. If you open the diff without knowing the purpose, it is easy to catch only formatting and miss a real logic error.
The same page also has Status checks, the results written back by automatic checks such as a pipeline. Each item shows Success, Failed, or Pending. A check that is still running shows Pending. If one item is Failed, see which one failed. If it is about the code you are reviewing, for example the build fails or a test does not pass, you can request changes and ask the author to make the check pass first.
4. Read the diff file by file, and comment on a specific line
After you know the purpose of the change, open the Files changed tab and read the code. A diff is the before-and-after comparison.
- Walk the file tree
The left side is the File tree. After you finish a file, check it in the tree and mark it Viewed. The action is Mark as viewed. When there are many files, this keeps you from missing a renamed or deleted file. A large file shows only the first part by default. Click Show full diff to see all of it.
- Pick a view that is easy to read
Unified stacks deleted lines and added lines. It fits a small change. Split puts the old version on the left and the new version on the right. It fits a function that was rewritten in a large block.
- Leave a comment on the line you want to discuss
Move the pointer to that line, click Add a comment on this line, write the comment, and click Comment. The comment is still a Draft. The author cannot see it, so you can keep reading other files and write other line comments, then send them all at once. If you need to discuss one line with a colleague, click Copy link to line and send it to them.
The picture is the review page for xlliu/test-cicd-example #1. In Unified under Files changed, a comment was written on the new line 9 of apps/service-a/src/index.js. The comment is marked Draft, so the author cannot see it yet. Neither file in the file tree on the left is marked viewed.
Three habits make a line comment easier for the author to fix:
- Say what the problem is, and why it is a problem. "This throws a null pointer" is more useful than "this looks wrong".
- Separate what must change from what is only a suggestion. If it is only a style you prefer, start with "optional". The author can leave it, and you can still approve.
- When you can give the code, give it. The next section shows how.
5. Offer the replacement code directly
Some comments are hard to explain in words. Write the corrected code instead. In the line comment, put a suggestion code block. The block is the text you want that line to become:
This does not handle an empty raw value. Check it first:
```suggestion
if (raw == null || raw.isBlank()) return false;
```
After you send it, the comment is shown as Suggested change. The author, or someone with write permission, clicks Apply suggestion. AngusGit replaces the line you commented on with the contents of the block (the block can contain several lines) and creates a new commit on the source branch. After it succeeds, the comment shows Applied.
Three limits matter:
- A suggestion replaces by line number. If the author changes the file after you write the suggestion, the line number may have moved. Refresh the diff before you apply it, and confirm that the line is still the one you meant.
- One comment recognizes only the first
suggestionblock. To change several places that are not next to each other, write several line comments. - Applying a suggestion adds a commit directly on the author's branch. Even if you have write permission yourself, tell the author before you click. If they still have unpushed local changes, the later push can conflict.
If the pull request's source branch is in a fork (a personal copy made from someone else's repository), or the file is binary, the suggestion cannot be applied. Write the code in an ordinary comment and ask the author to change it.
6. Submit the decision
After you have read every file, click Submit review at the top. The dialog title is Submit Review, and it says "Choose your review decision and add comments".
- Choose the decision
Pick Approve, Request changes, or Comment. Section 1 explains what each one means.
- Write a summary
In the Comment box, write the overall conclusion for the author. The placeholder is "Add your comments...". One sentence is enough for an approval, for example "The logic is fine. This can be merged." For request changes, list the places that must be fixed, so the author does not have to sort a dozen line comments to see which ones are required. The summary can be left empty.
- Send it
+N on the button means the N draft line comments you wrote earlier will be sent together. After you confirm, click Submit review.
After you submit, your decision appears in the review area on the pull request Conversation page, and the author can see each line comment on the file diff. The request also moves from your Pending list to Reviewed.
In the picture, Approve is selected. The button says Submit review. This review has no draft line comment, so the button does not show a count. Request changes and Comment are the other two choices. The summary can be left empty. Until you click Submit review, this review's status is still Pending.
7. Review again after the author updates
After the author receives Request changes, they edit locally and push to the same source branch. They do not need a new pull request. The new commits appear on the original one.
After a discussion is fixed as requested, the author or the reviewer can click Mark as resolved. If the repository requires every comment to be resolved before merge (Require conversation resolution), an unmarked discussion stays in the merge conditions.
After the author pushes, come back to this review:
- On the Commits tab, find the commits the author just pushed and click View changes. Read only what is new. You do not need to reread the whole diff from the start.
- Confirm that the problems you raised are fixed. If you still have a question, write another line comment.
- Click Submit review again. This time you usually pick Approve.
Someone who already submitted Approve sees that approval marked Needs re-review after the author pushes new commits. If the target branch has branch protection (merge and push rules set on that branch), those old approvals no longer count. Someone has to approve the latest code again before the merge card allows the merge. The code that was approved is then the latest version.
8. The merge happens on the pull request page. If you are busy, delegate
The review page records the decision. It does not merge the code. When the approval count meets the repository requirement, status checks have passed, and there is no conflict, the author or a maintainer goes back to the pull request Conversation page and clicks Merge pull request.
If you do not have time to review, click Delegate while the review is pending. Under Delegate to, pick another member, then click Delegate. The request leaves your pending list and moves to theirs.
9. When you get stuck
| What you see | Why | What to do |
|---|---|---|
| The review has no Submit review button | You are not a reviewer on this request, or the request is already merged | Ask the author or a repository administrator to add you as a reviewer. A merged request cannot take another decision |
| The author says they cannot see your line comments | The line comments are still drafts, and you have not clicked Submit review | Open Submit review, pick a decision, and send it. +N on the button is the number that has not been sent |
| You cannot find the line-comment entry under Files changed on the pull request | That page is for reading. The top says "Line comments and suggestions are done on the review page" | Click Go to review to comment, and write the comment on the review page |
| You already approved, and the merge card still says This pull request is not ready to merge | The approval count is not high enough; or the author pushed more commits after your approval and it became Needs re-review; or there is a conflict, a status check failed, or a discussion is unresolved | Follow the reason written on the merge card. If it is Needs re-review, approve the latest code again |
| Apply suggestion says Failed to apply suggestion | The comment has no suggestion block, the comment is not on a line, the file is not a text file, or the request's source branch is in a fork |
Confirm that the suggestion is in a line comment and that the block starts with three backticks plus suggestion. For a request from a fork, and for a binary file, ask the author to edit it by hand |
Frequently asked questions
How many people have to review one request?
The repository decides. Required reviewers under Settings → Pull Requests, or Required approving review count on the branch protection rule, is the number of approvals required before merge. The merge card allows the merge after that number is reached.
If I pick Comment, can the author still merge?
Yes. Comment does not count as an approval, and it does not block the merge. If the problem you care about must be fixed first, pick Request changes.
What if a review comment is wrong?
Under that discussion, click Reply and write the correction. The author follows the latest reply. If the decision itself was the wrong choice, submit the review again and pick the right decision.
The change is too large to finish reading. What then?
In the description or the summary, ask the author to split it into several small pull requests, each doing one thing. A reviewer can actually read a change that stays within a few hundred lines.
Summary
A complete review has four steps. Open the queue under Review. Read the description and the status checks so you know what the author is trying to do. Under Files changed, read file by file, comment on specific lines, and use a suggestion block when you can give the code directly. Then send the decision once with Submit review. After the author pushes new commits, come back and read only what was added, then submit a decision again. The author or a maintainer does the actual merge on the pull request page.
Conclusion: Code review is done on the Review page in the sidebar. Line comments you write file by file stay as drafts. They are published together, and they count toward the merge conditions, only after you click Submit review and choose Approve, Request changes, or Comment.
Related articles
- AngusGit manual: Code review (review list, line comments, submitting a decision, delegate)
- AngusGit guide: Review a pull request
- AngusGit manual: Pull requests (merge conditions, conflicts)
- How to protect the Git main branch: turn on branch protection, then merge through a pull request
- How to push code after you install your own Git server: set up SSH or HTTPS and finish the first push
Top comments (0)