Your team knows why an API field needs a matching schema change. A reviewer joining the project might not. GitLab's Code Review Flow can inspect the code on its own, and project-specific instructions give it the context behind conventions your team would otherwise explain in review comments.
Start with something that matters to your project: how clients consume a response, which calls need a timeout, or where compatibility is documented. A long list of general programming advice is less useful than a short explanation of a decision the reviewer needs to understand.
The worked example compares the same API change before and after adding an instruction, then fixes the problem and requests a fresh review. Duo found the missing schema field in both reviews. The instruction added the team's client context; it didn't discover a new defect. That comparison helps you decide which instructions are worth keeping.
Before you begin
You'll need Premium or Ultimate for custom review instructions, Code Review Flow available in your project, and a merge request you can ask Duo to review. Code Review Flow itself is also available on Free with GitLab Credits. You can leave automatic reviews off while trying the example.
Which review runs depends on the person requesting it. A user without a Duo Enterprise seat gets Code Review Flow, which uses GitLab Credits. An Enterprise seat holder gets the seat-based GitLab Duo Code Review by default, even when Code Review Flow is enabled. Use the same review experience for both sides of the comparison.
On GitLab.com, a top-level group Owner can enable Code Review Flow under Settings > GitLab Duo > Change configuration > Flow execution > Allow foundational flows. To route Enterprise seat holders to the flow too, clear and reselect Code Review Flow, then confirm Enable Code Review Flow. This switches all reviews in the group to the credit-consuming flow. GitLab documents the routing choice and the Self-Managed and Dedicated steps; its Code Review setup guide covers the other prerequisites.
There's no custom flow to install. Code Review uses .gitlab/duo/mr-review-instructions.yaml for these instructions; it doesn't load AGENTS.md or SKILL.md.
1. See what the review already catches
Choose a small merge request with a problem you understand. Request a review by assigning GitLab Duo as a reviewer, or post this quick action in a merge request comment:
/assign_reviewer @GitLabDuo
Check the merge request's activity for a review session. If Duo completed a review without a session, the seat-based review ran; check the routing above before comparing results. Read the summary and comments on changed lines, and use View session beside the summary to inspect the investigation. Can you connect the finding to the code and the behavior it affects?
Our example adds resource_type to an order response and updates the Python test, but leaves the OpenAPI schema unchanged. CI passes because those tests don't validate the schema. Duo identifies the mismatch without additional instructions—a useful reminder to try the default review before adding rules.
2. Explain one project convention
Open the sample review instructions. The Order response compatibility instruction names the serializer, the OpenAPI file, and why the team cares about keeping them together. Its fileFilters entry targets src/orders/api.py, where the response is built.
Copy the file to .gitlab/duo/mr-review-instructions.yaml on your project's default branch. For your own code, replace the sample path and explanation with the files and client behavior your team actually uses. If an instructions file already exists, add the item under its existing instructions list.
Aim for enough context to make a useful decision. For example, explain which schema describes a response and what needs to accompany a new field. An instruction to flag every API edit would also complain about harmless comments and make reviews less helpful. These instructions guide a review; checks that must run on every change still fit in CI.
3. Compare the feedback
Try the same change again with the instruction available. The evaluation walkthrough uses a second merge request so you can compare the two reviews side by side.
In our run, the new comment names Order response compatibility and explains the concern using the client context. Both reviews identify the same missing field. One labels it Major, the other Critical; the stronger label alone doesn't make the second review better. Judge whether the explanation is accurate and helps the author make the right change.
If an instruction only repeats what Duo already explains well, you may not need it. Keep the context that makes a difference, and revise instructions that produce irrelevant or unsupported findings.
4. Check the review after the fix
Correct the issue and let the pipeline run. In the example, we add resource_type to OpenAPI without weakening the tests. Then post:
@GitLabDuo please review the latest changes.
The fresh review should use the updated files. Our run recognizes the schema fix and finds nothing further to comment on. Compare that explanation with the diff and passing checks before resolving the original discussion. Your team's reviewers still decide whether to approve and merge.
Try the before-and-after exercise with the supplied files, or use a familiar change in your own project. GitLab's review-instructions guide has more examples when you're ready to cover another convention.
Other ways to start a review
You can ask Agentic Chat to review a merge request by providing its URL, select Re-request review beside GitLab Duo in the reviewer list, or use the experimental Code Review REST API.
For automatic initial reviews, a Maintainer can open Settings > Merge requests > GitLab Duo Code Review, select Enable automatic reviews by GitLab Duo, and save. Eligible merge requests receive a review when created with changes, marked ready from draft, or given their first changes after being created empty. Exclusion rules can skip selected merge requests.
In GitLab 19.5, Start a new review on push also starts a review when a push changes the diff of an open, non-draft merge request that already has GitLab Duo as a reviewer. It requires automatic reviews and Code Review Flow for the author. The setting is on by default; a Maintainer can change it in the same settings section.
For other event-based starts, a Maintainer can create a trigger under AI > Triggers, select Code Review as the flow, and choose an event:
| Event in the trigger form | When it starts the review |
|---|---|
| Assign | The trigger's service account is assigned to the merge request. |
| Assign reviewer | The trigger's service account is added as a reviewer. |
| Merge request > Created | The merge request is created and its diff is available. |
| Merge request > Approved | The merge request has all required approvals. |
| Merge request > Marked ready | A draft merge request becomes ready. |
| Merge request > Merge conflict | GitLab detects a code conflict that prevents merging. |
The mention route remains the review request shown in step 4: mention @GitLabDuo in a merge request comment and ask for a review. These event triggers use the merge request as their target.