diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-07-20 12:55:51 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-07-20 12:55:51 +0300 |
| commit | e8d2c2579383897a1dd7f9debd359abe8ae8373d (patch) | |
| tree | c42be41678c2586d49a75cabce89322082698334 /doc/user/project/merge_requests | |
| parent | fc845b37ec3a90aaa719975f607740c22ba6a113 (diff) | |
Add latest changes from gitlab-org/gitlab@14-1-stable-eev14.1.0-rc42
Diffstat (limited to 'doc/user/project/merge_requests')
30 files changed, 310 insertions, 325 deletions
diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index 76aff18b00d..2bc6d5bb148 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -10,7 +10,7 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/25144) in GitLab 12.8. If your application offers a web interface and you are using -[GitLab CI/CD](../../../ci/README.md), you can quickly determine the accessibility +[GitLab CI/CD](../../../ci/index.md), you can quickly determine the accessibility impact of pending code changes. ## Overview @@ -37,7 +37,7 @@ This example shows how to run [pa11y](https://pa11y.org/) on your code with GitLab CI/CD using the [GitLab Accessibility Docker image](https://gitlab.com/gitlab-org/ci-cd/accessibility). For GitLab 12.9 and later, to define the `a11y` job, you must -[include](../../../ci/yaml/README.md#includetemplate) the +[include](../../../ci/yaml/index.md#includetemplate) the [`Accessibility.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml) included with your GitLab installation, as shown below. diff --git a/doc/user/project/merge_requests/approvals/index.md b/doc/user/project/merge_requests/approvals/index.md index 3c47c2af344..40345f33cb2 100644 --- a/doc/user/project/merge_requests/approvals/index.md +++ b/doc/user/project/merge_requests/approvals/index.md @@ -11,11 +11,21 @@ disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/merge > Redesign [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/1979) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.8 and [feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/10685) in 12.0. You can configure your merge requests so that they must be approved before -they can be merged. You can do this by creating [rules](rules.md) or by specifying -a list of users who act as [code owners](../../code_owners.md) for specific files. - -You can configure merge request approvals for each project. In higher GitLab tiers, -Administrators of self-managed GitLab instances can configure approvals +they can be merged. While [GitLab Free](https://about.gitlab.com/pricing/) allows +all users with Developer or greater [permissions](../../../permissions.md) to +approve merge requests, these approvals are [optional](#optional-approvals). +[GitLab Premium](https://about.gitlab.com/pricing/) and +[GitLab Ultimate](https://about.gitlab.com/pricing/) provide additional +flexibility: + +- Create required [rules](rules.md) about the number and type of approvers before work can merge. +- Specify a list of users who act as [code owners](../../code_owners.md) for specific files, + and require their approval before work can merge. + +You can configure merge request approvals on a per-project basis. Administrators of +[GitLab Premium](https://about.gitlab.com/pricing/) and +[GitLab Ultimate](https://about.gitlab.com/pricing/) self-managed GitLab instances +can also configure approvals [for the entire instance](../../../admin_area/merge_requests_approvals.md). ## How approvals work @@ -60,7 +70,7 @@ a merge request. After a merge request receives the [number and type of approvals](rules.md) you configure, it can merge unless it's blocked for another reason. Merge requests can be blocked by other problems, -such as merge conflicts, [pending discussions](../../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved), +such as merge conflicts, [pending discussions](../../../discussions/index.md#prevent-merge-unless-all-threads-are-resolved), or a [failed CI/CD pipeline](../merge_when_pipeline_succeeds.md). To prevent merge request authors from approving their own merge requests, @@ -94,6 +104,7 @@ Without the approvals, the work cannot merge. Required approvals enable multiple database, for all proposed code changes. - Use the [code owners of changed files](rules.md#code-owners-as-eligible-approvers), to determine who should review the work. +- Require an [approval before merging code that causes test coverage to decline](../../../../ci/pipelines/settings.md#coverage-check-approval-rule) - [Require approval from a security team](../../../application_security/index.md#security-approvals-in-merge-requests) before merging code that could introduce a vulnerability. **(ULTIMATE)** diff --git a/doc/user/project/merge_requests/approvals/rules.md b/doc/user/project/merge_requests/approvals/rules.md index 1e4b0f659ee..82685f9101e 100644 --- a/doc/user/project/merge_requests/approvals/rules.md +++ b/doc/user/project/merge_requests/approvals/rules.md @@ -5,7 +5,7 @@ info: "To determine the technical writer assigned to the Stage/Group associated type: reference, concepts --- -# Merge request approval rules **(FREE)** +# Merge request approval rules **(PREMIUM)** Approval rules define how many [approvals](index.md) a merge request must receive before it can be merged, and which users should do the approving. You can define approval rules: @@ -159,7 +159,7 @@ become eligible approvers in the project. To enable this merge request approval  You can also -[require code owner approval](../../protected_branches.md#protected-branches-approval-by-code-owners) +[require code owner approval](../../protected_branches.md#require-code-owner-approval-on-a-protected-branch) for protected branches. **(PREMIUM)** ## Merge request approval segregation of duties **(PREMIUM)** @@ -173,6 +173,7 @@ Some users (like managers) may not need permission to push or merge code, but st oversight on proposed work. To enable approval permissions for these users without granting them push access: +1. [Create a protected branch](../../protected_branches.md) 1. [Create a new group](../../../group/index.md#create-a-group). 1. [Add the user to the group](../../../group/index.md#add-users-to-a-group), and select the Reporter role for the user. @@ -180,7 +181,7 @@ granting them push access: based on the Reporter role. 1. Go to your project and select **Settings > General**. 1. Expand **Merge request (MR) approvals**. -1. Select **Add approval rule** or **Update approval rule**. +1. Select **Add approval rule** or **Update approval rule** and target the protected branch. 1. [Add the group](../../../group/index.md#create-a-group) to the permission list.  @@ -203,7 +204,7 @@ on a merge request, you can either add or remove approvers: Administrators can change the [merge request approvals settings](settings.md#prevent-overrides-of-default-approvals) to prevent users from overriding approval rules for merge requests. -## Configure optional approval rules +## Configure optional approval rules **(PREMIUM)** Merge request approvals can be optional for projects where approvals are appreciated, but not required. To make an approval rule optional: @@ -229,4 +230,4 @@ approval rule for certain branches:  1. To enable this configuration, read - [Code Owner's approvals for protected branches](../../protected_branches.md#protected-branches-approval-by-code-owners). + [Code Owner's approvals for protected branches](../../protected_branches.md#require-code-owner-approval-on-a-protected-branch). diff --git a/doc/user/project/merge_requests/approvals/settings.md b/doc/user/project/merge_requests/approvals/settings.md index b72a4125d0e..8a81ff8c94b 100644 --- a/doc/user/project/merge_requests/approvals/settings.md +++ b/doc/user/project/merge_requests/approvals/settings.md @@ -115,8 +115,16 @@ permission enables an electronic signature for approvals, such as the one define ## Security approvals in merge requests **(ULTIMATE)** You can require that a member of your security team approves a merge request if a -merge request could introduce a vulnerability. To learn more, see -[Security approvals in merge requests](../../../application_security/index.md#security-approvals-in-merge-requests). +merge request could introduce a vulnerability. + +To learn more, see [Security approvals in merge requests](../../../application_security/index.md#security-approvals-in-merge-requests). + +## Code coverage check approvals **(PREMIUM)** + +You can require specific approvals if a merge request would result in a decline in code test +coverage. + +To learn more, see [Coverage check approval rule](../../../../ci/pipelines/settings.md#coverage-check-approval-rule). ## Related links diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index 930df65f3fc..339f67f828f 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -17,7 +17,7 @@ There are two main ways to have a merge request flow with GitLab: With the protected branch flow everybody works within the same GitLab project. The project maintainers get the [Maintainer role](../../permissions.md) and the regular developers -get Developer access. +get the Developer role. Maintainers mark the authoritative branches as 'Protected'. diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index d11ad53a9d6..eff3a5bd99e 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -10,7 +10,7 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/3507) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3. If your application offers a web interface and you're using -[GitLab CI/CD](../../../ci/README.md), you can quickly determine the rendering performance +[GitLab CI/CD](../../../ci/index.md), you can quickly determine the rendering performance impact of pending code changes in the browser. NOTE: @@ -40,7 +40,7 @@ Consider the following workflow: ## How browser performance testing works First, define a job in your `.gitlab-ci.yml` file that generates the -[Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsbrowser_performance). +[Browser Performance report artifact](../../../ci/yaml/index.md#artifactsreportsbrowser_performance). GitLab then checks this report, compares key performance metrics for each page between the source and target branches, and shows the information in the merge request. @@ -89,7 +89,7 @@ The above example: GitLab 12.3 or earlier, you must [add the configuration manually](#gitlab-versions-132-and-earlier). The template uses the [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance), -and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsbrowser_performance) +and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/index.md#artifactsreportsbrowser_performance) that you can later download and analyze. This implementation always takes the latest Browser Performance artifact available. If [GitLab Pages](../pages/index.md) is enabled, you can view the report directly in your browser. diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 27642a9bd5d..19302572dc9 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -10,17 +10,22 @@ type: reference, howto > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1984) in GitLab 9.3. > - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in 13.2. -Ensuring your project's code stays simple, readable and easy to contribute to can be problematic. With the help of [GitLab CI/CD](../../../ci/README.md), you can analyze your -source code quality using GitLab Code Quality. +To ensure your project's code stays simple, readable, and easy to contribute to, +you can use [GitLab CI/CD](../../../ci/index.md) to analyze your source code quality. + +For example, while you're implementing a feature, you can run Code Quality reports +to analyze how your improvements are impacting your code's quality. You can +use this information to ensure that your changes are improving performance rather +than degrading it. Code Quality: -- Uses [Engines](https://docs.codeclimate.com/docs/list-of-engines) supported by Code Climate, which are +- Uses [plugins](https://docs.codeclimate.com/docs/list-of-engines) supported by Code Climate, which are free and open source. Code Quality does not require a Code Climate subscription. -- Runs in [pipelines](../../../ci/pipelines/index.md) using a Docker image built in the - [GitLab Code - Quality](https://gitlab.com/gitlab-org/ci-cd/codequality) project using [default Code Climate configurations](https://gitlab.com/gitlab-org/ci-cd/codequality/-/tree/master/codeclimate_defaults). +- Runs in [pipelines](../../../ci/pipelines/index.md) by using a Docker image built in the + [GitLab Code Quality](https://gitlab.com/gitlab-org/ci-cd/codequality) project. +- Uses [default Code Climate configurations](https://gitlab.com/gitlab-org/ci-cd/codequality/-/tree/master/codeclimate_defaults). - Can make use of a [template](#example-configuration). - Is available by using [Auto Code Quality](../../../topics/autodevops/stages.md#auto-code-quality), provided by [Auto DevOps](../../../topics/autodevops/index.md). - Can be extended through [Analysis Plugins](https://docs.codeclimate.com/docs/list-of-engines) or a [custom tool](#implementing-a-custom-tool). @@ -54,42 +59,14 @@ See also the Code Climate list of [Supported Languages for Maintainability](http > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/267612) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.11. > - [Deployed behind a feature flag](../../../user/feature_flags.md), disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 13.12. -> - [Feature enhanced](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) in GitLab 14.0. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/284140) in GitLab 14.1. +> - [Inline annotation added](https://gitlab.com/gitlab-org/gitlab/-/issues/2526) in GitLab 14.1. Changes to files in merge requests can cause Code Quality to fall if merged. In these cases, the merge request's diff view displays an indicator next to lines with new Code Quality violations. For example:  -Previously, an indicator was displayed (**{information-o}** **Code Quality**) on the file in the merge request's diff view: - - - -To switch to the previous version of this feature, a GitLab administrator can run the following in a -[Rails console](../../../administration/operations/rails_console.md): - -```ruby -# For the instance -Feature.disable(:codequality_mr_diff_annotations) -# For a single project -Feature.disable(:codequality_mr_diff_annotations, Project.find(<project id>)) -``` - -## Use cases - -For instance, consider the following workflow: - -1. Your backend team member starts a new implementation for making a certain - feature in your app faster. -1. With Code Quality reports, they analyze how their implementation is impacting - the code quality. -1. The metrics show that their code degrades the quality by 10 points. -1. You ask a co-worker to help them with this modification. -1. They both work on the changes until Code Quality report displays no - degradations, only improvements. -1. You approve the merge request and authorize its deployment to staging. -1. Once verified, their changes are deployed to production. - ## Example configuration This example shows how to run Code Quality on your code by using GitLab CI/CD and Docker. @@ -111,7 +88,7 @@ include: The above example creates a `code_quality` job in your CI/CD pipeline which scans your source code for code quality issues. The report is saved as a -[Code Quality report artifact](../../../ci/yaml/README.md#artifactsreportscodequality) +[Code Quality report artifact](../../../ci/yaml/index.md#artifactsreportscodequality) that you can later download and analyze. It's also possible to override the URL to the Code Quality image by @@ -262,13 +239,13 @@ was chosen as an operational decision by the runner team, instead of exposing `d ### Disabling the code quality job The `code_quality` job doesn't run if the `$CODE_QUALITY_DISABLED` CI/CD variable -is present. Please refer to the CI/CD variables [documentation](../../../ci/variables/README.md) +is present. Please refer to the CI/CD variables [documentation](../../../ci/variables/index.md) to learn more about how to define one. To disable the `code_quality` job, add `CODE_QUALITY_DISABLED` as a custom CI/CD variable. This can be done: -- For [the whole project](../../../ci/variables/README.md#custom-cicd-variables). +- For [the whole project](../../../ci/variables/index.md#custom-cicd-variables). - For a single pipeline run: 1. Go to **CI/CD > Pipelines** @@ -278,11 +255,11 @@ This can be done: ### Using with merge request pipelines The configuration provided by the Code Quality template does not let the `code_quality` job -run on [pipelines for merge requests](../../../ci/merge_request_pipelines/index.md). +run on [pipelines for merge requests](../../../ci/pipelines/merge_request_pipelines.md). If pipelines for merge requests is enabled, the `code_quality:rules` must be redefined. -The template has these [`rules`](../../../ci/yaml/README.md#rules) for the `code quality` job: +The template has these [`rules`](../../../ci/yaml/index.md#rules) for the `code quality` job: ```yaml code_quality: @@ -292,7 +269,7 @@ code_quality: - if: '$CI_COMMIT_TAG || $CI_COMMIT_BRANCH' ``` -If you are using merge request pipelines, your `rules` (or [`workflow: rules`](../../../ci/yaml/README.md#workflow)) +If you are using merge request pipelines, your `rules` (or [`workflow: rules`](../../../ci/yaml/index.md#workflow)) might look like this example: ```yaml @@ -334,7 +311,7 @@ do this: 1. Define a job in your `.gitlab-ci.yml` file that generates the [Code Quality report - artifact](../../../ci/yaml/README.md#artifactsreportscodequality). + artifact](../../../ci/yaml/index.md#artifactsreportscodequality). 1. Configure your tool to generate the Code Quality report artifact as a JSON file that implements a subset of the [Code Climate spec](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types). @@ -342,13 +319,13 @@ do this: The Code Quality report artifact JSON file must contain an array of objects with the following properties: -| Name | Description | -| ---------------------- | -------------------------------------------------------------------------------------- | -| `description` | A description of the code quality violation. | -| `fingerprint` | A unique fingerprint to identify the code quality violation. For example, an MD5 hash. | -| `severity` | A severity string (can be `info`, `minor`, `major`, `critical`, or `blocker`). | -| `location.path` | The relative path to the file containing the code quality violation. | -| `location.lines.begin` | The line on which the code quality violation occurred. | +| Name | Description | +| ---------------------- | ----------------------------------------------------------------------------------------- | +| `description` | A description of the code quality violation. | +| `fingerprint` | A unique fingerprint to identify the code quality violation. For example, an MD5 hash. | +| `severity` | A severity string (can be `info`, `minor`, `major`, `critical`, or `blocker`). | +| `location.path` | The relative path to the file containing the code quality violation. | +| `location.lines.begin` or `location.positions.begin.line` | The line on which the code quality violation occurred. | Example: @@ -371,6 +348,8 @@ Example: NOTE: Although the Code Climate spec supports more properties, those are ignored by GitLab. +The GitLab parser does not allow a [byte order mark](https://en.wikipedia.org/wiki/Byte_order_mark) +at the beginning of the file. ## Code Quality reports **(PREMIUM)** @@ -389,7 +368,7 @@ After the Code Quality job completes: - The full list of code quality violations generated by a pipeline is shown in the Code Quality tab of the Pipeline Details page. **(PREMIUM)** -### Generating an HTML report +## Generate an HTML report In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/ci-cd/codequality/-/issues/10), it is possible to generate an HTML report file by setting the `REPORT_FORMAT` @@ -535,7 +514,7 @@ This can be due to multiple reasons: - Your pipeline is not set to run the code quality job on your target branch. If there is no report generated from the target branch, your MR branch reports have nothing to compare to. - If no [degradation or error is detected](https://docs.codeclimate.com/docs/maintainability#section-checks), nothing is displayed. -- The [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) CI/CD +- The [`artifacts:expire_in`](../../../ci/yaml/index.md#artifactsexpire_in) CI/CD setting can cause the Code Quality artifact(s) to expire faster than desired. - The widgets use the pipeline of the latest commit to the target branch. If commits are made to the default branch that do not run the code quality job, this may cause the merge request widget to have no base report for comparison. - If you use the [`REPORT_STDOUT` environment variable](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables), no report file is generated and nothing displays in the merge request. diff --git a/doc/user/project/merge_requests/commits.md b/doc/user/project/merge_requests/commits.md index 1bda12468a3..fb1b7f8b9b6 100644 --- a/doc/user/project/merge_requests/commits.md +++ b/doc/user/project/merge_requests/commits.md @@ -26,3 +26,62 @@ To seamlessly navigate among commits in a merge request: - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts.  + +## View merge request commits in context + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29274) in GitLab 13.12. +> - [Deployed behind a feature flag](../../feature_flags.md), enabled by default. +> - Disabled on GitLab.com. +> - Not recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-viewing-merge-request-commits-in-context). **(FREE SELF)** + +WARNING: +This feature is in [beta](https://about.gitlab.com/handbook/product/gitlab-the-product/#beta) +and is [incomplete](https://gitlab.com/groups/gitlab-org/-/epics/1192). +Previously merged commits can be added, but they can't be removed due to +[this bug](https://gitlab.com/gitlab-org/gitlab/-/issues/325538). + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../../feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. + +When reviewing a merge request, it helps to have more context about the changes +made. That includes unchanged lines in unchanged files, and previous commits +that have already merged that the change is built on. + +To add previously merged commits to a merge request for more context: + +1. Go to your merge request. +1. Select the **Commits** tab. +1. Scroll to the end of the list of commits, and select **Add previously merged commits**: + +  + +1. Select the commits that you want to add. +1. Select **Save changes**. + +To view the changes done on those previously merged commits: + +1. On your merge request, select the **Changes** tab. +1. Scroll to **(file-tree)** **Compare** and select **previously merged commits**: + +  + +### Enable or disable viewing merge request commits in context **(FREE SELF)** + +Viewing merge request commits in context is under development and not ready for production use. It is +deployed behind a feature flag that is **disabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can enable it. + +To enable it: + +```ruby +Feature.enable(:context_commits) +``` + +To disable it: + +```ruby +Feature.disable(:context_commits) +``` diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 430c6488b26..0d56fbc89b8 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -7,189 +7,155 @@ description: "How to create merge requests in GitLab." disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html' --- -# How to create a merge request **(FREE)** +# Creating merge requests **(FREE)** -Before creating a merge request, read through an -[introduction to merge requests](getting_started.md) -to familiarize yourself with the concept, the terminology, -and to learn what you can do with them. +There are many different ways to create a merge request. -Every merge request starts by creating a branch. You can either -do it locally through the [command line](#new-merge-request-from-your-local-environment), via a Git CLI application, -or through the [GitLab UI](#new-merge-request-from-a-new-branch-created-through-the-ui). +## From the merge request list -This document describes the several ways to create a merge request. +You can create a merge request from the list of merge requests. -When you start a new merge request, regardless of the method, -you are taken to the [**New merge request** page](#new-merge-request-page) -to fill it with information about the merge request. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left menu, select **Merge requests**. +1. In the top right, select **New merge request**. +1. Select a source and target branch and then **Compare branches and continue**. +1. Fill out the fields and select **Create merge request**. -If you push a new branch to GitLab, also regardless of the method, -you can click the [**Create merge request**](#create-merge-request-button) -button and start a merge request from there. +## From an issue -## New merge request page +You can [create a merge request from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue). -On the **New merge request** page, start by filling in the title and description -for the merge request. If commits already exist on the branch, GitLab suggests a -merge request title for you: +## When you add, edit, or upload a file -- **If a multi-line commit message exists**: GitLab adds the first line of the - first multi-line commit message as the title. Any additional lines in that - commit message become the description. -- **If no multi-line commit message exists**: GitLab adds the branch name as the - title, and leaves the description blank. +You can create a merge request when you add, edit, or upload a file to a repository. -The title is the only field that is mandatory in all cases. +1. Add, edit, or upload a file to the repository. +1. In the **Commit message**, enter a reason for the commit. +1. Select the **Target branch** or create a new branch by typing the name (without spaces, capital letters, or special chars). +1. Select the **Start a new merge request with these changes** checkbox or toggle. This checkbox or toggle is visible only + if the target is not the same as the source branch, or if the source branch is protected. +1. Select **Commit changes**. -From there, you can fill it with information (title, description, -assignee(s), milestone, labels, approvers) and click **Create merge request**. +## When you create a branch -From that initial screen, you can also see all the commits, -pipelines, and file changes pushed to your branch before submitting -the merge request. +You can create a merge request when you create a branch. - +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left menu, select **Repository > Branches**. +1. Type a branch name and select **New branch**. +1. Above the file list, on the right side, select **Create merge request**. + A merge request is created. The default branch is the target. +1. Fill out the fields and select **Create merge request**. -NOTE: -You can push one or more times to your branch in GitLab before -creating the merge request. +## When you use Git commands locally -## Create merge request button +You can create a merge request by running Git commands on your local machine. -Once you have pushed a new branch to GitLab, visit your repository -in GitLab and to see a call-to-action at the top of your screen -from which you can click the button **Create merge request**. +1. Create a branch: - + ```shell + git checkout -b my-new-branch + ``` -You can also see the **Create merge request** button in the top-right of the: +1. Create, edit, or delete files. The stage and commit them: -- **Project** page. -- **Repository > Files** page. -- **Merge requests** page. + ```shell + git add . + git commit -m "My commit message" + ``` -In this case, GitLab uses the most recent branch you pushed -changes to as the source branch, and the default branch in the current -project as the target. +1. [Push your branch to GitLab](../../../gitlab-basics/start-using-git.md#send-changes-to-gitlabcom): -## New merge request by adding, editing, and uploading a file + ```shell + git push origin my-new-branch + ``` -When you choose to edit, add, or upload a file through the GitLab UI, -at the end of the file you see the option to add the **Commit message**, -to select the **Target branch** of that commit, and the checkbox to -**Start new a merge request with these changes**. + GitLab prompts you with a direct link for creating a merge request: -Similarly, if you change files through the Web IDE, when you navigate to **Commit** on the left-hand sidebar, you see these same options. + ```plaintext + ... + remote: To create a merge request for docs-new-merge-request, visit: + remote: https://gitlab.example.com/my-group/my-project/merge_requests/new?merge_request%5Bsource_branch%5D=my-new-branch + ``` -Once you have added, edited, or uploaded the file: +1. Copy the link and paste it in your browser. -1. Describe your changes in the commit message. -1. Select an existing branch to add your commit into, or, if you'd like to create a new branch, type the new branch name (without spaces, capital letters, or special chars). -1. Keep the checkbox checked to start a new merge request straightaway, or, uncheck it to add more changes to that branch before starting the merge request. -1. Click **Commit changes**. +You can add other [flags to commands when pushing through the command line](../push_options.md) +to reduce the need for editing merge requests manually through the UI. -If you chose to start a merge request, you are taken to the -[**New merge request** page](#new-merge-request-page), from -which you can fill it in with information and submit the merge request. +## When you work in a fork -The merge request targets the default branch of the repository. -If you want to change it, you can do it later by editing the merge request. +You can create a merge request from your fork to contribute back to the main project. -## New merge request from a new branch created through the UI - -To quickly start working on files through the GitLab UI, -navigate to your project's **Repository > Branches** and click -**New branch**. A new branch is created and you can start -editing files. - -Once committed and pushed, you can click on the [**Create merge request**](#create-merge-request-button) -button to open the [**New merge request** page](#new-merge-request-page). -A new merge request is started using the current branch as the source, -and the default branch in the current project as the target. - -## New merge request from your local environment - -Assuming you have your repository cloned into your computer and you'd -like to start working on changes to files, start by creating and -checking out a new branch: - -```shell -git checkout -b my-new-branch -``` - -Work on your file changes, stage, and commit them: +1. On the top bar, select **Menu > Project**. +1. Select your fork of the repository. +1. On the left menu, go to **Merge requests**, and select **New merge request**. +1. In the **Source branch** drop-down list box, select the branch in your forked repository as the source branch. +1. In the **Target branch** drop-down list box, select the branch from the upstream repository as the target branch. + You can set a [default target project](#set-the-default-target-project) to + change the default target branch (which can be useful if you are working in a + forked project). +1. Select **Compare branches and continue**. +1. Select **Submit merge request**. -```shell -git add . -git commit -m "My commit message" -``` +After your work is merged, if you don't intend to +make any other contributions to the upstream project, you can unlink your +fork from its upstream project. Go to **Settings > Advanced Settings** and +[remove the forking relationship](../settings/index.md#removing-a-fork-relationship). -Once you're done, [push your branch to GitLab](../../../gitlab-basics/start-using-git.md#send-changes-to-gitlabcom): +For more information, [see the forking workflow documentation](../repository/forking_workflow.md). -```shell -git push origin my-new-branch -``` +## By sending an email **(FREE SELF)** -In the output, GitLab prompts you with a direct link for creating -a merge request: +> The format of the generated email address changed in GitLab 11.7. + The earlier format is still supported so existing aliases + or contacts still work. -```shell -... -remote: To create a merge request for docs-new-merge-request, visit: -remote: https://gitlab-instance.com/my-group/my-project/merge_requests/new?merge_request%5Bsource_branch%5D=my-new-branch -``` +You can create a merge request by sending an email message to GitLab. +The merge request target branch is the project's default branch. -Copy that link and paste it in your browser, and the [**New merge request page**](#new-merge-request-page) -is displayed. +Prerequisites: -There is also a number of [flags you can add to commands when pushing through the command line](../push_options.md) to reduce the need for editing merge requests manually through the UI. +- A GitLab administrator must configure [incoming email](../../../administration/incoming_email.md). +- A GitLab administrator must configure [Reply by email](../../../administration/reply_by_email.md). -If you didn't push your branch to GitLab through the command line -(for example, you used a Git CLI application to push your changes), -you can create a merge request through the GitLab UI by clicking -the [**Create merge request**](#create-merge-request-button) button. +To create a merge request by sending an email: -## New merge request from an issue +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left menu, select **Merge requests**. +1. In the top right, select **Email a new merge request to this project**. + An email address is displayed. Copy this address. + Ensure you keep this address private. +1. Open an email and compose a message with the following information: -You can also [create a new merge request directly from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue). + - The **To** line is the email address you copied. + - The subject line is the source branch name. + - The message body is the merge request description. -## New merge request from the merge requests page +1. Send the email message. -You can start creating a new merge request by clicking the -**New merge request** button on the **merge requests** page in a project. -Then choose the source project and branch that contain your changes, -and the target project and branch where you want to merge the changes into. -Click on **Compare branches and continue** to go to the -[**New merge request** page](#new-merge-request-page) and fill in the details. +A merge request is created. -## New merge request from a fork +### Add attachments when creating a merge request by email -After forking a project and applying your local changes, complete the following steps to -create a merge request from your fork to contribute back to the main project: +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22723) in GitLab 11.5. -1. On the top bar, select **Menu > Project**. -1. Select **Your Projects**, then select your fork of the repository. -1. In the left menu, go to **Merge requests**, and click **New merge request**. -1. In the **Source branch** drop-down list box, select your branch in your forked repository as the source branch. -1. In the **Target branch** drop-down list box, select the branch from the upstream repository as the target branch. - You can set a [default target project](#set-the-default-target-project) to - change the default target branch (which can be useful when working with a - forked project). -1. After entering the credentials, click **Compare branches and continue** to compare your local changes to the upstream repository. -1. Assign a user to review your changes, and click **Submit merge request**. +You can add commits to a merge request by adding +patches as attachments to the email. All attachments with a filename +ending in `.patch` are considered patches and are processed +ordered by name. -When the changes are merged, your changes are added to the upstream repository and -the branch as per specification. After your work is merged, if you don't intend to -make any other contributions to the upstream project, you can unlink your -fork from its upstream project in the **Settings > Advanced Settings** section by -[removing the forking relationship](../settings/index.md#removing-a-fork-relationship). +The combined size of the patches can be 2 MB. -For further details, [see the forking workflow documentation](../repository/forking_workflow.md). +If the source branch from the subject does not exist, it is +created from the repository's HEAD or the specified target branch. +You can specify the target branch by using the +[`/target_branch` quick action](../quick_actions.md). If the source +branch already exists, the patches are applied on top of it. ## Set the default target project -Merge requests have a source and a target project which are the same, unless +Merge requests have a source and a target project that are the same, unless forking is involved. Creating a fork of the project can cause either of these scenarios when you create a new merge request: @@ -197,57 +163,11 @@ scenarios when you create a new merge request: option). - You target your own fork. -If you want to have merge requests from a fork by default target your own fork -(instead of the upstream project), you can change the default by: +To have merge requests from a fork by default target your own fork +(instead of the upstream project), you can change the default. -1. In your project, go to **Settings > General > Merge requests**. +1. On the top bar, select **Menu > Project**. +1. On the left menu, select **Settings > General > Merge requests**. 1. In the **Target project** section, select the option you want to use for your default target project. 1. Select **Save changes**. - -## New merge request by email **(FREE SELF)** - -_This feature needs [incoming email](../../../administration/incoming_email.md) -to be configured by a GitLab administrator to be available._ It isn't -available in GitLab.com. - -You can create a new merge request by sending an email to a user-specific email -address. The address can be obtained on the merge requests page by clicking on -a **Email a new merge request to this project** button. The subject is -used as the source branch name for the new merge request and the target branch -is the default branch for the project. The message body (if not empty) -is used as the merge request description. You need -["Reply by email"](../../../administration/reply_by_email.md) enabled to use -this feature. If it's not enabled to your instance, you may ask your GitLab -administrator to do so. - -This is a private email address, generated just for you. **Keep it to yourself** -as anyone who has it can create issues or merge requests as if they were you. -You can add this address to your contact list for easy access. - - - -_In GitLab 11.7, we updated the format of the generated email address. -However the older format is still supported, allowing existing aliases -or contacts to continue working._ - -### Adding patches when creating a merge request via e-mail - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22723) in GitLab 11.5. - -You can add commits to the merge request being created by adding -patches as attachments to the email. All attachments with a filename -ending in `.patch` are considered patches and they are processed -ordered by name. - -The combined size of the patches can be 2MB. - -If the source branch from the subject does not exist, it is -created from the repository's HEAD or the specified target branch to -apply the patches. The target branch can be specified using the -[`/target_branch` quick action](../quick_actions.md). If the source -branch already exists, the patches are applied on top of it. - -## Reviewing and managing merge requests - -Once you have submitted a merge request, it can be [reviewed and managed](reviews/index.md) through GitLab. diff --git a/doc/user/project/merge_requests/drafts.md b/doc/user/project/merge_requests/drafts.md index 57850ad7304..a91679ffd63 100644 --- a/doc/user/project/merge_requests/drafts.md +++ b/doc/user/project/merge_requests/drafts.md @@ -79,9 +79,9 @@ draft merge requests: ## Pipelines for drafts -When the [pipelines for merged results](../../../ci/merge_request_pipelines/pipelines_for_merged_results/index.md) +When the [pipelines for merged results](../../../ci/pipelines/pipelines_for_merged_results.md) feature is enabled, draft merge requests run -[merge request pipelines](../../../ci/merge_request_pipelines/index.md) only. +[merge request pipelines](../../../ci/pipelines/merge_request_pipelines.md) only. To run pipelines for merged results, you must [mark the merge request as ready](#mark-merge-requests-as-ready). diff --git a/doc/user/project/merge_requests/fail_fast_testing.md b/doc/user/project/merge_requests/fail_fast_testing.md index 68a63aebb90..15ab2d9c8e2 100644 --- a/doc/user/project/merge_requests/fail_fast_testing.md +++ b/doc/user/project/merge_requests/fail_fast_testing.md @@ -19,7 +19,7 @@ that it believes to be relevant to the input files. `tff` is designed for Ruby on Rails projects, so the `Verify/FailFast` template is configured to run when changes to Ruby files are detected. By default, it runs in -the [`.pre` stage](../../../ci/yaml/README.md#pre-and-post) of a GitLab CI/CD pipeline, +the [`.pre` stage](../../../ci/yaml/index.md#pre-and-post) of a GitLab CI/CD pipeline, before all other stages. ## Example use case @@ -42,8 +42,8 @@ This template requires: - A project built in Rails that uses RSpec for testing. - CI/CD configured to: - Use a Docker image with Ruby available. - - Use [Pipelines for merge requests](../../../ci/merge_request_pipelines/index.md#configuring-pipelines-for-merge-requests) -- [Pipelines for Merged Results](../../../ci/merge_request_pipelines/pipelines_for_merged_results/index.md#enable-pipelines-for-merged-results) + - Use [Pipelines for merge requests](../../../ci/pipelines/merge_request_pipelines.md#configure-pipelines-for-merge-requests) +- [Pipelines for Merged Results](../../../ci/pipelines/pipelines_for_merged_results.md#enable-pipelines-for-merged-results) enabled in the project settings. - A Docker image with Ruby available. The template uses `image: ruby:2.6` by default, but you [can override](../../../ci/yaml/includes.md#overriding-external-template-values) this. @@ -62,7 +62,7 @@ rspec-complete: - bundle exec rspec ``` -To run the most relevant specs first instead of the whole suite, [`include`](../../../ci/yaml/README.md#include) +To run the most relevant specs first instead of the whole suite, [`include`](../../../ci/yaml/index.md#include) the template by adding the following to your CI/CD configuration: ```yaml diff --git a/doc/user/project/merge_requests/img/add_previously_merged_commits_button_v14_1.png b/doc/user/project/merge_requests/img/add_previously_merged_commits_button_v14_1.png Binary files differnew file mode 100644 index 00000000000..e60e869f854 --- /dev/null +++ b/doc/user/project/merge_requests/img/add_previously_merged_commits_button_v14_1.png diff --git a/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png b/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png Binary files differindex a942420d65e..da7d4115bd9 100644 --- a/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png +++ b/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v14.png diff --git a/doc/user/project/merge_requests/img/create_from_email.png b/doc/user/project/merge_requests/img/create_from_email.png Binary files differdeleted file mode 100644 index 14eef473e27..00000000000 --- a/doc/user/project/merge_requests/img/create_from_email.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/create_merge_request_button_v12_6.png b/doc/user/project/merge_requests/img/create_merge_request_button_v12_6.png Binary files differdeleted file mode 100644 index bcbee10e1b7..00000000000 --- a/doc/user/project/merge_requests/img/create_merge_request_button_v12_6.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/new_merge_request_page_v12_6.png b/doc/user/project/merge_requests/img/new_merge_request_page_v12_6.png Binary files differdeleted file mode 100644 index c0f2ba261cb..00000000000 --- a/doc/user/project/merge_requests/img/new_merge_request_page_v12_6.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/previously_merged_commits_v14_1.png b/doc/user/project/merge_requests/img/previously_merged_commits_v14_1.png Binary files differnew file mode 100644 index 00000000000..4f49fad10ad --- /dev/null +++ b/doc/user/project/merge_requests/img/previously_merged_commits_v14_1.png diff --git a/doc/user/project/merge_requests/img/status_checks_widget_passed_v14_0.png b/doc/user/project/merge_requests/img/status_checks_widget_passed_v14_0.png Binary files differnew file mode 100644 index 00000000000..de61ca8b553 --- /dev/null +++ b/doc/user/project/merge_requests/img/status_checks_widget_passed_v14_0.png diff --git a/doc/user/project/merge_requests/img/status_checks_widget_pending_v14_0.png b/doc/user/project/merge_requests/img/status_checks_widget_pending_v14_0.png Binary files differnew file mode 100644 index 00000000000..c4e606bd2f4 --- /dev/null +++ b/doc/user/project/merge_requests/img/status_checks_widget_pending_v14_0.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index b5c51c42ae9..fa90cf524ec 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -27,13 +27,13 @@ important parts of the merge request:  - **Overview**: Contains the description, notifications from pipelines, and a - discussion area for [comment threads](../../discussions/index.md#resolvable-comments-and-threads) + discussion area for [comment threads](../../discussions/index.md#resolve-a-thread)) and [code suggestions](reviews/suggestions.md). The right sidebar provides fields to add assignees, reviewers, labels, and a milestone to your work, and the [merge request widgets area](widgets.md) reports results from pipelines and tests. - **Commits**: Contains a list of commits added to this merge request. For more information, read [Commits tab in merge requests](commits.md). -- **Pipelines**: If configured, contains a list of recent [GitLab CI/CD](../../../ci/README.md) +- **Pipelines**: If configured, contains a list of recent [GitLab CI/CD](../../../ci/index.md) pipelines and their status. - **Changes**: Contains the diffs of files changed by this merge request. You can [configure the display](changes.md). @@ -119,7 +119,7 @@ For a software developer working in a team: 1. Pushes a commit with their final review. 1. [Approves the merge request](approvals/index.md). 1. Sets it to [merge when pipeline succeeds](merge_when_pipeline_succeeds.md). -1. Your changes get deployed to production with [manual actions](../../../ci/yaml/README.md#whenmanual) for GitLab CI/CD. +1. Your changes get deployed to production with [manual actions](../../../ci/yaml/index.md#whenmanual) for GitLab CI/CD. 1. Your implementations were successfully shipped to your customer. For a web developer writing a webpage for your company's website: diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index d1b697add08..7ea785c00ea 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -10,7 +10,7 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/10683) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.2. With Load Performance Testing, you can test the impact of any pending code changes -to your application's backend in [GitLab CI/CD](../../../ci/README.md). +to your application's backend in [GitLab CI/CD](../../../ci/index.md). GitLab uses [k6](https://k6.io/), a free and open source tool, for measuring the system performance of applications under @@ -28,7 +28,7 @@ GET calls to a popular API endpoint in your application to see how it performs. ## How Load Performance Testing works First, define a job in your `.gitlab-ci.yml` file that generates the -[Load Performance report artifact](../../../ci/yaml/README.md#artifactsreportsload_performance). +[Load Performance report artifact](../../../ci/yaml/index.md#artifactsreportsload_performance). GitLab checks this report, compares key load performance metrics between the source and target branches, and then shows the information in a merge request widget: @@ -93,7 +93,7 @@ template that is included with GitLab. NOTE: For large scale k6 tests you need to ensure the GitLab Runner instance performing the actual test is able to handle running the test. Refer to [k6's guidance](https://k6.io/docs/testing-guides/running-large-tests#hardware-considerations) -for spec details. The [default shared GitLab.com runners](../../../ci/runners/README.md#linux-shared-runners) +for spec details. The [default shared GitLab.com runners](../../../ci/runners/build_cloud/linux_build_cloud.md) likely have insufficient specs to handle most large k6 tests. This template runs the @@ -140,7 +140,7 @@ For example, you can override the duration of the test with a CLI option: GitLab only displays the key performance metrics in the MR widget if k6's results are saved via [summary export](https://k6.io/docs/results-visualization/json#summary-export) -as a [Load Performance report artifact](../../../ci/yaml/README.md#artifactsreportsload_performance). +as a [Load Performance report artifact](../../../ci/yaml/index.md#artifactsreportsload_performance). The latest Load Performance artifact available is always used, using the summary values from the test. diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index 21282a55ff2..aace1f58c62 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -27,7 +27,7 @@ the other way around. imports the library. - Prevent a documentation-only merge request from being merged before the merge request implementing the feature to be documented. -- Require an merge request updating a permissions matrix to be merged before merging an +- Require a merge request updating a permissions matrix to be merged before merging a merge request from someone who hasn't yet been granted permissions. It is common for a single logical change to span several merge requests, spread diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index 6c1e33a9ace..d7c9c0f73ee 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -21,7 +21,7 @@ request is updated to show the impending merge. If you can't wait for the pipeline to succeed, you can choose **Merge immediately** in the dropdown menu on the right of the main button. -The author of the merge request and project members with developer permissions can +The author of the merge request and project members with the Developer role can cancel the automatic merge at any time before the pipeline finishes.  @@ -67,8 +67,8 @@ You should be careful to configure CI/CD so that pipelines run for every merge r ### Limitations When this setting is enabled, a merge request is prevented from being merged if there -is no pipeline. This may conflict with some use cases where [`only/except`](../../../ci/yaml/README.md#only--except) -or [`rules`](../../../ci/yaml/README.md#rules) are used and they don't generate any pipelines. +is no pipeline. This may conflict with some use cases where [`only/except`](../../../ci/yaml/index.md#only--except) +or [`rules`](../../../ci/yaml/index.md#rules) are used and they don't generate any pipelines. You should ensure that [there is always a pipeline](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54226) and that it's successful. @@ -101,7 +101,7 @@ for details on avoiding two pipelines for a single merge request. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211482) in GitLab 13.1. -When the **Pipelines must succeed** checkbox is checked, [skipped pipelines](../../../ci/yaml/README.md#skip-pipeline) prevent +When the **Pipelines must succeed** checkbox is checked, [skipped pipelines](../../../ci/yaml/index.md#skip-pipeline) prevent merge requests from being merged. To change this behavior: 1. Navigate to your project's **Settings > General** page. diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md index 317202e9303..16267e13fd5 100644 --- a/doc/user/project/merge_requests/reviews/index.md +++ b/doc/user/project/merge_requests/reviews/index.md @@ -100,7 +100,7 @@ When you submit your review, GitLab: ### Resolving/Unresolving threads -Review comments can also resolve or unresolve [resolvable threads](../../../discussions/index.md#resolvable-comments-and-threads). +Review comments can also resolve or unresolve [resolvable threads](../../../discussions/index.md#resolve-a-thread)). When replying to a comment, a checkbox is displayed to resolve or unresolve the thread after publication. diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 9409cc569a6..8ee068531c8 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -14,7 +14,7 @@ type: index, reference As a reviewer, you're able to suggest code changes with a Markdown syntax in merge request diff threads. Then, the merge request author (or other users with appropriate [permission](../../../permissions.md)) is able to apply these suggestions with a click, -which generates a commit in the merge request authored by the user that applied them. +which generates a commit in the merge request authored by the user that suggested the changes. 1. Choose a line of code to be changed, add a new comment, then select the **Insert suggestion** icon in the toolbar: @@ -42,7 +42,7 @@ which generates a commit in the merge request authored by the user that applied After the author applies a suggestion, it's marked with the **Applied** label, the thread is automatically resolved, and GitLab creates a new commit and pushes the suggested change directly into the codebase in the merge request's -branch. [Developer permission](../../../permissions.md) is required to do so. +branch. The [Developer role](../../../permissions.md) is required to do so. ## Multi-line suggestions diff --git a/doc/user/project/merge_requests/status_checks.md b/doc/user/project/merge_requests/status_checks.md index 775820870f3..70e2d718406 100644 --- a/doc/user/project/merge_requests/status_checks.md +++ b/doc/user/project/merge_requests/status_checks.md @@ -8,11 +8,8 @@ disqus_identifier: 'https://docs.gitlab.com/ee/user/project/merge_requests/statu # External Status Checks **(ULTIMATE)** -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab 14.0. -> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-status-checks). **(ULTIMATE SELF)** +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab 14.0, disabled behind the `:ff_external_status_checks` feature flag. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320783) in GitLab 14.1. WARNING: This feature might not be available to you. Check the **version history** note above for details. @@ -113,6 +110,31 @@ To complete the deletion of the status check you must select the **Remove status check** button. This **permanently** deletes the status check and it **will not** be recoverable. +## Status checks widget + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/327634) in GitLab 14.1. + +The status checks widget displays in merge requests and shows the status of external +status checks: + + + +An organization might have a policy that does not allow merging merge requests if +external status checks do not pass. However, the details in the widget are for informational +purposes only. GitLab does not prevent merging of merge requests that fail status checks. + +While GitLab waits for a response from the external status check, the widget shows +the status checks as `pending`: + + + +After GitLab [receives a response](../../../api/status_checks.md#set-approval-status-of-an-external-status-check) +from the external status check, the widget updates accordingly. + +NOTE: +GitLab cannot guarantee that the external status checks are properly processed by +the related external service. + ## Troubleshooting ### Duplicate value errors @@ -149,30 +171,18 @@ An unexpected response was received from the branches retrieval API. As suggested, you should close the form and reopen again or refresh the page. This error should be temporary, although if it persists please check the [GitLab status page](https://status.gitlab.com/) to see if there is a wider outage. -## Enable or disable status checks **(ULTIMATE SELF)** - -Status checks are under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) -can enable it. +### Failed to load status checks -To enable it: - -```ruby -# For the instance -Feature.enable(:ff_compliance_approval_gates) -# For a single project -Feature.enable(:ff_compliance_approval_gates, Project.find(<project id>)) +```plaintext +Failed to load status checks ``` -To disable it: +An unexpected response was received from the external status checks API. +You should: -```ruby -# For the instance -Feature.disable(:ff_compliance_approval_gates) -# For a single project -Feature.disable(:ff_compliance_approval_gates, Project.find(<project id>) -``` +- Refresh the page in case this error is temporary. +- Check the [GitLab status page](https://status.gitlab.com/) if the problem persists, + to see if there is a wider outage. ## Related links diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index e044d50d246..ce8bfa2d054 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -10,7 +10,7 @@ type: reference, howto > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3708) in GitLab 12.9. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/249811) in GitLab 13.5. -With the help of [GitLab CI/CD](../../../ci/README.md), you can collect the test +With the help of [GitLab CI/CD](../../../ci/index.md), you can collect the test coverage information of your favorite testing or coverage-analysis tool, and visualize this information inside the file diff view of your merge requests (MRs). This will allow you to see which lines are covered by tests, and which lines still require coverage, before the @@ -21,14 +21,14 @@ MR is merged. ## How test coverage visualization works Collecting the coverage information is done via GitLab CI/CD's -[artifacts reports feature](../../../ci/yaml/README.md#artifactsreports). +[artifacts reports feature](../../../ci/yaml/index.md#artifactsreports). You can specify one or more coverage reports to collect, including wildcard paths. GitLab then takes the coverage information in all the files and combines it together. For the coverage analysis to work, you have to provide a properly formatted [Cobertura XML](https://cobertura.github.io/cobertura/) report to -[`artifacts:reports:cobertura`](../../../ci/yaml/README.md#artifactsreportscobertura). +[`artifacts:reports:cobertura`](../../../ci/yaml/index.md#artifactsreportscobertura). This format was originally developed for Java, but most coverage analysis frameworks for other languages have plugins to add support for it, like: @@ -129,7 +129,7 @@ The `source` is ignored if the path does not follow this pattern. The parser ass ### JavaScript example -The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example uses [Mocha](https://mochajs.org/) +The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example uses [Mocha](https://mochajs.org/) JavaScript testing and [nyc](https://github.com/istanbuljs/nyc) coverage-tooling to generate the coverage artifact: @@ -147,7 +147,7 @@ test: #### Maven example -The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Java or Kotlin uses [Maven](https://maven.apache.org/) +The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for Java or Kotlin uses [Maven](https://maven.apache.org/) to build the project and [JaCoCo](https://www.eclemma.org/jacoco/) coverage-tooling to generate the coverage artifact. You can check the [Docker image configuration and scripts](https://gitlab.com/haynes/jacoco2cobertura) if you want to build your own image. @@ -185,7 +185,7 @@ coverage-jdk11: #### Gradle example -The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Java or Kotlin uses [Gradle](https://gradle.org/) +The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for Java or Kotlin uses [Gradle](https://gradle.org/) to build the project and [JaCoCo](https://www.eclemma.org/jacoco/) coverage-tooling to generate the coverage artifact. You can check the [Docker image configuration and scripts](https://gitlab.com/haynes/jacoco2cobertura) if you want to build your own image. @@ -223,7 +223,7 @@ coverage-jdk11: ### Python example -The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Python uses [pytest-cov](https://pytest-cov.readthedocs.io/) to collect test coverage data and [coverage.py](https://coverage.readthedocs.io/) to convert the report to use full relative paths. +The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for Python uses [pytest-cov](https://pytest-cov.readthedocs.io/) to collect test coverage data and [coverage.py](https://coverage.readthedocs.io/) to convert the report to use full relative paths. The information isn't displayed without the conversion. This example assumes that the code for your package is in `src/` and your tests are in `tests.py`: @@ -243,7 +243,7 @@ run tests: ### C/C++ example -The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for C/C++ with +The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for C/C++ with `gcc` or `g++` as the compiler uses [`gcovr`](https://gcovr.com/en/stable/) to generate the coverage output file in Cobertura XML format. diff --git a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md index 55e122dec76..0a9a2a37bfe 100644 --- a/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md +++ b/doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md @@ -17,13 +17,13 @@ or link to useful information directly from merge requests: | [Browser Performance Testing](browser_performance_testing.md) **(PREMIUM)** | Quickly determine the browser performance impact of pending code changes. | | [Load Performance Testing](load_performance_testing.md) **(PREMIUM)** | Quickly determine the server performance impact of pending code changes. | | [Code Quality](code_quality.md) | Analyze your source code quality using the [Code Climate](https://codeclimate.com/) analyzer and show the Code Climate report right in the merge request widget area. | -| [Display arbitrary job artifacts](../../../ci/yaml/README.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../../../ci/pipelines/job_artifacts.md) in merge requests. | -| [GitLab CI/CD](../../../ci/README.md) | Build, test, and deploy your code in a per-branch basis with built-in CI/CD. | +| [Display arbitrary job artifacts](../../../ci/yaml/index.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../../../ci/pipelines/job_artifacts.md) in merge requests. | +| [GitLab CI/CD](../../../ci/index.md) | Build, test, and deploy your code in a per-branch basis with built-in CI/CD. | | [Unit test reports](../../../ci/unit_test_reports.md) | Configure your CI jobs to use Unit test reports, and let GitLab display a report on the merge request so that it's easier and faster to identify the failure without having to check the entire job log. | | [License Compliance](../../compliance/license_compliance/index.md) **(ULTIMATE)** | Manage the licenses of your dependencies. | | [Metrics Reports](../../../ci/metrics_reports.md) **(PREMIUM)** | Display the Metrics Report on the merge request so that it's fast and easy to identify changes to important metrics. | -| [Multi-Project pipelines](../../../ci/multi_project_pipelines.md) **(PREMIUM)** | When you set up GitLab CI/CD across multiple projects, you can visualize the entire pipeline, including all cross-project interdependencies. | -| [Pipelines for merge requests](../../../ci/merge_request_pipelines/index.md) | Customize a specific pipeline structure for merge requests in order to speed the cycle up by running only important jobs. | +| [Multi-Project pipelines](../../../ci/pipelines/multi_project_pipelines.md) **(PREMIUM)** | When you set up GitLab CI/CD across multiple projects, you can visualize the entire pipeline, including all cross-project interdependencies. | +| [Pipelines for merge requests](../../../ci/pipelines/merge_request_pipelines.md) | Customize a specific pipeline structure for merge requests in order to speed the cycle up by running only important jobs. | | [Pipeline Graphs](../../../ci/pipelines/index.md#visualize-pipelines) | View the status of pipelines within the merge request, including the deployment process. | | [Test Coverage visualization](test_coverage_visualization.md) | See test coverage results for merge requests, within the file diff. | diff --git a/doc/user/project/merge_requests/widgets.md b/doc/user/project/merge_requests/widgets.md index 92b2a8f24ef..b0464f3f972 100644 --- a/doc/user/project/merge_requests/widgets.md +++ b/doc/user/project/merge_requests/widgets.md @@ -14,7 +14,7 @@ and the services you configure for your project. ## Pipeline information -If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, +If you've set up [GitLab CI/CD](../../../ci/index.md) in your project, a [merge request](index.md) displays pipeline information in the widgets area of the **Overview** tab: @@ -62,3 +62,9 @@ merge request widget takes you directly to the pages changed, making it easier a faster to preview proposed modifications. [Read more about Review Apps](../../../ci/review_apps/index.md). + +## External status checks **(ULTIMATE)** + +If you have configured [external status checks](status_checks.md) you can +see the status of these checks in merge requests +[in a specific widget](status_checks.md#status-checks-widget). diff --git a/doc/user/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md deleted file mode 100644 index 8b663b8edf8..00000000000 --- a/doc/user/project/merge_requests/work_in_progress_merge_requests.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -redirect_to: 'drafts.md' -remove_date: '2021-05-19' ---- - -This document was moved to [another location](drafts.md). - -<!-- This redirect file can be deleted after <2021-05-19>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> |
