Add latest changes from gitlab-org/gitlab@master

11 files changed, 294 insertions, 6 deletions

diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md
index b4403e1d9b9..998fb534b7b 100644
--- a/doc/api/merge_request_approvals.md
+++ b/doc/api/merge_request_approvals.md
@@ -294,6 +294,7 @@ POST /projects/:id/approval_rules
 | `id`                   | integer or string | yes      | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding) |
 | `name`                 | string  | yes      | The name of the approval rule                                    |
 | `approvals_required`   | integer | yes      | The number of required approvals for this rule                   |
+| `rule_type`            | string  | no       | The type of rule. `any_approver` is a pre-configured default rule with `approvals_required` at `0`. Other rules are `regular`.
 | `user_ids`             | Array   | no       | The ids of users as approvers                                    |
 | `group_ids`            | Array   | no       | The ids of groups as approvers                                   |
 | `protected_branch_ids` | Array   | no       | **(PREMIUM)** The ids of protected branches to scope the rule by |
@@ -379,6 +380,23 @@ POST /projects/:id/approval_rules
 }
 ```
 
+You can increase the default number of 0 required approvers like this:
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
+  --header 'Content-Type: application/json' \
+  --data '{"name": "Any name", "rule_type": "any_approver", "approvals_required": 2}'
+```
+
+Another example is creating an additional, user-specific rule:
+
+```shell
+curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
+  --header 'Content-Type: application/json' \
+  --data '{"name": "Name of your rule", "approvals_required": 3, "user_ids": [123, 456, 789]}' \
+  https://gitlab.example.com/api/v4/projects/<project_id>/approval_rules
+```
+
 ### Update project-level rule
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/11877) in GitLab 12.3.
diff --git a/doc/api/resource_groups.md b/doc/api/resource_groups.md
new file mode 100644
index 00000000000..ce4fa33d7f2
--- /dev/null
+++ b/doc/api/resource_groups.md
@@ -0,0 +1,70 @@
+---
+stage: Release
+group: Release
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+type: concepts, howto
+---
+
+# Resource Groups API
+
+You can read more about [controling the job concurrency with resource groups](../ci/resource_groups/index.md).
+
+## Get a specific resource group
+
+```plaintext
+GET /projects/:id/resource_groups/:key
+```
+
+| Attribute | Type    | Required | Description         |
+|-----------|---------|----------|---------------------|
+| `id`      | integer/string     | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `key`     | string  | yes      | The key of the resource group |
+
+```shell
+curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/resource_groups/production"
+```
+
+Example of response
+
+```json
+{
+  "id": 3,
+  "key": "production",
+  "process_mode": "unordered",
+  "created_at": "2021-09-01T08:04:59.650Z",
+  "updated_at": "2021-09-01T08:04:59.650Z"
+}
+```
+
+## Edit an existing resource group
+
+Updates an existing resource group's properties.
+
+It returns `200` if the resource group was successfully updated. In case of an error, a status code `400` is returned.
+
+```plaintext
+PUT /projects/:id/resource_groups/:key
+```
+
+| Attribute       | Type    | Required                          | Description                      |
+| --------------- | ------- | --------------------------------- | -------------------------------  |
+| `id`            | integer/string | yes                        | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user            |
+| `key`           | string  | yes                               | The key of the resource group |
+| `process_mode`  | string  | no                                | The process mode of the resource group. One of `unordered`, `oldest_first` or `newest_first`. Read [process modes](../ci/resource_groups/index.md#process-modes) for more information. |
+
+```shell
+curl --request PUT --data "process_mode=oldest_first" \
+     --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/resource_groups/production"
+```
+
+Example response:
+
+```json
+{
+  "id": 3,
+  "key": "production",
+  "process_mode": "oldest_first",
+  "created_at": "2021-09-01T08:04:59.650Z",
+  "updated_at": "2021-09-01T08:13:38.679Z"
+}
+```
diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md
index 1b34b520007..78f30b29e06 100644
--- a/doc/ci/environments/deployment_safety.md
+++ b/doc/ci/environments/deployment_safety.md
@@ -60,7 +60,7 @@ The improved pipeline flow **after** using the resource group:
 1. `deploy` job in Pipeline-A finishes.
 1. `deploy` job in Pipeline-B starts running.
 
-For more information, see [`resource_group` keyword in `.gitlab-ci.yml`](../yaml/index.md#resource_group).
+For more information, see [Resource Group documentation](../resource_groups/index.md).
 
 ## Skip outdated deployment jobs
 
diff --git a/doc/ci/resource_groups/index.md b/doc/ci/resource_groups/index.md
new file mode 100644
index 00000000000..e5ff919a70c
--- /dev/null
+++ b/doc/ci/resource_groups/index.md
@@ -0,0 +1,168 @@
+---
+stage: Release
+group: Release
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+description: Control the job concurrency in GitLab CI/CD
+---
+
+# Resource Group **(FREE)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15536) in GitLab 12.7.
+
+By default, pipelines in GitLab CI/CD run in parallel. The parallelization is an important factor to improve
+the feedback loop in merge requests, however, there are some situations that
+you may want to limit the concurrency on deployment
+jobs to run them one by one.
+Resource Group allows you to strategically control
+the concurrency of the jobs for optimizing your continuous deployments workflow with safety.
+
+## Add a resource group
+
+Provided that you have the following pipeline configuration (`.gitlab-ci.yml` file in your repository):
+
+```yaml
+build:
+  stage: build
+  script: echo "Your build script"
+
+deploy:
+  stage: deploy
+  script: echo "Your deployment script"
+  environment: production
+```
+
+Every time you push a new commit to a branch, it runs a new pipeline that has
+two jobs `build` and `deploy`. But if you push multiple commits in a short interval, multiple
+pipelines start running simultaneously, for example:
+
+- The first pipeline runs the jobs `build` -> `deploy`
+- The second pipeline runs the jobs `build` -> `deploy`
+
+In this case, the `deploy` jobs across different pipelines could run concurrently
+to the `production` environment. Running multiple deployment scripts to the same
+infrastructure could harm/confuse the instance and leave it in a corrupted state in the worst case.
+
+In order to ensure that a `deploy` job runs once at a time, you can specify
+[`resource_group` keyword](../yaml/index.md#resource_group) to the concurrency sensitive job:
+
+```yaml
+deploy:
+  ...
+  resource_group: production
+```
+
+With this configuration, the safety on the deployments is assured while you
+can still run `build` jobs concurrently for maximizing the pipeline efficency.
+
+## Requirements
+
+- The basic knowledge of the [GitLab CI/CD pipelines](../pipelines/index.md)
+- The basic knowledge of the [GitLab Environments and Deployments](../environments/index.md)
+- [Developer role](../../user/permissions.md) (or above) in the project to configure CI/CD pipelines.
+
+### Limitations
+
+Only one resource can be attached to a resource group.
+
+## Process modes
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202186) in GitLab 14.3.
+
+FLAG:
+On self-managed GitLab, by default this feature is not available.
+To make it available, ask an administrator to [enable the `ci_resource_group_process_modes` flag](../../administration/feature_flags.md).
+On GitLab.com, this feature is not available.
+The feature is not ready for production use.
+
+You can choose a process mode to strategically control the job concurrency for your deployment preferences.
+The following modes are supported:
+
+- **Unordered:** This is the default process mode that limits the concurrency on running jobs.
+  It's the easiest option to use and useful when you don't care about the execution order
+  of the jobs. It starts processing the jobs whenever a job ready to run.
+- **Oldest first:** This process mode limits the concurrency of the jobs. When a resource is free,
+  it picks the first job from the list of upcoming jobs (`created`, `scheduled`, or `waiting_for_resource` state)
+  that are sorted by pipeline ID in ascending order.
+
+  This mode is useful when you want to ensure that the jobs are executed from the oldest pipeline.
+  This is less efficient compared to the `unordered` mode in terms of the pipeline efficiency,
+  but safer for continuous deployments.
+
+- **Newest first:** This process mode limits the concurrency of the jobs. When a resource is free,
+  it picks the first job from the list of upcoming jobs (`created`, `scheduled` or `waiting_for_resource` state)
+  that are sorted by pipeline ID in descending order.
+
+  This mode is useful when you want to ensure that the jobs are executed from the newest pipeline and
+  cancel all of the old deploy jobs with the [skip outdated deployment jobs](../environments/deployment_safety.md#skip-outdated-deployment-jobs) feature.
+  This is the most efficient option in terms of the pipeline efficiency, but you must ensure that each deployment job is idempotent.
+
+### Change the process mode
+
+To change the process mode of a resource group, you need to use the API and
+send a request to [edit an existing resource group](../../api/resource_groups.md#edit-an-existing-resource-group)
+by specifying the `process_mode`:
+
+- `unordered`
+- `oldest_first`
+- `newest_first`
+
+### An example of difference between the process modes
+
+Consider the following `.gitlab-ci.yml`, where we have two jobs `build` and `deploy`
+each running in their own stage, and the `deploy` job has a resource group set to
+`production`:
+
+```yaml
+build:
+  stage: build
+  script: echo "Your build script"
+
+deploy:
+  stage: deploy
+  script: echo "Your deployment script"
+  environment: production
+  resource_group: production
+```
+
+If three commits are pushed to the project in a short interval, that means that three
+pipelines run almost at the same time:
+
+- The first pipeline runs the jobs `build` -> `deploy`. Let's call this deployment job `deploy-1`.
+- The second pipeline runs the jobs `build` -> `deploy`. Let's call this deployment job `deploy-2`.
+- The third pipeline runs the jobs `build` -> `deploy`. Let's call this deployment job `deploy-3`.
+
+Depending on the process mode of the resource group:
+
+- If the process mode is set to `unordered`:
+  - `deploy-1`, `deploy-2`, and `deploy-3` do not run in parallel.
+  - There is no guarantee on the job execution order, for example, `deploy-1` could run before or after `deploy-3` runs.
+- If the process mode is `oldest_first`:
+  - `deploy-1`, `deploy-2`, and `deploy-3` do not run in parallel.
+  - `deploy-1` runs first, `deploy-2` runs second, and `deploy-3` runs last.
+- If the process mode is `newest_first`:
+  - `deploy-1`, `deploy-2`, and `deploy-3` do not run in parallel.
+  - `deploy-3` runs first, `deploy-2` runs second and `deploy-1` runs last.
+
+## Pipeline-level concurrency control with Cross-Project/Parent-Child pipelines
+
+See the how to [control the pipeline concurrency in cross-project pipelines](../yaml/index.md#pipeline-level-concurrency-control-with-cross-projectparent-child-pipelines).
+
+## API
+
+See the [API documentation](../../api/resource_groups.md).
+
+## Related features
+
+Read more how you can use GitLab for [safe deployments](../environments/deployment_safety.md).
+
+<!-- ## Troubleshooting
+
+Include any troubleshooting steps that you can foresee. If you know beforehand what issues
+one might have when setting this up, or when something is changed, or on upgrading, it's
+important to describe those, too. Think of things that may go wrong and include them here.
+This is important to minimize requests for support, and to avoid doc comments with
+questions that you know someone might ask.
+
+Each scenario can be a third-level heading, e.g. `### Getting error message X`.
+If you have none to add when creating a doc, leave this section in place
+but commented out to help encourage others to add to it in the future. -->
diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md
index fb5748788f7..ab4891f8dd6 100644
--- a/doc/ci/yaml/index.md
+++ b/doc/ci/yaml/index.md
@@ -3859,7 +3859,7 @@ can be deployed to, but there can be only one deployment per device at any given
 The `resource_group` value can only contain letters, digits, `-`, `_`, `/`, `$`, `{`, `}`, `.`, and spaces.
 It can't start or end with `/`.
 
-For more information, see [Deployments Safety](../environments/deployment_safety.md).
+For more information, see [Resource Group documentation](../resource_groups/index.md).
 
 #### Pipeline-level concurrency control with Cross-Project/Parent-Child pipelines
 
diff --git a/doc/development/feature_categorization/index.md b/doc/development/feature_categorization/index.md
index 2f0f8101b53..07d1a981855 100644
--- a/doc/development/feature_categorization/index.md
+++ b/doc/development/feature_categorization/index.md
@@ -72,6 +72,11 @@ class SomeCrossCuttingConcernWorker
 end
 ```
 
+Workers marked as not owned workers will, when possible, use the
+category of their caller (worker or HTTP endpoint) in metrics and logs.
+For instance, `ReactiveCachingWorker` can have multiple feature
+categories in metrics and logs.
+
 ## Rails controllers
 
 Specifying feature categories on controller actions can be done using
diff --git a/doc/development/service_ping/metrics_dictionary.md b/doc/development/service_ping/metrics_dictionary.md
index 8dc2d2255d1..a2eb0ddb821 100644
--- a/doc/development/service_ping/metrics_dictionary.md
+++ b/doc/development/service_ping/metrics_dictionary.md
@@ -6,7 +6,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Metrics Dictionary Guide
 
-This guide describes the [Metrics Dictionary](https://gitlab-org.gitlab.io/growth/product-intelligence/metric-dictionary) and how it's implemented.
+[Service Ping](index.md) metrics are defined in the
+[Metrics Dictionary](https://gitlab-org.gitlab.io/growth/product-intelligence/metric-dictionary).
+This guide describes the dictionary and how it's implemented.
 
 ## Metrics Definition and validation
 
diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md
index 76687db3a3f..035d3ce385f 100644
--- a/doc/development/testing_guide/frontend_testing.md
+++ b/doc/development/testing_guide/frontend_testing.md
@@ -998,7 +998,7 @@ it like so:
 import Subject from '~/feature/the_subject.vue';
 
 // Force Jest to transpile and cache
-// eslint-disable-next-line import/order, no-unused-vars
+// eslint-disable-next-line no-unused-vars
 import _Thing from '~/feature/path/to/thing.vue';
 ```
 
diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md
index 2b3d4dbfc0a..0e5399f9d56 100644
--- a/doc/user/application_security/container_scanning/index.md
+++ b/doc/user/application_security/container_scanning/index.md
@@ -397,7 +397,7 @@ For details on saving and transporting Docker images as a file, see Docker's doc
 We recommend that you set up a [scheduled pipeline](../../../ci/pipelines/schedules.md)
 to fetch the latest vulnerabilities database on a preset schedule.
 Automating this with a pipeline means you do not have to do it manually each time. You can use the
-following `.gitlab-yml.ci` example as a template.
+following `.gitlab-ci.yml` example as a template.
 
 ```yaml
 variables:
diff --git a/doc/user/group/index.md b/doc/user/group/index.md
index caf874cfe28..1b1118aa2f3 100644
--- a/doc/user/group/index.md
+++ b/doc/user/group/index.md
@@ -732,6 +732,31 @@ The group's new subgroups have push rules set for them based on either:
 - The closest parent group with push rules defined.
 - Push rules set at the instance level, if no parent groups have push rules defined.
 
+## Group approval rules **(ULTIMATE)**
+
+> Introduced in GitLab 13.9. [Deployed behind the `group_merge_request_approval_settings_feature_flag` flag](../../administration/feature_flags.md), disabled by default.
+
+FLAG:
+On self-managed GitLab, by default this feature is not available. To make it available,
+per group, ask an administrator to [enable the `group_merge_request_approval_settings_feature_flag` flag](../../administration/feature_flags.md).
+The feature is not ready for production use.
+
+Group approval rules are an in-development feature that provides an interface for managing
+[project merge request approval rules](../project/merge_requests/approvals/index.md) at the
+top-level group level.
+
+The feature is limited to the user interface but the following merge requests extend the UI to:
+
+- [Enforce group settings on projects](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/69750).
+- [Cascade group settings onto projects](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/68476).
+
+To view the merge request approval rules UI for a group:
+
+1. Go to the top-level group's **Settings > General** page.
+1. Expand the **Merge request approvals** section.
+1. Select the settings you want.
+1. Select **Save changes**.
+
 ## Related topics
 
 - [Group wikis](../project/wiki/index.md)
diff --git a/doc/user/markdown.md b/doc/user/markdown.md
index 5eab5fcb513..5e600b6e0d1 100644
--- a/doc/user/markdown.md
+++ b/doc/user/markdown.md
@@ -524,7 +524,7 @@ GitLab Flavored Markdown recognizes the following:
 | specific user                   | `@user_name`               |                                         |                                |
 | specific group                  | `@group_name`              |                                         |                                |
 | entire team                     | `@all`                     |                                         |                                |
-| project                         | `namespace/project`        |                                         |                                |
+| project                         | `namespace/project>`       |                                         |                                |
 | issue                           | ``#123``                   | `namespace/project#123`                 | `project#123`                  |
 | merge request                   | `!123`                     | `namespace/project!123`                 | `project!123`                  |
 | snippet                         | `$123`                     | `namespace/project$123`                 | `project$123`                  |