Add latest changes from gitlab-org/gitlab@master

12 files changed, 476 insertions, 478 deletions

diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md
index b5b06f56f35..fa2a92428a6 100644
--- a/doc/administration/geo/replication/troubleshooting.md
+++ b/doc/administration/geo/replication/troubleshooting.md
@@ -519,7 +519,7 @@ To solve this:
    curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/<first_failed_geo_sync_ID>"
    ```
 
-1. Enter the [Rails console](../../troubleshooting/navigating_gitlab_via_rails_console.md) and run:
+1. Enter the [Rails console](../../operations/rails_console.md) and run:
 
    ```ruby
    failed_geo_syncs = Geo::ProjectRegistry.failed.pluck(:id)
@@ -805,7 +805,7 @@ You can work around this by marking the objects as synced and succeeded verifica
 be aware that can also mark objects that may be
 [missing from the primary](#missing-files-on-the-geo-primary-site).
 
-To do that, enter the [Rails console](../../troubleshooting/navigating_gitlab_via_rails_console.md)
+To do that, enter the [Rails console](../../operations/rails_console.md)
 and run:
 
 ```ruby
diff --git a/doc/administration/index.md b/doc/administration/index.md
index 29fb65e2deb..6b2910a2d62 100644
--- a/doc/administration/index.md
+++ b/doc/administration/index.md
@@ -211,7 +211,7 @@ Learn how to install, configure, update, and maintain your GitLab instance.
 - [Log system](logs.md): Where to look for logs.
 - [Sidekiq Troubleshooting](troubleshooting/sidekiq.md): Debug when Sidekiq appears hung and is not processing jobs.
 - [Troubleshooting Elasticsearch](troubleshooting/elasticsearch.md)
-- [Navigating GitLab via Rails console](troubleshooting/navigating_gitlab_via_rails_console.md)
+- [Navigating GitLab via Rails console](operations/rails_console.md)
 - [GitLab application limits](instance_limits.md)
 - [Responding to security incidents](../security/responding_to_security_incidents.md)
 
diff --git a/doc/administration/operations/rails_console.md b/doc/administration/operations/rails_console.md
index df039ee734f..8778b2a8a36 100644
--- a/doc/administration/operations/rails_console.md
+++ b/doc/administration/operations/rails_console.md
@@ -6,8 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # Rails console **(FREE SELF)**
 
+At the heart of GitLab is a web application [built using the Ruby on Rails
+framework](https://about.gitlab.com/blog/2018/10/29/why-we-use-rails-to-build-gitlab/).
 The [Rails console](https://guides.rubyonrails.org/command_line.html#rails-console).
-provides a way to interact with your GitLab instance from the command line.
+provides a way to interact with your GitLab instance from the command line, and also grants access to the amazing tools built right into Rails.
 
 WARNING:
 The Rails console interacts directly with GitLab. In many cases,
@@ -17,7 +19,9 @@ with no consequences, you are strongly advised to do so in a test environment.
 
 The Rails console is for GitLab system administrators who are troubleshooting
 a problem or need to retrieve some data that can only be done through direct
-access of the GitLab application.
+access of the GitLab application. Basic knowledge of Ruby is needed (try [this
+30-minute tutorial](https://try.ruby-lang.org/) for a quick introduction).
+Rails experience is useful but not required.
 
 ## Starting a Rails console session
 
@@ -168,3 +172,435 @@ sudo chown -R git:git /scripts
 sudo chmod 700 /scripts
 sudo gitlab-rails runner /scripts/helloworld.rb
 ```
+
+## Active Record objects
+
+### Looking up database-persisted objects
+
+Under the hood, Rails uses [Active Record](https://guides.rubyonrails.org/active_record_basics.html),
+an object-relational mapping system, to read, write, and map application objects
+to the PostgreSQL database. These mappings are handled by Active Record models,
+which are Ruby classes defined in a Rails app. For GitLab, the model classes
+can be found at `/opt/gitlab/embedded/service/gitlab-rails/app/models`.
+
+Let's enable debug logging for Active Record so we can see the underlying
+database queries made:
+
+```ruby
+ActiveRecord::Base.logger = Logger.new($stdout)
+```
+
+Now, let's try retrieving a user from the database:
+
+```ruby
+user = User.find(1)
+```
+
+Which would return:
+
+```ruby
+D, [2020-03-05T16:46:25.571238 #910] DEBUG -- :   User Load (1.8ms)  SELECT "users".* FROM "users" WHERE "users"."id" = 1 LIMIT 1
+=> #<User id:1 @root>
+```
+
+We can see that we've queried the `users` table in the database for a row whose
+`id` column has the value `1`, and Active Record has translated that database
+record into a Ruby object that we can interact with. Try some of the following:
+
+- `user.username`
+- `user.created_at`
+- `user.admin`
+
+By convention, column names are directly translated into Ruby object attributes,
+so you should be able to do `user.<column_name>` to view the attribute's value.
+
+Also by convention, Active Record class names (singular and in camel case) map
+directly onto table names (plural and in snake case) and vice versa. For example,
+the `users` table maps to the `User` class, while the `application_settings`
+table maps to the `ApplicationSetting` class.
+
+You can find a list of tables and column names in the Rails database schema,
+available at `/opt/gitlab/embedded/service/gitlab-rails/db/schema.rb`.
+
+You can also look up an object from the database by attribute name:
+
+```ruby
+user = User.find_by(username: 'root')
+```
+
+Which would return:
+
+```ruby
+D, [2020-03-05T17:03:24.696493 #910] DEBUG -- :   User Load (2.1ms)  SELECT "users".* FROM "users" WHERE "users"."username" = 'root' LIMIT 1
+=> #<User id:1 @root>
+```
+
+Give the following a try:
+
+- `User.find_by(email: 'admin@example.com')`
+- `User.where.not(admin: true)`
+- `User.where('created_at < ?', 7.days.ago)`
+
+Did you notice that the last two commands returned an `ActiveRecord::Relation`
+object that appeared to contain multiple `User` objects?
+
+Up to now, we've been using `.find` or `.find_by`, which are designed to return
+only a single object (notice the `LIMIT 1` in the generated SQL query?).
+`.where` is used when it is desirable to get a collection of objects.
+
+Let's get a collection of non-administrator users and see what we can do with it:
+
+```ruby
+users = User.where.not(admin: true)
+```
+
+Which would return:
+
+```ruby
+D, [2020-03-05T17:11:16.845387 #910] DEBUG -- :   User Load (2.8ms)  SELECT "users".* FROM "users" WHERE "users"."admin" != TRUE LIMIT 11
+=> #<ActiveRecord::Relation [#<User id:3 @support-bot>, #<User id:7 @alert-bot>, #<User id:5 @carrie>, #<User id:4 @bernice>, #<User id:2 @anne>]>
+```
+
+Now, try the following:
+
+- `users.count`
+- `users.order(created_at: :desc)`
+- `users.where(username: 'support-bot')`
+
+In the last command, we see that we can chain `.where` statements to generate
+more complex queries. Notice also that while the collection returned contains
+only a single object, we cannot directly interact with it:
+
+```ruby
+users.where(username: 'support-bot').username
+```
+
+Which would return:
+
+```ruby
+Traceback (most recent call last):
+        1: from (irb):37
+D, [2020-03-05T17:18:25.637607 #910] DEBUG -- :   User Load (1.6ms)  SELECT "users".* FROM "users" WHERE "users"."admin" != TRUE AND "users"."username" = 'support-bot' LIMIT 11
+NoMethodError (undefined method `username' for #<ActiveRecord::Relation [#<User id:3 @support-bot>]>)
+Did you mean?  by_username
+```
+
+Let's retrieve the single object from the collection by using the `.first`
+method to get the first item in the collection:
+
+```ruby
+users.where(username: 'support-bot').first.username
+```
+
+We now get the result we wanted:
+
+```ruby
+D, [2020-03-05T17:18:30.406047 #910] DEBUG -- :   User Load (2.6ms)  SELECT "users".* FROM "users" WHERE "users"."admin" != TRUE AND "users"."username" = 'support-bot' ORDER BY "users"."id" ASC LIMIT 1
+=> "support-bot"
+```
+
+For more on different ways to retrieve data from the database using Active
+Record, please see the [Active Record Query Interface documentation](https://guides.rubyonrails.org/active_record_querying.html).
+
+### Modifying Active Record objects
+
+In the previous section, we learned about retrieving database records using
+Active Record. Now, let's learn how to write changes to the database.
+
+First, let's retrieve the `root` user:
+
+```ruby
+user = User.find_by(username: 'root')
+```
+
+Next, let's try updating the user's password:
+
+```ruby
+user.password = 'password'
+user.save
+```
+
+Which would return:
+
+```ruby
+Enqueued ActionMailer::MailDeliveryJob (Job ID: 05915c4e-c849-4e14-80bb-696d5ae22065) to Sidekiq(mailers) with arguments: "DeviseMailer", "password_change", "deliver_now", #<GlobalID:0x00007f42d8ccebe8 @uri=#<URI::GID gid://gitlab/User/1>>
+=> true
+```
+
+Here, we see that the `.save` command returned `true`, indicating that the
+password change was successfully saved to the database.
+
+We also see that the save operation triggered some other action -- in this case
+a background job to deliver an email notification. This is an example of an
+[Active Record callback](https://guides.rubyonrails.org/active_record_callbacks.html)
+-- code which is designated to run in response to events in the Active Record
+object life cycle. This is also why using the Rails console is preferred when
+direct changes to data is necessary as changes made via direct database queries
+do not trigger these callbacks.
+
+It's also possible to update attributes in a single line:
+
+```ruby
+user.update(password: 'password')
+```
+
+Or update multiple attributes at once:
+
+```ruby
+user.update(password: 'password', email: 'hunter2@example.com')
+```
+
+Now, let's try something different:
+
+```ruby
+# Retrieve the object again so we get its latest state
+user = User.find_by(username: 'root')
+user.password = 'password'
+user.password_confirmation = 'hunter2'
+user.save
+```
+
+This returns `false`, indicating that the changes we made were not saved to the
+database. You can probably guess why, but let's find out for sure:
+
+```ruby
+user.save!
+```
+
+This should return:
+
+```ruby
+Traceback (most recent call last):
+        1: from (irb):64
+ActiveRecord::RecordInvalid (Validation failed: Password confirmation doesn't match Password)
+```
+
+Aha! We've tripped an [Active Record Validation](https://guides.rubyonrails.org/active_record_validations.html).
+Validations are business logic put in place at the application-level to prevent
+unwanted data from being saved to the database and in most cases come with
+helpful messages letting you know how to fix the problem inputs.
+
+We can also add the bang (Ruby speak for `!`) to `.update`:
+
+```ruby
+user.update!(password: 'password', password_confirmation: 'hunter2')
+```
+
+In Ruby, method names ending with `!` are commonly known as "bang methods". By
+convention, the bang indicates that the method directly modifies the object it
+is acting on, as opposed to returning the transformed result and leaving the
+underlying object untouched. For Active Record methods that write to the
+database, bang methods also serve an additional function: they raise an
+explicit exception whenever an error occurs, instead of just returning `false`.
+
+We can also skip validations entirely:
+
+```ruby
+# Retrieve the object again so we get its latest state
+user = User.find_by(username: 'root')
+user.password = 'password'
+user.password_confirmation = 'hunter2'
+user.save!(validate: false)
+```
+
+This is not recommended, as validations are usually put in place to ensure the
+integrity and consistency of user-provided data.
+
+A validation error prevents the entire object from being saved to
+the database. You can see a little of this in the section below. If you're getting
+a mysterious red banner in the GitLab UI when submitting a form, this can often
+be the fastest way to get to the root of the problem.
+
+### Interacting with Active Record objects
+
+At the end of the day, Active Record objects are just normal Ruby objects. As
+such, we can define methods on them which perform arbitrary actions.
+
+For example, GitLab developers have added some methods which help with
+two-factor authentication:
+
+```ruby
+def disable_two_factor!
+  transaction do
+    update(
+      otp_required_for_login:      false,
+      encrypted_otp_secret:        nil,
+      encrypted_otp_secret_iv:     nil,
+      encrypted_otp_secret_salt:   nil,
+      otp_grace_period_started_at: nil,
+      otp_backup_codes:            nil
+    )
+    self.u2f_registrations.destroy_all # rubocop: disable DestroyAll
+  end
+end
+
+def two_factor_enabled?
+  two_factor_otp_enabled? || two_factor_u2f_enabled?
+end
+```
+
+(See: `/opt/gitlab/embedded/service/gitlab-rails/app/models/user.rb`)
+
+We can then use these methods on any user object:
+
+```ruby
+user = User.find_by(username: 'root')
+user.two_factor_enabled?
+user.disable_two_factor!
+```
+
+Some methods are defined by gems, or Ruby software packages, which GitLab uses.
+For example, the [StateMachines](https://github.com/state-machines/state_machines-activerecord)
+gem which GitLab uses to manage user state:
+
+```ruby
+state_machine :state, initial: :active do
+  event :block do
+
+  ...
+
+  event :activate do
+
+  ...
+
+end
+```
+
+Give it a try:
+
+```ruby
+user = User.find_by(username: 'root')
+user.state
+user.block
+user.state
+user.activate
+user.state
+```
+
+Earlier, we mentioned that a validation error prevents the entire object
+from being saved to the database. Let's see how this can have unexpected
+interactions:
+
+```ruby
+user.password = 'password'
+user.password_confirmation = 'hunter2'
+user.block
+```
+
+We get `false` returned! Let's find out what happened by adding a bang as we did
+earlier:
+
+```ruby
+user.block!
+```
+
+Which would return:
+
+```ruby
+Traceback (most recent call last):
+        1: from (irb):87
+StateMachines::InvalidTransition (Cannot transition state via :block from :active (Reason(s): Password confirmation doesn't match Password))
+```
+
+We see that a validation error from what feels like a completely separate
+attribute comes back to haunt us when we try to update the user in any way.
+
+In practical terms, we sometimes see this happen with GitLab administration settings --
+validations are sometimes added or changed in a GitLab update, resulting in
+previously saved settings now failing validation. Because you can only update
+a subset of settings at once through the UI, in this case the only way to get
+back to a good state is direct manipulation via Rails console.
+
+### Commonly used Active Record models and how to look up objects
+
+**Get a user by primary email address or username:**
+
+```ruby
+User.find_by(email: 'admin@example.com')
+User.find_by(username: 'root')
+```
+
+**Get a user by primary OR secondary email address:**
+
+```ruby
+User.find_by_any_email('user@example.com')
+```
+
+The `find_by_any_email` method is a custom method added by GitLab developers rather
+than a Rails-provided default method.
+
+**Get a collection of administrator users:**
+
+```ruby
+User.admins
+```
+
+`admins` is a [scope convenience method](https://guides.rubyonrails.org/active_record_querying.html#scopes)
+which does `where(admin: true)` under the hood.
+
+**Get a project by its path:**
+
+```ruby
+Project.find_by_full_path('group/subgroup/project')
+```
+
+`find_by_full_path` is a custom method added by GitLab developers rather
+than a Rails-provided default method.
+
+**Get a project's issue or merge request by its numeric ID:**
+
+```ruby
+project = Project.find_by_full_path('group/subgroup/project')
+project.issues.find_by(iid: 42)
+project.merge_requests.find_by(iid: 42)
+```
+
+`iid` means "internal ID" and is how we keep issue and merge request IDs
+scoped to each GitLab project.
+
+**Get a group by its path:**
+
+```ruby
+Group.find_by_full_path('group/subgroup')
+```
+
+**Get a group's related groups:**
+
+```ruby
+group = Group.find_by_full_path('group/subgroup')
+
+# Get a group's parent group
+group.parent
+
+# Get a group's child groups
+group.children
+```
+
+**Get a group's projects:**
+
+```ruby
+group = Group.find_by_full_path('group/subgroup')
+
+# Get group's immediate child projects
+group.projects
+
+# Get group's child projects, including those in subgroups
+group.all_projects
+```
+
+**Get CI pipeline or builds:**
+
+```ruby
+Ci::Pipeline.find(4151)
+Ci::Build.find(66124)
+```
+
+The pipeline and job ID numbers increment globally across your GitLab
+instance, so there's no requirement to use an internal ID attribute to look them up,
+unlike with issues or merge requests.
+
+**Get the current application settings object:**
+
+```ruby
+ApplicationSetting.current
+```
diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md
index d6cadbab6a6..a6c97bbe3f5 100644
--- a/doc/administration/packages/container_registry.md
+++ b/doc/administration/packages/container_registry.md
@@ -887,7 +887,7 @@ administrators can clean up image tags
 and [run garbage collection](#container-registry-garbage-collection).
 
 To remove image tags by running the cleanup policy, run the following commands in the
-[GitLab Rails console](../troubleshooting/navigating_gitlab_via_rails_console.md):
+[GitLab Rails console](../operations/rails_console.md):
 
 ```ruby
 # Numeric ID of the project whose container registry should be cleaned up
@@ -1738,7 +1738,7 @@ In this case, follow these steps:
 1. Try the removal again.
 
 If you still can't remove the repository using the common methods, you can use the
-[GitLab Rails console](../troubleshooting/navigating_gitlab_via_rails_console.md)
+[GitLab Rails console](../operations/rails_console.md)
 to remove the project by force:
 
 ```ruby
diff --git a/doc/administration/troubleshooting/debug.md b/doc/administration/troubleshooting/debug.md
index 81ca1bda5d0..b88a96a560d 100644
--- a/doc/administration/troubleshooting/debug.md
+++ b/doc/administration/troubleshooting/debug.md
@@ -18,7 +18,6 @@ Your type of GitLab installation determines how
 See also:
 
 - [GitLab Rails Console Cheat Sheet](gitlab_rails_cheat_sheet.md).
-- [Navigating GitLab via Rails console](navigating_gitlab_via_rails_console.md).
 
 ### Enabling Active Record logging
 
diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md
index aec81514a0e..8d86d987f12 100644
--- a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md
+++ b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md
@@ -10,7 +10,7 @@ This is the GitLab Support Team's collection of information regarding the GitLab
 console, for use while troubleshooting. It is listed here for transparency,
 and it may be useful for users with experience with these tools. If you are currently
 having an issue with GitLab, it is highly recommended that you first check
-our guide on [navigating our Rails console](navigating_gitlab_via_rails_console.md),
+our guide on [our Rails console](../operations/rails_console.md),
 and your [support options](https://about.gitlab.com/support/), before attempting to use
 this information.
 
@@ -517,7 +517,7 @@ If this all runs successfully, you see an output like the following before being
 
 The exported project is located within a `.tar.gz` file in `/var/opt/gitlab/gitlab-rails/uploads/-/system/import_export_upload/export_file/`.
 
-If this fails, [enable verbose logging](navigating_gitlab_via_rails_console.md#looking-up-database-persisted-objects),
+If this fails, [enable verbose logging](../operations/rails_console.md#looking-up-database-persisted-objects),
 repeat the above procedure after,
 and report the output to
 [GitLab Support](https://about.gitlab.com/support/).
@@ -1114,7 +1114,7 @@ License.select(&TYPE).each(&:destroy!)
 As a GitLab administrator, you may need to reduce disk space consumption.
 A common culprit is Docker Registry images that are no longer in use. To find
 the storage broken down by each project, run the following in the
-[GitLab Rails console](../troubleshooting/navigating_gitlab_via_rails_console.md):
+[GitLab Rails console](../operations/rails_console.md):
 
 ```ruby
 projects_and_size = [["project_id", "creator_id", "registry_size_bytes", "project path"]]
diff --git a/doc/administration/troubleshooting/index.md b/doc/administration/troubleshooting/index.md
index 7d40a9e9683..12f86cfa78c 100644
--- a/doc/administration/troubleshooting/index.md
+++ b/doc/administration/troubleshooting/index.md
@@ -20,7 +20,6 @@ installation.
 - [Kubernetes cheat sheet](kubernetes_cheat_sheet.md)
 - [Linux cheat sheet](linux_cheat_sheet.md)
 - [Parsing GitLab logs with `jq`](log_parsing.md)
-- [Navigating GitLab via Rails console](navigating_gitlab_via_rails_console.md)
 - [Diagnostics tools](diagnostics_tools.md)
 - [Debugging tips](debug.md)
 - [Tracing requests with correlation ID](tracing_correlation_id.md)
diff --git a/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md b/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md
index 51ef3d95a4e..09a5cb8d185 100644
--- a/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md
+++ b/doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md
@@ -1,465 +1,11 @@
 ---
-stage: Systems
-group: Distribution
-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
+redirect_to: '../operations/rails_console.md'
+remove_date: '2022-10-05'
 ---
 
-# Navigating GitLab via Rails console **(FREE SELF)**
+This document was moved to [another location](../operations/rails_console.md).
 
-At the heart of GitLab is a web application [built using the Ruby on Rails
-framework](https://about.gitlab.com/blog/2018/10/29/why-we-use-rails-to-build-gitlab/).
-Thanks to this, we also get access to the amazing tools built right into Rails.
-This guide introduces the [Rails console](../operations/rails_console.md#starting-a-rails-console-session)
-and the basics of interacting with your GitLab instance from the command line.
-
-WARNING:
-The Rails console interacts directly with your GitLab instance. In many cases,
-there are no handrails to prevent you from permanently modifying, corrupting
-or destroying production data. If you would like to explore the Rails console
-with no consequences, you are strongly advised to do so in a test environment.
-
-This guide is targeted at GitLab system administrators who are troubleshooting
-a problem or must retrieve some data that can only be done through direct
-access of the GitLab application. Basic knowledge of Ruby is needed (try [this
-30-minute tutorial](https://try.ruby-lang.org/) for a quick introduction).
-Rails experience is helpful to have but not a must.
-
-## Starting a Rails console session
-
-Your type of GitLab installation determines how
-[to start a rails console](../operations/rails_console.md).
-
-The following code examples take place inside the Rails console and also
-assume an Omnibus GitLab installation.
-
-## Active Record objects
-
-### Looking up database-persisted objects
-
-Under the hood, Rails uses [Active Record](https://guides.rubyonrails.org/active_record_basics.html),
-an object-relational mapping system, to read, write, and map application objects
-to the PostgreSQL database. These mappings are handled by Active Record models,
-which are Ruby classes defined in a Rails app. For GitLab, the model classes
-can be found at `/opt/gitlab/embedded/service/gitlab-rails/app/models`.
-
-Let's enable debug logging for Active Record so we can see the underlying
-database queries made:
-
-```ruby
-ActiveRecord::Base.logger = Logger.new($stdout)
-```
-
-Now, let's try retrieving a user from the database:
-
-```ruby
-user = User.find(1)
-```
-
-Which would return:
-
-```ruby
-D, [2020-03-05T16:46:25.571238 #910] DEBUG -- :   User Load (1.8ms)  SELECT "users".* FROM "users" WHERE "users"."id" = 1 LIMIT 1
-=> #<User id:1 @root>
-```
-
-We can see that we've queried the `users` table in the database for a row whose
-`id` column has the value `1`, and Active Record has translated that database
-record into a Ruby object that we can interact with. Try some of the following:
-
-- `user.username`
-- `user.created_at`
-- `user.admin`
-
-By convention, column names are directly translated into Ruby object attributes,
-so you should be able to do `user.<column_name>` to view the attribute's value.
-
-Also by convention, Active Record class names (singular and in camel case) map
-directly onto table names (plural and in snake case) and vice versa. For example,
-the `users` table maps to the `User` class, while the `application_settings`
-table maps to the `ApplicationSetting` class.
-
-You can find a list of tables and column names in the Rails database schema,
-available at `/opt/gitlab/embedded/service/gitlab-rails/db/schema.rb`.
-
-You can also look up an object from the database by attribute name:
-
-```ruby
-user = User.find_by(username: 'root')
-```
-
-Which would return:
-
-```ruby
-D, [2020-03-05T17:03:24.696493 #910] DEBUG -- :   User Load (2.1ms)  SELECT "users".* FROM "users" WHERE "users"."username" = 'root' LIMIT 1
-=> #<User id:1 @root>
-```
-
-Give the following a try:
-
-- `User.find_by(email: 'admin@example.com')`
-- `User.where.not(admin: true)`
-- `User.where('created_at < ?', 7.days.ago)`
-
-Did you notice that the last two commands returned an `ActiveRecord::Relation`
-object that appeared to contain multiple `User` objects?
-
-Up to now, we've been using `.find` or `.find_by`, which are designed to return
-only a single object (notice the `LIMIT 1` in the generated SQL query?).
-`.where` is used when it is desirable to get a collection of objects.
-
-Let's get a collection of non-administrator users and see what we can do with it:
-
-```ruby
-users = User.where.not(admin: true)
-```
-
-Which would return:
-
-```ruby
-D, [2020-03-05T17:11:16.845387 #910] DEBUG -- :   User Load (2.8ms)  SELECT "users".* FROM "users" WHERE "users"."admin" != TRUE LIMIT 11
-=> #<ActiveRecord::Relation [#<User id:3 @support-bot>, #<User id:7 @alert-bot>, #<User id:5 @carrie>, #<User id:4 @bernice>, #<User id:2 @anne>]>
-```
-
-Now, try the following:
-
-- `users.count`
-- `users.order(created_at: :desc)`
-- `users.where(username: 'support-bot')`
-
-In the last command, we see that we can chain `.where` statements to generate
-more complex queries. Notice also that while the collection returned contains
-only a single object, we cannot directly interact with it:
-
-```ruby
-users.where(username: 'support-bot').username
-```
-
-Which would return:
-
-```ruby
-Traceback (most recent call last):
-        1: from (irb):37
-D, [2020-03-05T17:18:25.637607 #910] DEBUG -- :   User Load (1.6ms)  SELECT "users".* FROM "users" WHERE "users"."admin" != TRUE AND "users"."username" = 'support-bot' LIMIT 11
-NoMethodError (undefined method `username' for #<ActiveRecord::Relation [#<User id:3 @support-bot>]>)
-Did you mean?  by_username
-```
-
-Let's retrieve the single object from the collection by using the `.first`
-method to get the first item in the collection:
-
-```ruby
-users.where(username: 'support-bot').first.username
-```
-
-We now get the result we wanted:
-
-```ruby
-D, [2020-03-05T17:18:30.406047 #910] DEBUG -- :   User Load (2.6ms)  SELECT "users".* FROM "users" WHERE "users"."admin" != TRUE AND "users"."username" = 'support-bot' ORDER BY "users"."id" ASC LIMIT 1
-=> "support-bot"
-```
-
-For more on different ways to retrieve data from the database using Active
-Record, please see the [Active Record Query Interface documentation](https://guides.rubyonrails.org/active_record_querying.html).
-
-### Modifying Active Record objects
-
-In the previous section, we learned about retrieving database records using
-Active Record. Now, let's learn how to write changes to the database.
-
-First, let's retrieve the `root` user:
-
-```ruby
-user = User.find_by(username: 'root')
-```
-
-Next, let's try updating the user's password:
-
-```ruby
-user.password = 'password'
-user.save
-```
-
-Which would return:
-
-```ruby
-Enqueued ActionMailer::MailDeliveryJob (Job ID: 05915c4e-c849-4e14-80bb-696d5ae22065) to Sidekiq(mailers) with arguments: "DeviseMailer", "password_change", "deliver_now", #<GlobalID:0x00007f42d8ccebe8 @uri=#<URI::GID gid://gitlab/User/1>>
-=> true
-```
-
-Here, we see that the `.save` command returned `true`, indicating that the
-password change was successfully saved to the database.
-
-We also see that the save operation triggered some other action -- in this case
-a background job to deliver an email notification. This is an example of an
-[Active Record callback](https://guides.rubyonrails.org/active_record_callbacks.html)
--- code which is designated to run in response to events in the Active Record
-object life cycle. This is also why using the Rails console is preferred when
-direct changes to data is necessary as changes made via direct database queries
-do not trigger these callbacks.
-
-It's also possible to update attributes in a single line:
-
-```ruby
-user.update(password: 'password')
-```
-
-Or update multiple attributes at once:
-
-```ruby
-user.update(password: 'password', email: 'hunter2@example.com')
-```
-
-Now, let's try something different:
-
-```ruby
-# Retrieve the object again so we get its latest state
-user = User.find_by(username: 'root')
-user.password = 'password'
-user.password_confirmation = 'hunter2'
-user.save
-```
-
-This returns `false`, indicating that the changes we made were not saved to the
-database. You can probably guess why, but let's find out for sure:
-
-```ruby
-user.save!
-```
-
-This should return:
-
-```ruby
-Traceback (most recent call last):
-        1: from (irb):64
-ActiveRecord::RecordInvalid (Validation failed: Password confirmation doesn't match Password)
-```
-
-Aha! We've tripped an [Active Record Validation](https://guides.rubyonrails.org/active_record_validations.html).
-Validations are business logic put in place at the application-level to prevent
-unwanted data from being saved to the database and in most cases come with
-helpful messages letting you know how to fix the problem inputs.
-
-We can also add the bang (Ruby speak for `!`) to `.update`:
-
-```ruby
-user.update!(password: 'password', password_confirmation: 'hunter2')
-```
-
-In Ruby, method names ending with `!` are commonly known as "bang methods". By
-convention, the bang indicates that the method directly modifies the object it
-is acting on, as opposed to returning the transformed result and leaving the
-underlying object untouched. For Active Record methods that write to the
-database, bang methods also serve an additional function: they raise an
-explicit exception whenever an error occurs, instead of just returning `false`.
-
-We can also skip validations entirely:
-
-```ruby
-# Retrieve the object again so we get its latest state
-user = User.find_by(username: 'root')
-user.password = 'password'
-user.password_confirmation = 'hunter2'
-user.save!(validate: false)
-```
-
-This is not recommended, as validations are usually put in place to ensure the
-integrity and consistency of user-provided data.
-
-A validation error prevents the entire object from being saved to
-the database. You can see a little of this in the section below. If you're getting
-a mysterious red banner in the GitLab UI when submitting a form, this can often
-be the fastest way to get to the root of the problem.
-
-### Interacting with Active Record objects
-
-At the end of the day, Active Record objects are just normal Ruby objects. As
-such, we can define methods on them which perform arbitrary actions.
-
-For example, GitLab developers have added some methods which help with
-two-factor authentication:
-
-```ruby
-def disable_two_factor!
-  transaction do
-    update(
-      otp_required_for_login:      false,
-      encrypted_otp_secret:        nil,
-      encrypted_otp_secret_iv:     nil,
-      encrypted_otp_secret_salt:   nil,
-      otp_grace_period_started_at: nil,
-      otp_backup_codes:            nil
-    )
-    self.u2f_registrations.destroy_all # rubocop: disable DestroyAll
-  end
-end
-
-def two_factor_enabled?
-  two_factor_otp_enabled? || two_factor_u2f_enabled?
-end
-```
-
-(See: `/opt/gitlab/embedded/service/gitlab-rails/app/models/user.rb`)
-
-We can then use these methods on any user object:
-
-```ruby
-user = User.find_by(username: 'root')
-user.two_factor_enabled?
-user.disable_two_factor!
-```
-
-Some methods are defined by gems, or Ruby software packages, which GitLab uses.
-For example, the [StateMachines](https://github.com/state-machines/state_machines-activerecord)
-gem which GitLab uses to manage user state:
-
-```ruby
-state_machine :state, initial: :active do
-  event :block do
-
-  ...
-
-  event :activate do
-
-  ...
-
-end
-```
-
-Give it a try:
-
-```ruby
-user = User.find_by(username: 'root')
-user.state
-user.block
-user.state
-user.activate
-user.state
-```
-
-Earlier, we mentioned that a validation error prevents the entire object
-from being saved to the database. Let's see how this can have unexpected
-interactions:
-
-```ruby
-user.password = 'password'
-user.password_confirmation = 'hunter2'
-user.block
-```
-
-We get `false` returned! Let's find out what happened by adding a bang as we did
-earlier:
-
-```ruby
-user.block!
-```
-
-Which would return:
-
-```ruby
-Traceback (most recent call last):
-        1: from (irb):87
-StateMachines::InvalidTransition (Cannot transition state via :block from :active (Reason(s): Password confirmation doesn't match Password))
-```
-
-We see that a validation error from what feels like a completely separate
-attribute comes back to haunt us when we try to update the user in any way.
-
-In practical terms, we sometimes see this happen with GitLab administration settings --
-validations are sometimes added or changed in a GitLab update, resulting in
-previously saved settings now failing validation. Because you can only update
-a subset of settings at once through the UI, in this case the only way to get
-back to a good state is direct manipulation via Rails console.
-
-### Commonly used Active Record models and how to look up objects
-
-**Get a user by primary email address or username:**
-
-```ruby
-User.find_by(email: 'admin@example.com')
-User.find_by(username: 'root')
-```
-
-**Get a user by primary OR secondary email address:**
-
-```ruby
-User.find_by_any_email('user@example.com')
-```
-
-The `find_by_any_email` method is a custom method added by GitLab developers rather
-than a Rails-provided default method.
-
-**Get a collection of administrator users:**
-
-```ruby
-User.admins
-```
-
-`admins` is a [scope convenience method](https://guides.rubyonrails.org/active_record_querying.html#scopes)
-which does `where(admin: true)` under the hood.
-
-**Get a project by its path:**
-
-```ruby
-Project.find_by_full_path('group/subgroup/project')
-```
-
-`find_by_full_path` is a custom method added by GitLab developers rather
-than a Rails-provided default method.
-
-**Get a project's issue or merge request by its numeric ID:**
-
-```ruby
-project = Project.find_by_full_path('group/subgroup/project')
-project.issues.find_by(iid: 42)
-project.merge_requests.find_by(iid: 42)
-```
-
-`iid` means "internal ID" and is how we keep issue and merge request IDs
-scoped to each GitLab project.
-
-**Get a group by its path:**
-
-```ruby
-Group.find_by_full_path('group/subgroup')
-```
-
-**Get a group's related groups:**
-
-```ruby
-group = Group.find_by_full_path('group/subgroup')
-
-# Get a group's parent group
-group.parent
-
-# Get a group's child groups
-group.children
-```
-
-**Get a group's projects:**
-
-```ruby
-group = Group.find_by_full_path('group/subgroup')
-
-# Get group's immediate child projects
-group.projects
-
-# Get group's child projects, including those in subgroups
-group.all_projects
-```
-
-**Get CI pipeline or builds:**
-
-```ruby
-Ci::Pipeline.find(4151)
-Ci::Build.find(66124)
-```
-
-The pipeline and job ID numbers increment globally across your GitLab
-instance, so there's no requirement to use an internal ID attribute to look them up,
-unlike with issues or merge requests.
-
-**Get the current application settings object:**
-
-```ruby
-ApplicationSetting.current
-```
+<!-- This redirect file can be deleted after <2022-10-05>. -->
+<!-- Redirects that point to other docs in the same project expire in three months. -->
+<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. -->
+<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html -->
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index a9edc301bc4..c6714459643 100644
--- a/doc/api/merge_requests.md
+++ b/doc/api/merge_requests.md
@@ -450,6 +450,7 @@ Parameters:
 | `assignee_id`                   | integer        | no       | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. |
 | `approver_ids` **(PREMIUM)**    | integer array  | no       | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. |
 | `approved_by_ids` **(PREMIUM)** | integer array  | no       | Returns merge requests which have been approved by all the users with the given `id`s (Max: 5). `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. |
+| `approved_by_usernames` **(PREMIUM)** | string array  | no       | Returns merge requests which have been approved by all the users with the given `username`s (Max: 5). `None` returns merge requests with no approvals. `Any` returns merge requests with an approval. |
 | `reviewer_id`                   | integer        | no       | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given user `id`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_username`.  |
 | `reviewer_username`             | string         | no       | Returns merge requests which have the user as a [reviewer](../user/project/merge_requests/getting_started.md#reviewer) with the given `username`. `None` returns merge requests with no reviewers. `Any` returns merge requests with any reviewer. Mutually exclusive with `reviewer_id`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49341) in GitLab 13.8. |
 | `my_reaction_emoji`             | string         | no       | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. |
diff --git a/doc/ci/testing/unit_test_reports.md b/doc/ci/testing/unit_test_reports.md
index 8aa41cd6fc0..1328a8a0d0f 100644
--- a/doc/ci/testing/unit_test_reports.md
+++ b/doc/ci/testing/unit_test_reports.md
@@ -163,3 +163,14 @@ report format XML files contain an `attachment` tag, GitLab parses the attachmen
 
 A link to the test case attachment appears in the test case details in
 [the pipeline test report](#view-unit-test-reports-on-gitlab).
+
+## Troubleshooting
+
+### Test report appears empty
+
+A unit test report can appear to be empty when [viewed in a merge request](#view-unit-test-reports-on-gitlab)
+if the artifact that contained the report [expires](../yaml/index.md#artifactsexpire_in).
+If the artifact frequently expires too early, set a longer `expire_in` value for
+the report artifact.
+
+Alternatively, you can run a new pipeline to generate a new report.
diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md
index 182d00d52ab..12fd7c3dc12 100644
--- a/doc/development/contributing/index.md
+++ b/doc/development/contributing/index.md
@@ -240,4 +240,4 @@ For information on how to contribute documentation, see GitLab
 ## Getting an Enterprise Edition License
 
 If you need a license for contributing to an EE-feature, see
-[relevant information](https://about.gitlab.com/handbook/marketing/community-relations/code-contributor-program/#for-contributors-to-the-gitlab-enterprise-edition-ee).
+[relevant information](https://about.gitlab.com/handbook/marketing/community-relations/code-contributor-program/#contributing-to-the-gitlab-enterprise-edition-ee).
diff --git a/doc/development/snowplow/implementation.md b/doc/development/snowplow/implementation.md
index ff12b82bbdb..f8e37aee1e0 100644
--- a/doc/development/snowplow/implementation.md
+++ b/doc/development/snowplow/implementation.md
@@ -505,16 +505,22 @@ To install and run Snowplow Micro, complete these steps to modify the
 
 1. Set the environment variable to tell the GDK to use Snowplow Micro in development. This overrides two `application_settings` options:
    - `snowplow_enabled` setting will instead return `true` from `Gitlab::Tracking.enabled?`
-   - `snowplow_collector_hostname` setting will instead always return `localhost:9090` (or whatever is set for `SNOWPLOW_MICRO_URI`) from `Gitlab::Tracking.collector_hostname`.
+   - `snowplow_collector_hostname` setting will instead always return `localhost:9090` (or whatever port is set for `snowplow_micro.port` GDK setting) from `Gitlab::Tracking.collector_hostname`.
 
    ```shell
-   export SNOWPLOW_MICRO_ENABLE=1
+   gdk config set snowplow_micro.enabled true
    ```
 
-   Optionally, you can set the URI for you Snowplow Micro instance as well (the default value is `http://localhost:9090`):
+   Optionally, you can set the port for you Snowplow Micro instance as well (the default value is `9090`):
 
    ```shell
-   export SNOWPLOW_MICRO_URI=https://127.0.0.1:8080
+   gdk config set snowplow_micro.port 8080
+   ```
+
+1. Regenerate the project YAML config:
+
+   ```shell
+   gdk reconfigure
    ```
 
 1. Restart GDK: