debian-mirror-gitlab/doc/user/project/merge_requests/index.md
2022-07-23 20:15:48 +02:00

15 KiB

stage group info type
Create Code Review To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments index, reference

Merge requests (FREE)

Merge requests (MRs) are the way you check source code changes into a branch. When you open a merge request, you can visualize and collaborate on the code changes before merge. Merge requests include:

  • A description of the request.
  • Code changes and inline code reviews.
  • Information about CI/CD pipelines.
  • A comment section for discussion threads.
  • The list of commits.

Read more about how to get started.

View merge requests

You can view merge requests for your project, group, or yourself.

View merge requests for a project

To view all merge requests for a project:

  1. On the top bar, select Menu > Projects and find your project.
  2. On the left sidebar, select Merge requests.

Or, to use a keyboard shortcut, press g + m.

View merge requests for all projects in a group

To view merge requests for all projects in a group:

  1. On the top bar, select Menu > Groups and find your group.
  2. On the left sidebar, select Merge requests.

If your group contains subgroups, this view also displays merge requests from the subgroup projects.

View all merge requests assigned to you

To view all merge requests assigned to you:

  1. On the top bar, put your cursor in the Search box.
  2. From the dropdown list, select Merge requests assigned to me.

Or:

  • To use a keyboard shortcut, press Shift + m.
  • On the top bar, on the top right, select {merge-request-open} Merge requests. Then select one of the following:

Filter the list of merge requests

To filter the list of merge requests:

  1. Above the list of merge requests, select Search or filter results....
  2. In the dropdown list that appears, select the attribute you wish to filter by.
  3. Select or type the operator to use for filtering the attribute. The following operators are available:
  4. Enter the text to filter the attribute by. You can filter some attributes by None or Any.
  5. Repeat this process to filter by multiple attributes. Multiple attributes are joined by a logical AND.

GitLab displays the results on-screen, but you can also retrieve them as an RSS feed.

Filter merge requests by ID

Introduced in GitLab 12.1.

You can filter the Merge Request list to find merge requests by their ID.

For example, enter filter #30 to return only merge request 30.

Filter merge requests by approvers (PREMIUM)

Moved to GitLab Premium in 13.9.

To filter merge requests by an individual eligible approver (Code owner), you can type (or select from the dropdown list) Approver and select the user.

Filter MRs by an approver

Filter merge requests by "approved by" (PREMIUM)

  • Introduced in GitLab 13.0.
  • Moved to GitLab Premium in 13.9.

To filter merge requests already approved by a specific individual, you can type (or select from the dropdown list) Approved-By and select the user.

Filter MRs by approved by

Filter merge requests by reviewer

Introduced in GitLab 13.7.

To filter review requested merge requests for a specific individual, you can type (or select from the dropdown list) Reviewer and select the user.

Filter merge requests by environment or deployment date

Introduced in GitLab 13.6.

To filter merge requests by deployment data, such as the environment or a date, you can type (or select from the dropdown list) the following:

  • Environment
  • Deployed-before
  • Deployed-after

NOTE: Projects using a fast-forward merge method do not return results, as this method does not create a merge commit.

When filtering by an environment, a dropdown list presents all environments that you can choose from:

Filter MRs by their environment

When filtering by Deployed-before or Deployed-after, the date refers to when the deployment to an environment (triggered by the merge commit) completed successfully. You must enter the deploy date manually. Deploy dates use the format YYYY-MM-DD, and must be quoted if you wish to specify both a date and time ("YYYY-MM-DD HH:MM"):

Filter MRs by a deploy date

Add changes to a merge request

If you have permission to add changes to a merge request, you can add your changes to an existing merge request in several ways, depending on the complexity of your change and whether you need access to a development environment:

Assign a user to a merge request

When a merge request is created, it's assigned by default to the person who created it. This person owns the merge request, but isn't responsible for reviewing it. To assign the merge request to someone else, use the /assign @user quick action in a text area in a merge request, or:

  1. On the top bar, select Menu > Projects and find your project.
  2. On the left sidebar, select Merge requests and find your merge request.
  3. On the right sidebar, expand the right sidebar and locate the Assignees section.
  4. Select Edit.
  5. Search for the user you want to assign, and select the user.

The merge request is added to the user's assigned merge request list.

Assign multiple users (PREMIUM)

Moved to GitLab Premium in 13.9.

GitLab enables multiple assignees for merge requests, if multiple people are accountable for it:

multiple assignees for merge requests sidebar

To assign multiple assignees to a merge request, use the /assign @user quick action in a text area, or:

  1. On the top bar, select Menu > Projects and find your project.
  2. On the left sidebar, select Merge requests and find your merge request.
  3. On the right sidebar, expand the right sidebar and locate the Assignees section.
  4. Select Edit and, from the dropdown list, select all users you want to assign the merge request to.

To remove an assignee, clear the user from the same dropdown list.

Close a merge request

If you decide to permanently stop work on a merge request, GitLab recommends you close the merge request rather than delete it. The author and assignees of a merge request, and users with Developer, Maintainer, or Owner roles in a project can close merge requests in the project:

  1. Go to the merge request you want to close.
  2. Scroll to the comment box at the bottom of the page.
  3. Following the comment box, select Close merge request.

GitLab closes the merge request, but preserves records of the merge request, its comments, and any associated pipelines.

Delete a merge request

GitLab recommends you close, rather than delete, merge requests.

WARNING: You cannot undo the deletion of a merge request.

To delete a merge request:

  1. Sign in to GitLab as a user with the project Owner role. Only users with this role can delete merge requests in a project.
  2. Go to the merge request you want to delete, and select Edit.
  3. Scroll to the bottom of the page, and select Delete merge request.

Update merge requests when target branch merges (FREE SELF)

Merge requests are often chained together, with one merge request depending on the code added or changed in another merge request. To support keeping individual merge requests small, GitLab can update up to four open merge requests when their target branch merges into main. For example:

  • Merge request 1: merge feature-alpha into main.
  • Merge request 2: merge feature-beta into feature-alpha.

If these merge requests are open at the same time, and merge request 1 (feature-alpha) merges into main, GitLab updates the destination of merge request 2 from feature-alpha to main.

Merge requests with interconnected content updates are usually handled in one of these ways:

  • Merge request 1 is merged into main first. Merge request 2 is then retargeted to main.
  • Merge request 2 is merged into feature-alpha. The updated merge request 1, which now contains the contents of feature-alpha and feature-beta, is merged into main.

This feature works only when a merge request is merged. Selecting Remove source branch after merging does not retarget open merge requests. This improvement is proposed as a follow-up.

Request attention to a merge request

Introduced in GitLab 14.10 with a flag named mr_attention_requests. Disabled by default.

FLAG: On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to enable the feature flag named mr_attention_requests. On GitLab.com, this feature is dependent on the enablement status of the feature flag. Refer to the enablement issue for details.

To tell a merge request's assignee or reviewer that their attention is needed on a merge request, you can request their attention. If an assignee or a reviewer has their attention requested on a merge request, the Attention request icon ({attention}) is displayed as a solid icon ({attention-solid}) on the merge request list page:

Attention request icon

To view a list of merge requests that need your attention:

  1. On the top bar, select Merge requests ({merge-request}).
  2. Select Attention requests.

To request attention from another user, use the /attention @user quick action or:

  1. Go to the merge request.

  2. On the right sidebar, identify the user you want to request attention from.

  3. Next to the user's name, select Request attention ({attention}), and the appearance of the icon changes:

    Attention request toggle

Remove an attention request

If your attention was requested as an assignee or reviewer, it's removed when you:

  • Manually remove the attention request by selecting Remove attention request ({attention-solid}).
  • Approve the merge request.
  • Add a new user as an assignee or reviewer.
  • Request the attention of a different assignee or reviewer.
  • Remove yourself (or are removed by someone else) as an assignee or reviewer.
  • Merge or close the merge request.

If you are both the assignee and a reviewer on a merge request, you receive only one attention request, which is synced across both duties. If the attention request is removed from you, either as an assignee or a reviewer, it is removed from both your duties.

Merge request workflows

For a software developer working in a team:

  1. You checkout a new branch, and submit your changes through a merge request.
  2. You gather feedback from your team.
  3. You work on the implementation optimizing code with Code Quality reports.
  4. You verify your changes with Unit test reports in GitLab CI/CD.
  5. You avoid using dependencies whose license is not compatible with your project with License Compliance reports.
  6. You request the approval from your manager.
  7. Your manager:
    1. Pushes a commit with their final review.
    2. Approves the merge request.
    3. Sets it to merge when pipeline succeeds.
  8. Your changes get deployed to production with manual jobs for GitLab CI/CD.
  9. Your implementations were successfully shipped to your customer.

For a web developer writing a webpage for your company's website:

  1. You checkout a new branch and submit a new page through a merge request.
  2. You gather feedback from your reviewers.
  3. You preview your changes with Review Apps.
  4. You request your web designers for their implementation.
  5. You request the approval from your manager.
  6. Once approved, your merge request is squashed and merged, and deployed to staging with GitLab Pages.
  7. Your production team cherry-picks the merge commit into production.