Add latest changes from gitlab-org/gitlab@master

16 files changed, 274 insertions, 56 deletions

diff --git a/doc/api/graphql/reference/gitlab_schema.graphql b/doc/api/graphql/reference/gitlab_schema.graphql
index cc3a1019c48..c682baed752 100644
--- a/doc/api/graphql/reference/gitlab_schema.graphql
+++ b/doc/api/graphql/reference/gitlab_schema.graphql
@@ -13050,6 +13050,11 @@ type MergeRequestConnection {
   Information to aid in pagination.
   """
   pageInfo: PageInfo!
+
+  """
+  Total sum of time to merge, in seconds, for the collection of merge requests
+  """
+  totalTimeToMerge: Float
 }
 
 """
diff --git a/doc/api/graphql/reference/gitlab_schema.json b/doc/api/graphql/reference/gitlab_schema.json
index 7066f2b5dc6..a283e437b23 100644
--- a/doc/api/graphql/reference/gitlab_schema.json
+++ b/doc/api/graphql/reference/gitlab_schema.json
@@ -36011,6 +36011,20 @@
               },
               "isDeprecated": false,
               "deprecationReason": null
+            },
+            {
+              "name": "totalTimeToMerge",
+              "description": "Total sum of time to merge, in seconds, for the collection of merge requests",
+              "args": [
+
+              ],
+              "type": {
+                "kind": "SCALAR",
+                "name": "Float",
+                "ofType": null
+              },
+              "isDeprecated": false,
+              "deprecationReason": null
             }
           ],
           "inputFields": null,
diff --git a/doc/ci/README.md b/doc/ci/README.md
index e860352b310..8c1ea3b75ea 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -73,7 +73,7 @@ to your needs:
 
 ![Use a `.gitlab-ci.yml` template](img/add_file_template_11_10.png)
 
-While building your `.gitlab-ci.yml`, you can use the [CI/CD configuration visualization](yaml/visualization.md) to facilate your writing experience.
+While building your `.gitlab-ci.yml`, you can use the [CI/CD configuration visualization](yaml/visualization.md) to facilitate your writing experience.
 
 For a broader overview, see the [CI/CD getting started](quick_start/README.md) guide.
 
diff --git a/doc/development/agent/identity.md b/doc/development/agent/identity.md
new file mode 100644
index 00000000000..3624bf15c26
--- /dev/null
+++ b/doc/development/agent/identity.md
@@ -0,0 +1,94 @@
+---
+stage: Configure
+group: Configure
+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/#designated-technical-writers
+---
+
+# Kubernetes Agent identity and authentication **(PREMIUM ONLY)**
+
+This page uses the word `agent` to describe the concept of the
+GitLab Kubernetes Agent. The program that implements the concept is called `agentk`.
+Read the
+[architecture page](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md)
+for more information.
+
+## Agent identity and name
+
+In a GitLab installation, each agent must have a unique, immutable name. This
+name must be unique in the project the agent is attached to, and this name must
+follow the [DNS label standard from RFC 1123](https://tools.ietf.org/html/rfc1123).
+The name must:
+
+- Contain at most 63 characters.
+- Contain only lowercase alphanumeric characters or `-`.
+- Start with an alphanumeric character.
+- End with an alphanumeric character.
+
+Kubernetes uses the
+[same naming restriction](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-label-names)
+for some names.
+
+The regex for names is: `/\A[a-z0-9]([-a-z0-9]*[a-z0-9])?\z/`.
+
+## Multiple agents in a cluster
+
+A Kubernetes cluster may have 0 or more agents running in it. Each agent likely
+has a different configuration. Some may enable features A and B, and some may
+enable features B and C. This flexibility enables different groups of people to
+use different features of the agent in the same cluster.
+
+For example, [Priyanka (Platform Engineer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#priyanka-platform-engineer)
+may want to use cluster-wide features of the agent, while
+[Sasha (Software Developer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sasha-software-developer)
+uses the agent that only has access to a particular namespace.
+
+Each agent is likely running using a
+[`ServiceAccount`](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/),
+a distinct Kubernetes identity, with a distinct set of permissions attached to it.
+These permissions enable the agent administrator to follow the
+[principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege)
+and minimize the permissions each particular agent needs.
+
+## Kubernetes Agent authentication
+
+When adding a new agent, GitLab provides the user with a bearer access token. The
+agent uses this token to authenticate with GitLab. This token is a random string
+and does not encode any information in it, but it is secret and must
+be treated with care. Store it as a `Secret` in Kubernetes.
+
+Each agent can have 0 or more tokens in GitLab's database. Having several valid
+tokens helps you rotate tokens without needing to re-register an agent. Each token
+record in the database has the following fields:
+
+- Agent identity it belongs to.
+- Token value. Encrypted at rest.
+- Creation time.
+- Who created it.
+- Revocation flag to mark token as revoked.
+- Revocation time.
+- Who revoked it.
+- A text field to store any comments the administrator may want to make about the token for future self.
+
+Tokens can be managed by users with `maintainer` and higher level of
+[permissions](../../user/permissions.md).
+
+Tokens are immutable, and only the following fields can be updated:
+
+- Revocation flag. Can only be updated to `true` once, but immutable after that.
+- Revocation time. Set to the current time when revocation flag is set, but immutable after that.
+- Comments field. Can be updated any number of times, including after the token has been revoked.
+
+The agent sends its token, along with each request, to GitLab to authenticate itself.
+For each request, GitLab checks the token's validity:
+
+- Does the token exist in the database?
+- Has the token been revoked?
+
+This information may be cached for some time to reduce load on the database.
+
+## Kubernetes Agent authorization
+
+GitLab provides the following information in its response for a given Agent access token:
+
+- Agent configuration Git repository. (The agent doesn't support per-folder authorization.)
+- Agent name.
diff --git a/doc/development/agent/index.md b/doc/development/agent/index.md
index 4361863daeb..dd09a779318 100644
--- a/doc/development/agent/index.md
+++ b/doc/development/agent/index.md
@@ -72,6 +72,10 @@ graph TB
   - (Optional) Sending notifications through ActionCable for events received from `agentk`.
   - Polling manifest repositories for [GitOps support](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/gitops.md) by communicating with Gitaly.
 
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+To learn more about how the repository is structured, see
+[GitLab Kubernetes Agent repository overview](https://www.youtube.com/watch?v=j8CyaCWroUY).
+
 ## Guiding principles
 
 GitLab prefers to add logic into `kas` rather than `agentk`. `agentk` should be kept
diff --git a/doc/development/agent/local.md b/doc/development/agent/local.md
new file mode 100644
index 00000000000..2af53d0b3bd
--- /dev/null
+++ b/doc/development/agent/local.md
@@ -0,0 +1,58 @@
+---
+stage: Configure
+group: Configure
+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/#designated-technical-writers
+---
+
+# Run the Kubernetes Agent locally **(PREMIUM ONLY)**
+
+You can run `kas` and `agentk` locally to test the [Kubernetes Agent](index.md) yourself.
+
+1. Create a `cfg.yaml` file from the contents of
+   [`kas_config_example.yaml`](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/kas_config_example.yaml), or this example:
+
+   ```yaml
+   listen_agent:
+     network: tcp
+     address: 127.0.0.1:8150
+     websocket: false
+   gitlab:
+     address: http://localhost:3000
+     authentication_secret_file: /Users/tkuah/code/ee-gdk/gitlab/.gitlab_kas_secret
+   agent:
+     gitops:
+       poll_period: "10s"
+   ```
+
+1. Create a `token.txt`. This is the token for
+   [the agent you created](../../user/clusters/agent/index.md#create-an-agent-record-in-gitlab). This file must not contain a newline character. You can create the file with this command:
+
+   ```shell
+   echo -n "<TOKEN>" > token.txt
+   ```
+
+1. Start the binaries with the following commands:
+
+   ```shell
+   # Need GitLab to start
+   gdk start
+   # Stop GDK's version of kas
+   gdk stop gitlab-k8s-agent
+
+   # Start kas
+   bazel run //cmd/kas -- --configuration-file="$(pwd)/cfg.yaml"
+   ```
+
+1. In a new terminal window, run this command to start agentk:
+
+   ```shell
+   bazel run //cmd/agentk -- --kas-address=grpc://127.0.0.1:8150 --token-file="$(pwd)/token.txt"
+   ```
+
+You can also inspect the
+[Makefile](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/Makefile)
+for more targets.
+
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+To learn more about how the repository is structured, see
+[GitLab Kubernetes Agent repository overview](https://www.youtube.com/watch?v=j8CyaCWroUY).
diff --git a/doc/development/architecture.md b/doc/development/architecture.md
index 3e6cb6752f1..a056ab595f4 100644
--- a/doc/development/architecture.md
+++ b/doc/development/architecture.md
@@ -434,7 +434,7 @@ GitLab CI/CD is the open-source continuous integration service included with Git
 
 #### GitLab Shell
 
-- [Project page](https://gitlab.com/gitlab-org/gitlab-shell/blob/master/README.md)
+- [Project page](https://gitlab.com/gitlab-org/gitlab-shell/-/blob/main/README.md)
 - Configuration:
   - [Omnibus](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template)
   - [Charts](https://docs.gitlab.com/charts/charts/gitlab/gitlab-shell/)
diff --git a/doc/development/experiment_guide/index.md b/doc/development/experiment_guide/index.md
index d01aa1a46c3..bee6b4015f6 100644
--- a/doc/development/experiment_guide/index.md
+++ b/doc/development/experiment_guide/index.md
@@ -56,59 +56,90 @@ addressed.
 
 1. Use the experiment in the code.
 
+   Experiments can be performed on a `subject`. The `subject` that gets provided needs to respond to `to_global_id` or `to_s`.
+   The resulting string is bucketed and assigned to either the control or the experimental group. It's therefore necessary to always provide the same `subject` for an experiment to have the same experience.
+
    - Use this standard for the experiment in a controller:
 
-      ```ruby
-      class RegistrationController < ApplicationController
+     Experiment run for a user:
+
+     ```ruby
+     class ProjectController < ApplicationController
        def show
          # experiment_enabled?(:experiment_key) is also available in views and helpers
+         if experiment_enabled?(:signup_flow, subject: current_user)
+           # render the experiment
+         else
+           # render the original version
+         end
+       end
+     end
+     ```
+
+     or experiment run for a namespace:
+
+     ```ruby
+     if experiment_enabled?(:signup_flow, subject: namespace)
+       # experiment code
+     else
+       # control code
+     end
+     ```
+
+     When no subject is given, it falls back to a cookie that gets set and is consistent until
+     the cookie gets deleted.
+
+     ```ruby
+     class RegistrationController < ApplicationController
+       def show
+         # falls back to a cookie
          if experiment_enabled?(:signup_flow)
            # render the experiment
          else
            # render the original version
          end
        end
-      end
-      ```
+     end
+     ```
 
    - Make the experiment available to the frontend in a controller:
 
-      ```ruby
-      before_action do
-        push_frontend_experiment(:signup_flow)
-      end
-      ```
+     ```ruby
+     before_action do
+       push_frontend_experiment(:signup_flow, subject: current_user)
+     end
+     ```
 
-      The above checks whether the experiment is enabled and push the result to the frontend.
+     The above checks whether the experiment is enabled and pushes the result to the frontend.
 
-      You can check the state of the feature flag in JavaScript:
+     You can check the state of the feature flag in JavaScript:
 
-      ```javascript
-      import { isExperimentEnabled } from '~/experimentation';
+     ```javascript
+     import { isExperimentEnabled } from '~/experimentation';
 
-      if ( isExperimentEnabled('signupFlow') ) {
-        // ...
-      }
-      ```
+     if ( isExperimentEnabled('signupFlow') ) {
+       // ...
+     }
+     ```
 
    - It is also possible to run an experiment outside of the controller scope, for example in a worker:
 
-      ```ruby
-      class SomeWorker
-        def perform
-          # Check if the experiment is enabled at all (the percentage_of_time_value > 0)
-          return unless Gitlab::Experimentation.enabled?(:experiment_key)
-
-          # Since we cannot access cookies in a worker, we need to bucket models based on a unique, unchanging attribute instead.
-          # Use the following method to check if the experiment is enabled for a certain attribute, for example a username or email address:
-          if Gitlab::Experimentation.enabled_for_attribute?(:experiment_key, some_attribute)
-            # execute experimental code
-          else
-            # execute control code
-          end
-        end
-      end
-      ```
+     ```ruby
+     class SomeWorker
+       def perform
+         # Check if the experiment is active at all (the percentage_of_time_value > 0)
+         return unless Gitlab::Experimentation.active?(:experiment_key)
+
+         # Since we cannot access cookies in a worker, we need to bucket models based on a unique, unchanging attribute instead.
+         # It is therefore necessery to always provide the same subject.
+         if Gitlab::Experimentation.in_experiment_group?(:experiment_key, subject: user)
+           # execute experimental code
+         else
+           # execute control code
+         end
+       end
+     end
+     ```
 
 ### Implement the tracking events
 
@@ -122,7 +153,7 @@ The framework provides the following helper method that is available in controll
 
 ```ruby
 before_action do
-  track_experiment_event(:signup_flow, 'action', 'value')
+  track_experiment_event(:signup_flow, 'action', 'value', subject: current_user)
 end
 ```
 
@@ -132,7 +163,7 @@ Which can be tested as follows:
 context 'when the experiment is active and the user is in the experimental group' do
   before do
     stub_experiment(signup_flow: true)
-    stub_experiment_for_user(signup_flow: true)
+    stub_experiment_for_subject(signup_flow: true)
   end
 
   it 'tracks an event', :snowplow do
@@ -155,8 +186,8 @@ The framework provides the following helper method that is available in controll
 
 ```ruby
 before_action do
-  push_frontend_experiment(:signup_flow)
-  frontend_experimentation_tracking_data(:signup_flow, 'action', 'value')
+  push_frontend_experiment(:signup_flow, subject: current_user)
+  frontend_experimentation_tracking_data(:signup_flow, 'action', 'value', subject: current_user)
 end
 ```
 
@@ -255,7 +286,7 @@ Along with the tracking of backend and frontend events and the [recording of exp
 - **Experimental experience:** Show an in-product nudge to see if it causes more people to sign up for trials.
 - **Conversion event:** The user starts a trial.
 
-The `record_experiment_conversion_event` helper method is available to all controllers, and enables us to easily record the conversion event for the current user, regardless of whether they are in the control or experimental group:
+The `record_experiment_conversion_event` helper method is available to all controllers. It enables us to record the conversion event for the current user, regardless of whether they are in the control or experimental group:
 
 ```ruby
 before_action do
@@ -296,7 +327,7 @@ context 'when the experiment is active' do
 
   context 'when the user is in the experimental group' do
     before do
-      stub_experiment_for_user(signup_flow: true)
+      stub_experiment_for_subject(signup_flow: true)
     end
 
     it { is_expected.to do_experimental_thing }
@@ -304,7 +335,7 @@ context 'when the experiment is active' do
 
   context 'when the user is in the control group' do
     before do
-      stub_experiment_for_user(signup_flow: false)
+      stub_experiment_for_subject(signup_flow: false)
     end
 
     it { is_expected.to do_control_thing }
diff --git a/doc/development/feature_flags/development.md b/doc/development/feature_flags/development.md
index a84536eac61..c195173f450 100644
--- a/doc/development/feature_flags/development.md
+++ b/doc/development/feature_flags/development.md
@@ -503,10 +503,6 @@ is persisted.
 
 Make sure behavior under feature flag doesn't go untested in some non-specific contexts.
 
-See the
-[testing guide](../testing_guide/best_practices.md#feature-flags-in-tests)
-for information and examples on how to stub feature flags in tests.
-
 ### `stub_feature_flags: false`
 
 This disables a memory-stubbed flipper, and uses `Flipper::Adapters::ActiveRecord`
diff --git a/doc/development/testing_guide/end_to_end/beginners_guide.md b/doc/development/testing_guide/end_to_end/beginners_guide.md
index 0586f4708eb..a20eaff1f1c 100644
--- a/doc/development/testing_guide/end_to_end/beginners_guide.md
+++ b/doc/development/testing_guide/end_to_end/beginners_guide.md
@@ -349,3 +349,9 @@ Where `<test_file>` is:
 
 - `qa/specs/features/browser_ui/1_manage/login/login_spec.rb` when running the Login example.
 - `qa/specs/features/browser_ui/2_plan/issues/issue_spec.rb` when running the Issue example.
+
+## End-to-end test merge request template
+
+When submitting a new end-to-end test, use the ["New End to End Test"](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/merge_request_templates/New%20End%20To%20End%20Test.md)
+merge request description template for additional
+steps that are required prior a successful merge.
diff --git a/doc/development/what_requires_downtime.md b/doc/development/what_requires_downtime.md
index f486c6f0ec3..63a7ea4dfbd 100644
--- a/doc/development/what_requires_downtime.md
+++ b/doc/development/what_requires_downtime.md
@@ -51,7 +51,7 @@ We require indication of when it is safe to remove the column ignore with:
 - `remove_with`: set to a GitLab release typically two releases (M+2) after adding the
   column ignore.
 - `remove_after`: set to a date after which we consider it safe to remove the column
-  ignore, typically last date of the development cycle of release M+2 - namely the release date.
+  ignore, typically after the M+1 release date, during the M+2 development cycle.
 
 This information allows us to reason better about column ignores and makes sure we
 don't remove column ignores too early for both regular releases and deployments to GitLab.com. For
diff --git a/doc/user/application_security/vulnerabilities/index.md b/doc/user/application_security/vulnerabilities/index.md
index 848cb11a3c6..705964dba66 100644
--- a/doc/user/application_security/vulnerabilities/index.md
+++ b/doc/user/application_security/vulnerabilities/index.md
@@ -47,9 +47,9 @@ and allows you to comment on a change.
 
 You can create an issue for a vulnerability by selecting the **Create issue** button.
 
-This creates a [confidential issue](../../project/issues/confidential_issues.md) in the
-project the vulnerability came from and pre-populates it with useful information from
-the vulnerability report. After the issue is created, GitLab redirects you to the
+This allows the user to create a [confidential issue](../../project/issues/confidential_issues.md)
+in the project the vulnerability came from. Fields are pre-populated with pertinent information
+from the vulnerability report. After the issue is created, GitLab redirects you to the
 issue page so you can edit, assign, or comment on the issue.
 
 ## Link issues to the vulnerability
diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md
index b934d59e06f..31ff86adf38 100644
--- a/doc/user/group/saml_sso/index.md
+++ b/doc/user/group/saml_sso/index.md
@@ -240,6 +240,10 @@ Users can unlink SAML for a group from their profile page. This can be helpful i
 - You no longer want a group to be able to sign you in to GitLab.com.
 - Your SAML NameID has changed and so GitLab can no longer find your user.
 
+CAUTION: **Warning:**
+Unlinking an account removes all roles assigned to that user within the group. 
+If a user relinks their account, roles need to be reassigned.
+
 For example, to unlink the `MyOrg` account, the following **Disconnect** button is available under **Profile > Accounts**:
 
 ![Unlink Group SAML](img/unlink_group_saml.png)
@@ -280,10 +284,6 @@ the user gets the highest access level from the groups. For example, if one grou
 is linked as `Guest` and another `Maintainer`, a user in both groups gets `Maintainer` 
 access.
 
-CAUTION: **Warning:**
-Unlinking an account removes all roles assigned to that user within the group. 
-If a user relinks their account, roles need to be reassigned.
-
 ## Glossary
 
 | Term | Description |
diff --git a/doc/user/permissions.md b/doc/user/permissions.md
index 0cd1d3066fc..ca9b21370b0 100644
--- a/doc/user/permissions.md
+++ b/doc/user/permissions.md
@@ -159,6 +159,7 @@ The following table depicts the various user permission levels in a project.
 | Manage Terraform state                            |         |            |             | ✓        | ✓      |
 | Manage license policy **(ULTIMATE)**              |         |            |             | ✓        | ✓      |
 | Edit comments (posted by any user)                |         |            |             | ✓        | ✓      |
+| Reposition comments on images (posted by any user)|✓ (*11*) | ✓ (*11*)   |  ✓ (*11*)   | ✓        | ✓      |
 | Manage Error Tracking                             |         |            |             | ✓        | ✓      |
 | Delete wiki pages                                 |         |            |             | ✓        | ✓      |
 | View project Audit Events                         |         |            |             | ✓        | ✓      |
@@ -188,6 +189,7 @@ The following table depicts the various user permission levels in a project.
 1. For information on eligible approvers for merge requests, see
    [Eligible approvers](project/merge_requests/merge_request_approvals.md#eligible-approvers).
 1. Owner permission is only available at the group or personal namespace level (and for instance admins) and is inherited by its projects.
+1. Applies only to comments on [Design Management](project/issues/design_management.md) designs.
 
 ## Project features permissions
 
@@ -405,6 +407,11 @@ automatically have access to projects and subgroups underneath. To support such
 Users with minimal access can list the group in the UI and through the API. However, they cannot see
 details such as projects or subgroups. They do not have access to the group's page or list any of its subgroups or projects.
 
+### Minimal access users take license seats
+
+Users with even a "minimal access" role are counted against your number of license seats. This
+requirement does not apply for [GitLab Gold/Ultimate](https://about.gitlab.com/pricing/) subscriptions.
+
 ## Project features
 
 Project features like wiki and issues can be hidden from users depending on
diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md
index f4309bf5de0..7dc29013f2b 100644
--- a/doc/user/project/deploy_tokens/index.md
+++ b/doc/user/project/deploy_tokens/index.md
@@ -149,6 +149,9 @@ belong either to the specific group or to one of its subgroups.
 <i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
 For an overview, see [Group Deploy Tokens](https://youtu.be/8kxTJvaD9ks).
 
+The Group Deploy Tokens UI is now accessible under **Settings > Repository**,
+not **Settings > CI/CD** as indicated in the video.
+
 To use a group deploy token:
 
 1. [Create](#creating-a-deploy-token) a deploy token for a group.
diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md
index add446c5eec..35d32ebfa35 100644
--- a/doc/user/project/settings/index.md
+++ b/doc/user/project/settings/index.md
@@ -198,8 +198,8 @@ To rename a repository:
 
 1. Navigate to your project's **Settings > General**.
 1. Under **Advanced**, click **Expand**.
-1. Under "Rename repository", change the "Path" to your liking.
-1. Hit **Rename project**.
+1. Under **Change path**, update the repository's path.
+1. Click **Change path**.
 
 Remember that this can have unintended side effects since everyone with the
 old URL won't be able to push or pull. Read more about what happens with the