diff options
Diffstat (limited to 'doc/user/project/merge_requests')
26 files changed, 246 insertions, 112 deletions
diff --git a/doc/user/project/merge_requests/accessibility_testing.md b/doc/user/project/merge_requests/accessibility_testing.md index c518113d3dd..09770bd447d 100644 --- a/doc/user/project/merge_requests/accessibility_testing.md +++ b/doc/user/project/merge_requests/accessibility_testing.md @@ -57,7 +57,7 @@ include: creates an `a11y` job in your CI/CD pipeline, runs Pa11y against the web pages defined in `a11y_urls`, and builds an HTML report for each. -The report for each URL is saved as an artifact that can be [viewed directly in your browser](../../../ci/pipelines/job_artifacts.md#browsing-artifacts). +The report for each URL is saved as an artifact that can be [viewed directly in your browser](../../../ci/pipelines/job_artifacts.md#download-job-artifacts). A single `gl-accessibility.json` artifact is created and saved along with the individual HTML reports. It includes report data for all URLs scanned. diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 7a869ed071a..76913351283 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -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/pipelines/job_artifacts.md#artifactsreportsperformance). +[Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance). 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. @@ -88,7 +88,7 @@ The example uses a CI/CD template that is included in all GitLab installations s or older, you must [add the configuration manually](#gitlab-versions-123-and-older) 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/pipelines/job_artifacts.md#artifactsreportsperformance) +and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsperformance) 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/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 4c9a6557320..f531cd52af1 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -9,7 +9,7 @@ type: reference, concepts GitLab implements Git's powerful feature to [cherry-pick any commit](https://git-scm.com/docs/git-cherry-pick "Git cherry-pick documentation") -with introducing a **Cherry-pick** button in merge requests and commit details. +with a **Cherry-pick** button in merge requests and commit details. ## Cherry-picking a merge request @@ -60,6 +60,46 @@ mainline: git cherry-pick -m 2 7a39eb0 ``` +### Cherry-pick into a project + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21268) in GitLab 13.11. +> - 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-cherry-picking-into-a-project). **(FREE SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +You can use the GitLab UI to cherry-pick merge requests into a project, even if the +merge request is from a fork: + +1. In the merge request's secondary menu, click **Commits** to display the commit details page. +1. Click on the **Options** dropdown and select **Cherry-pick** to show the cherry-pick modal. +1. In **Pick into project** and **Pick into branch**, select the destination project and branch: +  +1. (Optional) Select **Start a new merge request** if you're ready to create a merge request. +1. Click **Cherry-pick**. + +### Enable or disable cherry-picking into a project **(FREE SELF)** + +Cherry-picking into a project 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(:pick_into_project) +``` + +To disable it: + +```ruby +Feature.disable(:pick_into_project) +``` + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 42c2547a618..0fe1b9801cc 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -15,7 +15,7 @@ source code quality using GitLab Code Quality. Code Quality: -- Uses [Code Climate Engines](https://codeclimate.com), which are +- Uses [Engines](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 @@ -33,7 +33,7 @@ Code Quality: Going a step further, GitLab can show the Code Quality report right in the merge request widget area if a report from the target branch is available to compare to: - + Watch a quick walkthrough of Code Quality in action: @@ -49,6 +49,26 @@ For one customer, the auditor found that having Code Quality, SAST, and Containe See also the Code Climate list of [Supported Languages for Maintainability](https://docs.codeclimate.com/docs/supported-languages-for-maintainability). +## Code Quality in diff view **(ULTIMATE)** + +> - [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. + +Changes to files in merge requests can cause Code Quality to fall if merged. In these cases, +an indicator is displayed (**{information-o}** **Code Quality**) on the file in the merge request's diff view. For example: + + + +To enable this feature, a GitLab administrator can run the following in a +[Rails console](../../../administration/operations/rails_console.md): + +```ruby +# For the instance +Feature.enable(:codequality_mr_diff) +# For a single project +Feature.enable(:codequality_mr_diff, Project.find(<project id>)) +``` + ## Use cases For instance, consider the following workflow: @@ -85,7 +105,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/pipelines/job_artifacts.md#artifactsreportscodequality) +[Code Quality report artifact](../../../ci/yaml/README.md#artifactsreportscodequality) that you can later download and analyze. It's also possible to override the URL to the Code Quality image by @@ -242,12 +262,11 @@ 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, [in the project settings](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui) - or [CI/CD configuration](../../../ci/variables/README.md#create-a-custom-variable-in-the-ui). +- For [the whole project](../../../ci/variables/README.md#custom-cicd-variables). - For a single pipeline run: 1. Go to **CI/CD > Pipelines** - 1. Click **Run Pipeline** + 1. Click **Run pipeline** 1. Add `CODE_QUALITY_DISABLED` as the variable key, with any value. ### Using with merge request pipelines @@ -309,7 +328,7 @@ do this: 1. Define a job in your `.gitlab-ci.yml` file that generates the [Code Quality report - artifact](../../../ci/pipelines/job_artifacts.md#artifactsreportscodequality). + artifact](../../../ci/yaml/README.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). @@ -347,7 +366,11 @@ NOTE: Although the Code Climate spec supports more properties, those are ignored by GitLab. -## Code Quality reports +## Code Quality reports **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21527) in GitLab Premium 12.9. + + After the Code Quality job completes: @@ -355,7 +378,7 @@ After the Code Quality job completes: The Code Quality widget in the merge request compares the reports from the base and head of the branch, then lists any violations that are resolved or created when the branch is merged. - The full JSON report is available as a - [downloadable artifact](../../../ci/pipelines/job_artifacts.md#downloading-artifacts) + [downloadable artifact](../../../ci/pipelines/job_artifacts.md#download-job-artifacts) for the `code_quality` job. - The full list of code quality violations generated by a pipeline is shown in the Code Quality tab of the Pipeline Details page. **(PREMIUM)** @@ -552,3 +575,8 @@ plugins: enabled: true channel: rubocop-0-67 ``` + +### No Code Quality appears on merge requests when using custom tool + +If your merge requests do not show any code quality changes when using a custom tool, +ensure that the line property is an `integer`. diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 58e80504212..3a5a581198b 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -172,6 +172,9 @@ create a merge request from your fork to contribute back to the main project: 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**. @@ -183,6 +186,24 @@ fork from its upstream project in the **Settings > Advanced Settings** section b For further details, [see the forking workflow documentation](../repository/forking_workflow.md). +## Set the default target project + +Merge requests have a source and a target project which 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: + +- You target an upstream project (the project you forked, and the default + 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: + +1. In your project, go to **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) diff --git a/doc/user/project/merge_requests/csv_export.md b/doc/user/project/merge_requests/csv_export.md index f4843b96c99..f973d9220f2 100644 --- a/doc/user/project/merge_requests/csv_export.md +++ b/doc/user/project/merge_requests/csv_export.md @@ -41,5 +41,5 @@ The following table shows what attributes will be present in the CSV. ## Limitations -- Export merge requests to CSV is not available at the Group’s merge request list. +- Export merge requests to CSV is not available at the Group's merge request list. - As the merge request CSV file is sent as an email attachment, the size is limited to 15MB to ensure successful delivery across a range of email providers. If you need to minimize the size of the file, you can narrow the search before export. For example, you can set up exports of open and closed merge requests in separate files. diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md index f25228729cf..1bb333dcb14 100644 --- a/doc/user/project/merge_requests/getting_started.md +++ b/doc/user/project/merge_requests/getting_started.md @@ -206,10 +206,10 @@ is set for deletion, the merge request widget displays the ### Branch retargeting on merge **(FREE SELF)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/320902) in GitLab 13.9. -> - It's [deployed behind a feature flag](../../feature_flags.md), disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/320895) on GitLab 13.10. -> - It's recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [disable it](#enable-or-disable-branch-retargeting-on-merge). **(FREE SELF)** +> - [Deployed behind a feature flag](../../feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/320895) in GitLab 13.10. +> - Recommended for production use. +> - To use in GitLab self-managed instances, ask a GitLab administrator to [disable it](#enable-or-disable-branch-retargeting-on-merge). **(FREE SELF)** In specific circumstances, GitLab can retarget the destination branch of open merge request, if the destination branch merges while the merge request is @@ -230,8 +230,6 @@ GitLab retargets up to four merge requests when their target branch is merged in `master`, so you don't need to perform this operation manually. Merge requests from forks are not retargeted. -The feature today works only one a merge. Clicking the `Remove source branch` button -after the merge request was merged will not automatically retarget merge request. The feature today works only on merge. Clicking the **Remove source branch** button after the merge request was merged will not automatically retarget a merge request. This improvement is [tracked as a follow-up](https://gitlab.com/gitlab-org/gitlab/-/issues/321559). diff --git a/doc/user/project/merge_requests/img/cherry_pick_into_project_v13_11.png b/doc/user/project/merge_requests/img/cherry_pick_into_project_v13_11.png Binary files differnew file mode 100644 index 00000000000..ada036255f2 --- /dev/null +++ b/doc/user/project/merge_requests/img/cherry_pick_into_project_v13_11.png diff --git a/doc/user/project/merge_requests/img/code_quality.png b/doc/user/project/merge_requests/img/code_quality.png Binary files differdeleted file mode 100644 index 1e7dd64baff..00000000000 --- a/doc/user/project/merge_requests/img/code_quality.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v13_11.png b/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v13_11.png Binary files differnew file mode 100644 index 00000000000..0fcdc252735 --- /dev/null +++ b/doc/user/project/merge_requests/img/code_quality_mr_diff_report_v13_11.png diff --git a/doc/user/project/merge_requests/img/code_quality_report_13_11.png b/doc/user/project/merge_requests/img/code_quality_report_13_11.png Binary files differnew file mode 100644 index 00000000000..36341548328 --- /dev/null +++ b/doc/user/project/merge_requests/img/code_quality_report_13_11.png diff --git a/doc/user/project/merge_requests/img/code_quality_widget_13_11.png b/doc/user/project/merge_requests/img/code_quality_widget_13_11.png Binary files differnew file mode 100644 index 00000000000..57978a0ed96 --- /dev/null +++ b/doc/user/project/merge_requests/img/code_quality_widget_13_11.png diff --git a/doc/user/project/merge_requests/img/commit_nav_v13_11.png b/doc/user/project/merge_requests/img/commit_nav_v13_11.png Binary files differnew file mode 100644 index 00000000000..a9bc8fa6bee --- /dev/null +++ b/doc/user/project/merge_requests/img/commit_nav_v13_11.png diff --git a/doc/user/project/merge_requests/img/commit_nav_v13_4.png b/doc/user/project/merge_requests/img/commit_nav_v13_4.png Binary files differdeleted file mode 100644 index 0ae6ce32693..00000000000 --- a/doc/user/project/merge_requests/img/commit_nav_v13_4.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/merge_request_tab_position_v12_6.png b/doc/user/project/merge_requests/img/merge_request_tab_position_v12_6.png Binary files differdeleted file mode 100644 index 9284e58f456..00000000000 --- a/doc/user/project/merge_requests/img/merge_request_tab_position_v12_6.png +++ /dev/null diff --git a/doc/user/project/merge_requests/img/merge_request_tab_position_v13_11.png b/doc/user/project/merge_requests/img/merge_request_tab_position_v13_11.png Binary files differnew file mode 100644 index 00000000000..52c715840f1 --- /dev/null +++ b/doc/user/project/merge_requests/img/merge_request_tab_position_v13_11.png diff --git a/doc/user/project/merge_requests/img/scoped_to_protected_branch_v13_10.png b/doc/user/project/merge_requests/img/scoped_to_protected_branch_v13_10.png Binary files differindex b1c2e147134..a6636f0bc7f 100644 --- a/doc/user/project/merge_requests/img/scoped_to_protected_branch_v13_10.png +++ b/doc/user/project/merge_requests/img/scoped_to_protected_branch_v13_10.png diff --git a/doc/user/project/merge_requests/img/update_approval_rule_v13_10.png b/doc/user/project/merge_requests/img/update_approval_rule_v13_10.png Binary files differindex c0cc0db600c..c5596b965ff 100644 --- a/doc/user/project/merge_requests/img/update_approval_rule_v13_10.png +++ b/doc/user/project/merge_requests/img/update_approval_rule_v13_10.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 99e0193d496..1fed30dc589 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -7,12 +7,10 @@ type: index, reference # Merge requests **(FREE)** -Whenever you need to merge one branch into another branch with GitLab, you -must create a merge request (MR). +Merge requests (MRs) are the way you check source code changes into a branch. -Using merge requests, you can visualize and collaborate on proposed changes to -source code. Merge requests display information about the proposed code changes, -including: +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. @@ -20,55 +18,50 @@ including: - A comment section for discussion threads. - The list of commits. -Based on your workflow, after review you can merge a merge request into its -target branch. - To get started, read the [introduction to merge requests](getting_started.md). -## Use cases +## Merge request workflows -A. Consider you're a software developer working in a team: +For a software developer working in a team: -1. You checkout a new branch, and submit your changes through a merge request -1. You gather feedback from your team -1. You work on the implementation optimizing code with [Code Quality reports](code_quality.md) -1. You verify your changes with [Unit test reports](../../../ci/unit_test_reports.md) in GitLab CI/CD -1. You avoid using dependencies whose license is not compatible with your project with [License Compliance reports](../../compliance/license_compliance/index.md) **(ULTIMATE)** -1. You request the [approval](merge_request_approvals.md) from your manager **(STARTER)** +1. You checkout a new branch, and submit your changes through a merge request. +1. You gather feedback from your team. +1. You work on the implementation optimizing code with [Code Quality reports](code_quality.md). +1. You verify your changes with [Unit test reports](../../../ci/unit_test_reports.md) in GitLab CI/CD. +1. You avoid using dependencies whose license is not compatible with your project with [License Compliance reports](../../compliance/license_compliance/index.md). +1. You request the [approval](merge_request_approvals.md) from your manager. 1. Your manager: - 1. Pushes a commit with their final review - 1. [Approves the merge request](merge_request_approvals.md) **(STARTER)** - 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 implementations were successfully shipped to your customer - -B. Consider you're 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 -1. You gather feedback from your reviewers -1. Your changes are previewed with [Review Apps](../../../ci/review_apps/index.md) -1. You request your web designers for their implementation -1. You request the [approval](merge_request_approvals.md) from your manager **(STARTER)** -1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/) -1. Your production team [cherry picks](cherry_pick_changes.md) the merge commit into production + 1. Pushes a commit with their final review. + 1. [Approves the merge request](merge_request_approvals.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 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. +1. You gather feedback from your reviewers. +1. You preview your changes with [Review Apps](../../../ci/review_apps/index.md). +1. You request your web designers for their implementation. +1. You request the [approval](merge_request_approvals.md) from your manager. +1. Once approved, your merge request is [squashed and merged](squash_and_merge.md), and [deployed to staging with GitLab Pages](https://about.gitlab.com/blog/2021/02/05/ci-deployment-and-environments/). +1. Your production team [cherry picks](cherry_pick_changes.md) the merge commit into production. ## Merge request navigation tabs at the top > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33813) in GitLab 12.6. This positioning is experimental. -So far, the navigation tabs present in merge requests to display **Discussion**, -**Commits**, **Pipelines**, and **Changes** were located after the merge request +In GitLab 12.5 and earlier, navigation tabs in merge requests (**Discussion**, +**Commits**, **Pipelines**, and **Changes**) were located after the merge request widget. -To facilitate this navigation without having to scroll up and down through the page -to find these tabs, based on user feedback, we're experimenting with a new positioning -of these tabs. They are now located at the top of the merge request, with a new -**Overview** tab, containing the description of the merge request followed by the -widget. Next to **Overview**, you can find **Pipelines**, **Commits**, and **Changes**. +To facilitate navigation without scrolling, and based on user feedback, the tabs are +now located at the top of the merge request tab. A new **Overview** tab was added, +and next to **Overview** are **Commits**, **Pipelines**, and **Changes**. - + -Please note this change is currently behind a feature flag which is enabled by default. For +This change is behind a feature flag that is enabled by default. For self-managed instances, it can be disabled through the Rails console by a GitLab administrator with the following command: @@ -76,23 +69,9 @@ administrator with the following command: Feature.disable(:mr_tabs_position) ``` -## Creating merge requests - -Learn [how to create a merge request](creating_merge_requests.md). - -## Reviewing and managing merge requests - -See the features at your disposal to [review and manage merge requests](reviewing_and_managing_merge_requests.md). - -## Testing and reports in merge requests - -Learn about the options for [testing and reports](testing_and_reports_in_merge_requests.md) on the changes in a merge request. - -## Authorization for merge requests - -There are two main ways to have a merge request flow with GitLab: - -1. Working with [protected branches](../protected_branches.md) in a single repository -1. Working with forks of an authoritative project +## Related topics -[Learn more about the authorization for merge requests.](authorization_for_merge_requests.md) +- [Create a merge request](creating_merge_requests.md) +- [Review and manage merge requests](reviewing_and_managing_merge_requests.md) +- [Authorization for merge requests](authorization_for_merge_requests.md) +- [Testing and reports](testing_and_reports_in_merge_requests.md) diff --git a/doc/user/project/merge_requests/load_performance_testing.md b/doc/user/project/merge_requests/load_performance_testing.md index e8062fadcfe..865a18a6a05 100644 --- a/doc/user/project/merge_requests/load_performance_testing.md +++ b/doc/user/project/merge_requests/load_performance_testing.md @@ -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/pipelines/job_artifacts.md#artifactsreportsload_performance). +[Load Performance report artifact](../../../ci/yaml/README.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: @@ -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/pipelines/job_artifacts.md#artifactsreportsload_performance). +as a [Load Performance report artifact](../../../ci/yaml/README.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_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 3d3e04842f8..835350ade44 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -13,6 +13,7 @@ type: reference, concepts Code review is an essential practice of every successful project. Approving a merge request is an important part of the review process, as it clearly communicates the ability to merge the change. +A [merge request approvals API](../../../api/merge_request_approvals.md) is also available. ## Optional Approvals @@ -23,6 +24,39 @@ This provides a consistent mechanism for reviewers to approve merge requests, an maintainers know a change is ready to merge. Approvals in Free are optional, and do not prevent a merge request from being merged when there is no approval. +## External approvals **(ULTIMATE)** + +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab Ultimate 13.10. +> - 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](../../../api/merge_request_approvals.md#enable-or-disable-external-project-level-mr-approvals). **(ULTIMATE SELF)** + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +When you create an external approval rule, the following merge request actions sends information +about a merge request to a third party service: + +- Create +- Change +- Close + +This action enables use-cases such as: + +- Integration with 3rd party workflow tools, such as [ServiceNow](https://www.servicenow.co.uk/). +- Integration with custom tools designed to approve merge requests from outside of GitLab. + +You can find more information about use-cases, development timelines and the feature discovery in +the [External API approval rules epic](https://gitlab.com/groups/gitlab-org/-/epics/3869). + +The intention for this feature is to allow those 3rd party tools to approve a merge request similarly to how users current do. + +NOTE: +The lack of an external approval does not block the merging of a merge request. + +You can modify external approval rules through the [REST API](../../../api/merge_request_approvals.md#external-project-level-mr-approvals). + ## Required Approvals **(PREMIUM)** > - [Introduced](https://about.gitlab.com/releases/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only) in GitLab Enterprise Edition 7.12. @@ -53,7 +87,7 @@ be merged, and optionally which users should do the approving. Approvals can be If no approval rules are defined, any user can approve a merge request. However, the default minimum number of required approvers can still be set in the -[project settings for merge request approvals](#merge-request-approvals-project-settings). +[settings for merge request approvals](#approval-settings). You can opt to define one single rule to approve a merge request among the available rules or choose more than one with [multiple approval rules](#multiple-approval-rules). @@ -114,7 +148,7 @@ or higher [permissions](../../permissions.md). To enable this merge request approval rule: 1. Navigate to your project's **Settings > General** and expand - **Merge request approvals**. + **Merge request (MR) approvals**. 1. Locate **Any eligible user** and choose the number of approvals required.  @@ -145,7 +179,7 @@ To enable this access: 1. [Share the project with your group](../members/share_project_with_groups.md#sharing-a-project-with-a-group-of-users), based on the Reporter role. 1. Navigate to your project's **Settings > General**, and in the - **Merge request approvals** section, click **Expand**. + **Merge request (MR) approvals** section, click **Expand**. 1. Select **Add approval rule** or **Update approval rule**. 1. [Add the group](../../group/index.md#create-a-group) to the permission list. @@ -155,7 +189,7 @@ To enable this access: To add or edit the default merge request approval rule: -1. Navigate to your project's **Settings > General** and expand **Merge request approvals**. +1. Navigate to your project's **Settings > General** and expand **Merge request (MR) approvals**. 1. Click **Add approval rule**, or **Edit**. - Add or change the **Rule name**. @@ -235,14 +269,14 @@ reduces the number of approvals left for all rules that the approver belongs to. Approval rules are often only relevant to specific branches, like `master`. When configuring [**Default Approval Rules**](#adding--editing-a-default-approval-rule) these can be scoped to all the protected branches at once by navigating to your project's -**Settings**, expanding **Merge request approvals**, and selecting **Any branch** from +**Settings**, expanding **Merge request (MR) approvals**, and selecting **Any branch** from the **Target branch** dropdown. Alternatively, you can select a very specific protected branch from the **Target branch** dropdown:  -To enable this configuration, see [Code Owner’s approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners). +To enable this configuration, see [Code Owner's approvals for protected branches](../protected_branches.md#protected-branches-approval-by-code-owners). ### Adding or removing an approval @@ -278,10 +312,10 @@ else blocking it. Note that the merge request could still be blocked by other co such as merge conflicts, [pending discussions](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved), or a [failed CI/CD pipeline](merge_when_pipeline_succeeds.md). -### Merge request approvals project settings +### Approval settings -The project settings for Merge request approvals are found by going to -**Settings > General** and expanding **Merge request approvals**. +The settings for Merge Request Approvals are found by going to +**Settings > General** and expanding **Merge request (MR) approvals**. #### Prevent overriding default approvals @@ -289,7 +323,7 @@ Regardless of the approval rules you choose for your project, users can edit the request, overriding the rules you set as [default](#adding--editing-a-default-approval-rule). To prevent that from happening: -1. Uncheck the **Allow overrides to approval lists per merge request (MR).** checkbox. +1. Select the **Prevent users from modifying MR approval rules in merge requests.** checkbox. 1. Click **Save changes**. #### Resetting approvals on push @@ -314,7 +348,7 @@ from the UI. However, approvals are reset if the target branch is changed. By default, projects are configured to prevent merge requests from being approved by their own authors. To change this setting: -1. Go to your project's **Settings > General**, expand **Merge request approvals**. +1. Go to your project's **Settings > General**, expand **Merge request (MR) approvals**. 1. Uncheck the **Prevent MR approval by the author.** checkbox. 1. Click **Save changes**. diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md index 2d7ba853258..fc5cc4d958b 100644 --- a/doc/user/project/merge_requests/merge_request_dependencies.md +++ b/doc/user/project/merge_requests/merge_request_dependencies.md @@ -17,9 +17,9 @@ then it cannot be merged until its dependency is itself merged. NOTE: Merge requests dependencies are a **PREMIUM** feature, but this restriction is -only enforced for the dependent merge request. A merge request in a **FREE** or -**STARTER** project can be a dependency of a **PREMIUM** merge request, but not -vice-versa. +only enforced for the dependent merge request. A merge request in a **FREE** +project can be a dependency of a **PREMIUM** merge request, but not +the other way around. ## Use cases diff --git a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md index 406a79217d0..aba75403a2a 100644 --- a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md +++ b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md @@ -28,6 +28,39 @@ You can [search and filter the results](../../search/index.md#filtering-issue-an  +## Cached merge request count + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299542) in GitLab 13.11. +> - It's [deployed behind a feature flag](../../feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-cached-merge-request-count). + +WARNING: +This feature might not be available to you. Check the **version history** note above for details. + +In a group, the sidebar displays the total count of open merge requests and this value is cached if higher +than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. + +### Enable or disable cached merge request count **(FREE SELF)** + +Cached merge request count in the left sidebar is under development but ready for production use. It is +deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md) +can disable it. + +To disable it: + +```ruby +Feature.disable(:cached_sidebar_merge_requests_count) +``` + +To enable it: + +```ruby +Feature.enable(:cached_sidebar_merge_requests_count) +``` + ## Semi-linear history merge requests A merge commit is created for every merge, but the branch is only merged if @@ -112,10 +145,10 @@ To seamlessly navigate among commits in a merge request: 1. Select a commit to open it in the single-commit view. 1. Navigate through the commits by either: - - Selecting **Prev** and **Next** buttons on the top-right of the page. + - Selecting **Prev** and **Next** buttons below the tab buttons. - Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts. - + ### Incrementally expand merge request diffs @@ -235,7 +268,7 @@ the **Merge** button is colored red. When a merge request is merged, you can see the post-merge pipeline status of the branch the merge request was merged into. For example, when a merge request -is merged into the `master` branch and then triggers a deployment to the staging +is merged into the [default branch](../repository/branches/default.md) and then triggers a deployment to the staging environment. Ongoing deployments are shown, and the state (deploying or deployed) diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index f500c18a32e..4315e5a0305 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -7,8 +7,7 @@ type: reference, concepts # Squash and merge **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/1024) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.17. -> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) from [GitLab Starter](https://about.gitlab.com/pricing/)to GitLab Free in 11.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/18956) to GitLab Free in 11.0. With squash and merge you can combine all your merge request's commits into one and retain a clean history. @@ -31,10 +30,7 @@ NOTE: The squashed commit in this example is followed by a merge commit, because the merge method for this repository uses a merge commit. You can disable merge commits in **Project Settings > General > Merge requests > Merge method > Fast-forward merge**. -The squashed commit's commit message is either: - -- Taken from the first multi-line commit message in the merge. -- The merge request's title if no multi-line commit message is found. +The squashed commit's default commit message is taken from the merge request title. NOTE: This only takes effect if there are at least 2 commits. As there is nothing to squash, the commit message does not change if there is only 1 commit. @@ -105,11 +101,11 @@ squashing can itself be considered equivalent to rebasing. ## Squash Commits Options > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17613) in GitLab 13.2. -> - It was deployed behind a feature flag, disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39382) on GitLab 13.3. -> - It's enabled on GitLab.com. -> - It can be enabled per project. -> - It's recommended for production use. +> - Deployed behind a feature flag, disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39382) in GitLab 13.3. +> - Enabled on GitLab.com. +> - Can be enabled per project. +> - Recommended for production use. With Squash Commits Options you can configure the behavior of Squash and Merge for your project. To set it up, navigate to your project's **Settings > General** and expand **Merge requests**. diff --git a/doc/user/project/merge_requests/test_coverage_visualization.md b/doc/user/project/merge_requests/test_coverage_visualization.md index 02b557e22b9..147171e8488 100644 --- a/doc/user/project/merge_requests/test_coverage_visualization.md +++ b/doc/user/project/merge_requests/test_coverage_visualization.md @@ -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/pipelines/job_artifacts.md#artifactsreports). +[artifacts reports feature](../../../ci/yaml/README.md#artifactsreports). You can specify one or more coverage reports to collect, including wildcard paths. GitLab will then take the coverage information in all the files and combine 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/pipelines/job_artifacts.md#artifactsreportscobertura). +[`artifacts:reports:cobertura`](../../../ci/yaml/README.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: @@ -55,6 +55,11 @@ NOTE: A limit of 100 `<source>` nodes for Cobertura format XML files applies. If your Cobertura report exceeds 100 nodes, there can be mismatches or no matches in the Merge Request diff view. +### Artifact expiration + +By default, the [pipeline artifact](../../../ci/pipelines/pipeline_artifacts.md#storage) used +to draw the visualization on the Merge Request expires **one week** after creation. + ### Automatic class path correction > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217664) in GitLab 13.8. 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 9661a02a767..cc0be389891 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 @@ -19,7 +19,7 @@ or link to useful information directly from merge requests: | [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. | -| [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. | +| [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. | |
