Merge requests end to end
Intermediate GitLab UI
Why this matters
The merge request is where your work meets the team. Everything else in this course leads here: the branch you made, the commits you wrote, the pipeline that checks them, the colleague who reads them. It is also the single page you will spend the most time on, so it is worth knowing every part.
The life of one
Creating one
Three routes, in increasing order of tidiness:
| Route | How | Pre-fills |
|---|---|---|
| After a push | The push output prints a URL; the project page also shows a Create merge request banner for recently pushed branches | Source branch |
| From the merge requests list | Code → Merge requests → New merge request, then choose source and target branches | Nothing |
| From an issue | On the issue, Create merge request | A correctly named branch, the target, and a description linking the issue |
The third is best: GitLab names the branch after the issue, sets Closes #N in the description, and marks the merge request as a draft, all of which you would otherwise do by hand.
Writing the description
The diff says what changed. The description says why, and it is read by the reviewer now and by whoever investigates in a year.
## What
Adds the Windows steps to the installation guide, and links them from the FAQ.
## Why
Support gets this question weekly; issue #12 has three examples.
## How to check
Read `docs/getting-started.md` on the branch, or the rendered preview from the pipeline.
Closes #12Four things earn their place: what, why, how the reviewer can verify it, and the closing keyword. Many projects have a description template (a file in .gitlab/merge_request_templates/) which fills this in for you; if the box arrives pre-filled, fill in the headings rather than deleting them.
Draft status is the other half. A merge request whose title starts with Draft: cannot be merged, which is how you say "this is for looking at, not for merging yet". The Mark as draft and Mark as ready controls toggle it. Opening as a draft early is good practice: the pipeline runs, colleagues can see the direction, and nobody merges it by accident.
The page
| Tab | Shows |
|---|---|
| Overview | The description, the discussion, the pipeline status and the merge panel |
| Commits | The commits the branch adds, which is git log main..branch |
| Pipelines | Every pipeline run for the branch |
| Changes | The diff, which is git diff main...branch (lesson 6.5) |
The right sidebar carries the fields: Assignee (who is responsible for moving it forward, usually you), Reviewers (who must look), Milestone, Labels, and the Approval panel showing how many approvals are required and which rules apply.
Suggestions
In the Changes tab, a reviewer can select lines and write a suggestion: a proposed replacement shown as a diff. You then click Apply suggestion, and GitLab commits the change to your branch for you. Several suggestions can be applied in one commit with Add suggestion to batch.
This is the fastest path for wording changes in documentation, and it is worth encouraging reviewers to use it: a suggestion is unambiguous, whereas "maybe reword this" is a conversation.
The merge panel
At the bottom of Overview, and it tells you exactly what is missing. Common reasons the button is disabled:
| Message | Meaning | Fix |
|---|---|---|
| Merge blocked: this is a draft | Title starts with Draft: |
Mark as ready |
| Merge blocked: pipeline must succeed | The pipeline is red or still running | Read the failing job (lesson 9.10) |
| Requires N approvals | Approval rule not satisfied | Ask a reviewer; you usually cannot approve your own |
| Requires approval from code owners | CODEOWNERS rule (lesson 9.5) | Ask the named owner |
| There are unresolved threads | A discussion is still open | Resolve or answer them |
| There are merge conflicts | The branch conflicts with the target | Resolve (Section 11) |
| Ready to merge! | Nothing is missing | Merge |
When it is ready, the button carries options:
- Squash commits: your branch becomes one commit in
main(lesson 6.6). Whether this is available or forced is a project setting. - Delete source branch: tick it; the branch has done its job (lesson 6.8).
- Auto-merge (older versions: "Merge when pipeline succeeds"): merges by itself once the checks pass, which saves waiting.
After merging
The issue closes if you wrote Closes #N. The branch is deleted if you ticked the box. Your local repository knows none of this until you catch up:
$ git switch main
$ git pull
$ git branch -d docs/12-windows-install-steps
$ git fetch --pruneremote: To create a merge request for docs/12-windows-install-steps, visit:
remote: https://gitlab.com/northwind-trails/trailguide/-/merge_requests/new?merge_request%5Bsource_branch%5D=docs%2F12-windows-install-stepsIf something turns out to be wrong, the merge request page has a Revert option that creates a revert commit on a new branch and a merge request for it, which is the safe way to undo a merged change (lesson 5.6).
How to do it
The terminal creates the branch and the commits; the merge request itself is a platform object. The push output gives you the link:
Push options can do more in one step, for projects that use them:
$ git push -o merge_request.create -o merge_request.target=main -u origin docs/12-windows-install-stepsThe GitLab Workflow extension adds a Merge requests view: browse open merge requests, read the diff, comment, and create one from the current branch. It needs a token with api scope.
With a GitLab account added, the Merge Requests tool window lists them, shows the diff, and lets you comment and approve without leaving the IDE. Git → GitLab → Create Merge Request starts one from the current branch.
- Create from the issue (Create merge request), from the banner after a push, or with Code → Merge requests → New merge request.
- Write the description: what, why, how to check, and
Closes #N. Leave it as a Draft while you work. - Add Reviewers in the right sidebar; that is what sends them a to-do item.
- Watch the pipeline on Overview; open the failing job if it is red.
- Answer threads; Apply suggestion for the ones that are wording changes.
- Mark as ready when it is, and merge when the panel says it can be, ticking Delete source branch.
The same object is a pull request, with Conversation, Commits, Checks and Files changed tabs, Closes #12, draft status, suggestions, required reviews and the same merge options. See lesson 10.7; the terminology map lists the differences in names.
Common mistakes
- Opening a merge request with an empty description. The reviewer has to reconstruct the reason from the diff.
- Forgetting
Closes #N. The work ships and the issue stays open. - Not marking it ready. It sits as a draft while you wait for a review nobody knows is wanted.
- Requesting review in chat instead of assigning a reviewer. No to-do item, no record.
- Pushing new commits to an approved merge request in a project that resets approvals (lesson 9.5).
- Leaving the source branch after merging. The branch list fills up for everyone.
Try it yourself
Goal: run a merge request from issue to merged on your own project.
- Create an issue for a small documentation change.
- From the issue, Create merge request; let GitLab create the branch.
- Locally:
git fetch,git switch <branch>, make the change, commit with(#N), push. - On the merge request: fill in the description with what, why and
Closes #N; watch the pipeline; then Mark as ready. - Merge with Delete source branch ticked, then locally
git switch main && git pull && git fetch --prune. - Check that the issue closed itself.
Expected result: the issue is closed, main has your change, the branch is gone in both places, and the merge request page records the whole story.
Show solution
Step 6 is the test of whether the description was right: if the issue is still open, Closes #N was missing or misspelled. Editing the description after merging does not close it retroactively; close it by hand and remember the keyword next time.