Merge Requests, Drafts, Review Threads, Suggestions, and Change Collaboration: Configuration, Design Choices, and Tradeoffs
Choose focused versus broad merge requests, same-project versus fork workflows, draft timing, reviewer assignment, and web suggestions versus local commits using explicit security, audit, maintainability, and delivery tradeoffs.
Learning objectives
- Choose MR scope that preserves review quality, test causality, rollback clarity, and understandable history.
- Choose same-project branches or fork workflows based on contributor trust, push rights, runner/resource boundaries, and operational overhead.
- Use draft timing as a collaboration signal without confusing it with CI, approval, or mergeability policy.
- Choose web suggestions versus local commits based on complexity, authorship, testing, signing, and audit requirements.
- Label Free versus Premium/Ultimate governance boundaries precisely instead of designing policy around unavailable controls.
glab mr command family are documented for
Free/Premium/Ultimate on GitLab.com, Self-Managed, and Dedicated. On
GitLab Free, eligible users can approve an MR, but
approvals are optional and do not enforce a merge gate;
required approval rules are Premium/Ultimate. Draft
MRs cannot merge until marked ready, but by default they run the same
MR pipelines as ready MRs. Current fork-pipeline behavior and
protected-resource rules are version-sensitive, so production policy
must be checked against the deployed GitLab version.
1. Small focused MR versus broad change set
An MR is easiest to reason about when one change has one dominant intent. “Small” does not mean an arbitrary line limit. It means the reviewer can understand the proposed behavior, identify relevant risk, connect tests to the change, and explain how to reverse it.
| Dimension | Focused MR | Broad MR | Production effect |
|---|---|---|---|
| Intent | One coherent reason | Several unrelated reasons | Focused intent improves audit and rollback decisions |
| Diff review | Less cognitive switching | Reviewers may skim or miss generated/secondary files | Large scope weakens review signal |
| CI causality | Failures map to fewer changes | Many possible causes | Debugging and bisecting become slower |
| Merge conflicts | Shorter lifetime/smaller overlap | Long-running branch accumulates divergence | Integration risk rises with breadth and time |
| Release/revert | Change can often revert independently | Revert may remove unrelated behavior | Operational blast radius increases |
2. Same-project branch versus fork workflow
Use a same-project branch when contributors are trusted project members who need ordinary push access to feature branches. Use a fork when contributors should not have write access to the authoritative project or when organizational boundaries make separate project ownership appropriate.
| Question | Same-project branch | Fork source project |
|---|---|---|
| Where source ref lives | Target project | Contributor/fork project |
| Typical contributor role | Developer or other role that can push feature branch | Can have lower/no write role in target |
| Remote complexity | One main remote is often enough | Contributor usually manages fork + upstream remotes |
| CI default trust | Same project settings, subject to branch/protected-resource rules | Fork pipeline normally uses fork resources; parent-run pipeline crosses a stronger trust boundary |
| Governance benefit | Simpler team workflow | Separates untrusted contribution from authoritative write access |
The choice is not “forks are safer” in isolation. A maintainer can erase the safety advantage by executing unreviewed fork CI in a parent context with powerful variables/runners. Security comes from the complete trust path.
3. Draft versus ready: communication timing, not test policy
Create a draft early when feedback on direction is valuable before implementation is complete. Keep it draft while the work is intentionally not mergeable. Mark it ready when the author believes review can produce a merge decision.
Do not use draft status as a cost-control mechanism by itself. Current GitLab runs the same MR pipelines for drafts by default unless pipeline rules explicitly skip them. Likewise, “ready” does not mean “approved,” “pipeline passed,” or “safe to deploy.”
4. Web suggestion versus local commit
| Use case | Web suggestion | Local commit / push |
|---|---|---|
| Tiny textual correction | Excellent: reviewer can propose exact patch | More ceremony than needed |
| Multi-file behavior change | Poor fit; review context may hide cross-file effect | Prefer local edit, test, commit, push |
| Needs local tests/build | Suggestion can be proposed, but application alone is not test proof | Local workflow can test before push |
| Commit signing / authorship policy | Must account for GitLab-created suggestion commit and documented suggestion authorship | Local tooling can satisfy team signing/authorship conventions |
| Audit clarity | Good for “reviewer proposed exact text” | Good for author-owned implementation with explicit commit message |
Applying a suggestion is a source mutation. Treat it like any other new commit: refresh diff/CI/review evidence if policy depends on the exact head SHA.
5. Assignee, reviewer, approver: design responsibility explicitly
Use the assignee to name who drives the MR to completion. Use reviewer requests to name who should inspect it. Use approval policy when you need evidence/enforcement that qualified reviewers accepted the change. Do not substitute broad Maintainer access for a review request.
On GitLab Free, approval recording is useful social/audit evidence but is optional. If production policy says “two independent approvals are mandatory,” that enforcement is not a Free approval rule; either use the appropriate Premium/Ultimate capability or enforce the policy in another auditable control that your organization actually operates.
6. Fork workflow decision: security and resource tradeoffs
When external code is involved, separate three questions:
- Who controls the source project and branch?
- Which CI configuration is executed?
- Which project’s runners, variables, network, and permissions are available to that execution?
A parent-project MR pipeline for fork code can intentionally combine source code from the fork with parent resources. That may be necessary for trusted validation, but it must be an explicit reviewed action. Do not make it automatic merely because the contributor cannot access a private dependency.
7. Worked decision table
Suppose an internal platform team accepts both employee changes and public contributions.
| Scenario | Recommended MR shape | Why |
|---|---|---|
| Employee fixes typo in owned docs | Small same-project branch; ready quickly; optional reviewer | Low risk, direct ownership, minimal overhead |
| Employee redesigns auth flow | Draft early; focused same-project MR; explicit security reviewer; current-head evidence | Complex risk benefits from early design review and strong traceability |
| External contributor changes application code | Fork MR; run source-side CI first; inspect diff and CI config before any parent-context pipeline | Keeps authoritative project write/secret boundary separate |
| Reviewer spots a one-line error | Web suggestion, then verify new source SHA and pipeline/review state | Exact patch is efficient and auditable |
| Reviewer proposes refactor across 12 files | Request local commits instead of giant suggestion sequence | Testing, authorship, review coherence, and rollback are clearer |
8. Performance and cost belong to the change shape
Very broad MRs create more diff rendering, longer pipelines, more rebases, and more reviewer time. GitLab also collapses generated/common large files and applies diff limits for performance. That is a UI/performance behavior, not permission to ignore those files. Reviewers should inspect the repository diff locally when critical changes are collapsed or too large to render.
Do not optimize pipeline cost by weakening trust boundaries or bypassing review. Improve change scope, pipeline rules, caching, job selection, and runner architecture in the dedicated CI chapters.
9. A lightweight MR policy for a Free-compatible team
- Every MR names one target branch and one dominant intent.
- Draft means “not merge-ready”; ready means “author requests merge-quality review.”
- Review is always against an identified head SHA; new commits invalidate stale assumptions.
- Critical comments stay unresolved until evidence shows the underlying concern is addressed.
- Suggestions are treated as commits and re-enter the evidence loop.
- Fork code never receives parent-project secrets/resources merely to make CI convenient.
- Optional Free approvals are not described as enforced gates.
- Large/generated/hidden diff areas receive local or API inspection when relevant.
Knowledge check
A team uses “Draft” to mean “CI should not run.” Is that reliable by default?
No. Current GitLab draft MRs run the same MR pipelines as ready MRs unless pipeline rules explicitly skip draft cases.
Why might a 2,000-line MR be operationally worse even if all lines are correct?
It weakens review focus, increases integration/conflict risk, makes failures harder to attribute, and can create larger rollback blast radius.
When is a fork workflow most justified?
When source contributors should not have ordinary write access to the authoritative project or when source ownership/trust is intentionally separate.
A reviewer proposes a multi-file refactor using dozens of suggestions. What is usually better?
Ask for local commits so the author can test the whole change, preserve coherent commit intent, and avoid fragmented suggestion-generated history.
Can a Free team truthfully claim “GitLab enforces two approvals” because two people usually click Approve?
No. On Free, approvals are optional evidence, not required merge rules. The policy description must match the actual enforcement mechanism.
Summary
Good MR design reduces ambiguity before tooling can help: keep change intent focused, choose branch versus fork topology based on trust and write access, use draft as a collaboration state, treat suggestions as source mutations, and align approval claims with the actual tier. Lesson 4 intentionally breaks these assumptions and diagnoses the resulting failures.
Official references
- GitLab Docs — Merge requests
- GitLab Docs — Create merge requests
- GitLab Docs — Draft merge requests
- GitLab Docs — Merge request reviews
- GitLab Docs — Suggest changes
- GitLab Docs — Merge request workflows
- GitLab Docs — Merge request pipelines
- GitLab Docs — Changes in merge requests
- GitLab Docs — Troubleshooting merge requests
- GitLab Docs — Merge request approvals
- GitLab Docs — Default branch
- GitLab Docs — Merge requests API
- GitLab Docs — Discussions API
- GitLab Docs — Suggest Changes API
- GitLab Docs — glab mr
- GitLab Docs — glab mr create
- GitLab Docs — glab mr update
- GitLab Docs — glab mr view
- GitLab Docs — glab mr checkout
- GitLab Docs — glab mr merge
- GitLab Docs — REST API pagination
Keep the academy open
Support free, practical DevOps education.
Every lesson is designed to remain readable in a browser, downloadable from GitHub, and usable without a paid learning platform. Contributions help expand and maintain the curriculum.
0x716c4Ab160C4B66F31a28AE2448BfF68fc3a2ef0Send only Ethereum/ERC-20 compatible assets to this
address.