Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 36 ยท Projects and Merge Requests

Merge Requests Basics

Learn the GitLab merge request workflow: branch, push, open an MR, draft state, push options, closing keywords, tabs of the MR page and how merging works.

A merge request (MR, written !7) is a proposal to merge one branch into another, wrapped in a discussion. Other platforms call the same thing a pull request. The MR page collects everything about the change: the description, the diff, comments, the pipeline result, approvals and the merge button. Nothing lands on main without going through one, if your project follows good practice.

The basic flow

  1. Update your local main and create a branch.
  2. Commit your work.
  3. Push the branch to GitLab.
  4. Open a merge request.
  5. Respond to review and CI results by pushing more commits.
  6. Merge.

On the command line:

Terminal
git switch main
git pull
git switch -c 42-fix-checkout-crash
# ...edit files...
git add .
git commit -m "Fix crash when the cart is empty"
git push -u origin 42-fix-checkout-crash

After a push, GitLab prints a link in the terminal output, and a banner on the project page offers a Create merge request button. Both lead to the same form.

Push options: create the MR from the terminal

Git lets you attach -o options to a push. GitLab reads them and can create or configure the merge request for you.

Terminal
git push -u origin 42-fix-checkout-crash \
  -o merge_request.create \
  -o merge_request.target=main \
  -o merge_request.title="Fix crash on empty cart" \
  -o merge_request.remove_source_branch

Useful options include merge_request.create, merge_request.target=<branch>, merge_request.title, merge_request.description, merge_request.label, merge_request.assign and merge_request.remove_source_branch. They save a lot of clicking once you do it daily. The stand-in below builds the command from a few answers, so you can see how the options compose.

Python Stand-in: build a push command with options

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The merge request form

When you open an MR, fill in:

  • Title: a clear summary. Start it with Draft: while the work is unfinished. A draft cannot be merged, and reviewers know not to look yet. Remove the prefix with the Mark as ready button.
  • Description: what changed and why, how to test it, and the closing keyword for the issue (Closes #42). Templates from .gitlab/merge_request_templates/ fill this in for you.
  • Assignee and reviewers: the assignee owns the MR (usually the author); reviewers are asked to review.
  • Labels and milestone: the same as for issues.
  • Merge options: Delete source branch when merged and Squash commits when merging checkboxes (depending on project settings).

Closing issues automatically

If the MR description or any of its commit messages contains a closing pattern pointing to an issue, GitLab closes that issue when the MR merges into the default branch. Recognized words include close, closes, closed, closing, fix, fixes, fixed, fixing, resolve, resolves, resolved, resolving, implement, implements, implemented and implementing, followed by an issue reference.

Python Stand-in: which issues will this MR close?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Observe that #50 is not closed because it follows "Related to" rather than a closing word, and that merging into a non-default branch closes nothing.

Anatomy of the merge request page

The page has tabs and a summary area:

  • Overview: the description, the activity timeline with comments and system notes, and the widget in the middle. The widget shows the pipeline status, approvals, whether there are conflicts, and the merge button.
  • Commits: every commit in the branch. Reviewing commit by commit helps with large work.
  • Pipelines: each pipeline run for this MR.
  • Changes: the diff. You can switch between inline and side-by-side, hide whitespace, and mark files as viewed.

The merge button is disabled when something blocks it: a failing pipeline (if the project requires success), unresolved discussion threads, missing approvals, conflicts, or the draft state. The page tells you which.

Keeping your branch current

If main moves while you work, your branch can fall behind or conflict. Two choices:

Terminal
git switch 42-fix-checkout-crash
git fetch origin
git rebase origin/main        # rewrites your commits on top of main
# or
git merge origin/main         # adds a merge commit instead

After a rebase, push with git push --force-with-lease, which refuses to overwrite commits you have not seen. Small conflicts can also be resolved in the web interface using the Resolve conflicts button, or you can use the project's Rebase button when the history is otherwise clean.

Habits of good merge requests

  • Keep them small. Reviewers handle 200 lines far better than 2,000.
  • One purpose per MR; resist unrelated cleanups.
  • Write the description for a reader who knows nothing: what, why, how to verify.
  • Open a draft early to get feedback and run CI before the work is done.
  • Check the pipeline yourself before asking others to look.

See the merge methods lesson for how the final merge shapes history.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a Draft: prefix on a merge request title do?

    Draft merge requests cannot be merged until marked ready, and reviewers know the work is in progress.
  2. 2. When does Closes #42 in an MR description close the issue?

    The closing pattern takes effect when the change reaches the default branch.
  3. 3. Which push option asks GitLab to open a merge request?

    merge_request.create is the push option that creates an MR as part of the push.
  4. 4. After rebasing a branch you already pushed, which push is safest?

    --force-with-lease refuses to overwrite remote commits you have not fetched, protecting teammates' work.

Summary

  • A merge request proposes merging a branch and hosts the discussion, diff, pipeline and approvals.
  • Push options such as merge_request.create let you open MRs from the terminal.
  • Use Draft: for unfinished work and closing keywords to link and close issues.
  • The MR page has Overview, Commits, Pipelines and Changes, and the widget explains what blocks the merge.
  • Keep MRs small and up to date with the target branch.

Next: Code Review and Approvals