Skip to content

Good Practices: GitLab Workflow - Reviewer Role

Purpose

This guide provides a step-by-step workflow for reviewing merge requests in GitLab. It is designed for developers of all experience levels, from those new to Git/GitLab to seasoned contributors.

The Essential Role of a Reviewer

Code review is not a rubber-stamping exercise, nor is it a test to see if the author is "right". The review is a critical part of development for ensuring quality, stability, and adherence to project standards. As a reviewer, you are allowed - and expected - to be critical.

As a reviewer, your primary goal is to ensure the long-term maintainability, safety, and clarity of the codebase - your eyes are the last on the code before it is merged. Keep these guiding principles in mind during every review:

  • Misunderstanding is a Valid Signal: If you review a piece of code and misunderstand what it does, do not assume you are at fault. A misunderstanding usually means the code's intent, variable naming, or structure could be clearer. Raise it as a question.
  • A Collaborative Learning Process: Reviews are a shared discussion. Ask questions, suggest alternatives, and challenge assumptions.
  • Review to Your Capabilities: You do not need to be an expert in every line of code written. Review what you understand, and if a specific module or optimization is outside your comfort zone, flag it in the MR comments so another team member can weigh in. Or ask: Often in explaining a piece of code, logical flaws become apparent.

The Authoritative Checklist

To avoid documentation drift, this workflow guide does not maintain a static list of coding requirements. Instead, every project generated from our official template includes a local file named REVIEWER_CHECKLIST.md at its root.

Always refer to the local REVIEWER_CHECKLIST.md file within the repository you are reviewing. It serves as the authoritative, up-to-date checklist for both general project safety and language-specific (Python or R) implementation standards.

How to Conduct a Review in GitLab

What: The process of providing feedback and your official approval or request for changes on an MR.

Why: To prevent changes that are difficult to understand, catch diverging views early, ensure adherence to standards, and generally share knowledge.

How:

  1. Understand the Goal: Read the MR Description and linked Issue to understand what problem the code is trying to solve and why.
  2. Use the Changes Tab: Navigate to the Changes tab to view the file differences (the "diff").
  3. Start a Review (Recommended): When leaving your first comment on a line of code, select Start a Review instead of Add comment now. This batches your comments into a private draft that only you can see until you are ready to submit. When you do submit, the author receives a single consolidated notification rather than one per comment. Use Add comment now only for a single quick question or minor note when you are not conducting a full review.
  4. Leave Line Comments: Place comments directly on specific lines of code where you have questions or suggestions.
  5. Use Suggestions: For minor improvements (e.g., typos, formatting), use the "Suggest change" feature to propose the change directly.
  6. Submit the Review: Once you have finished reviewing, open Your review in the upper-right corner to see all pending comments together, then click Submit review.
  7. Select the outcome of your review:
    • Approve: The MR is acceptable and ready to merge.
    • Comment: General feedback, questions, or suggestions without an explicit approval or change request. This is the appropriate choice for most review cycles.
    • Request changes: Use this only for blocking issues - problems that genuinely prevent the MR from being merged. Reserve it for significant concerns rather than stylistic preferences or minor suggestions.
  8. (Optional but recommended) Leave a summary comment explaining your overall thoughts.

All comments must be resolved before the MR is merged. If a comment is a minor suggestion rather than a blocking concern, label it explicitly (e.g., "nit:" or "optional:") so the author can prioritize their fixes accordingly - but it still needs to be addressed and resolved before approval.

  1. Hand Off for Merging: Once you are satisfied the MR is ready to merge, two further actions are needed:
  2. Click Approve on the MR to formally mark it as verified. This signals to the rest of the team that the code has passed review.
  3. Reassign the MR to a team member with merge rights. This moves the MR into their GitLab work list directly, signalling that it is waiting for the final merge into the target branch.

Leaving an MR approved but unassigned risks it being overlooked and delays the merge.

Tips:

  • Focus your feedback on the code, not the person. Assume the author has a positive intent.
  • Frame suggestions as questions ("What do you think about refactoring X?") rather than demands ("Change X to Y.").
  • Clearly explain the why behind a suggestion, not just the what.
  • Consider asking the author to break down the MR if it is too large. The quality of the review decreases with the size of change.
  • When the author has addressed your feedback, they should mark each discussion as Resolved and click Re-request review next to your name. You may reopen a discussion if you feel the concern has not been fully addressed.

Additional Resources