diff --git a/doc/administration/geo/disaster_recovery/index.md b/doc/administration/geo/disaster_recovery/index.md
index 78e6bbd6c067b24bef2a47295643c8c194722837..186a76518c4b581137e9d08cd65b1495d97871dd 100644
--- a/doc/administration/geo/disaster_recovery/index.md
+++ b/doc/administration/geo/disaster_recovery/index.md
@@ -79,11 +79,7 @@ This issue has been fixed in GitLab 13.4 and later.
 
 Note the following when promoting a secondary:
 
-- If replication was paused on the secondary site (for example as a part of
-  upgrading, while you were running a version of GitLab earlier than 13.4), you
-  _must_ [enable the site by using the database](../replication/troubleshooting.md#message-activerecordrecordinvalid-validation-failed-enabled-geo-primary-node-cannot-be-disabled)
-  before proceeding. If the secondary site
-  [has been paused](../../geo/index.md#pausing-and-resuming-replication), the promotion
+- If the secondary site [has been paused](../../geo/index.md#pausing-and-resuming-replication), the promotion
   performs a point-in-time recovery to the last known state.
   Data that was created on the primary while the secondary was paused is lost.
 - A new **secondary** should not be added at this time. If you want to add a new
@@ -92,9 +88,6 @@ Note the following when promoting a secondary:
 - If you encounter an `ActiveRecord::RecordInvalid: Validation failed: Name has already been taken`
   error message during this process, for more information, see this
   [troubleshooting advice](../replication/troubleshooting.md#fixing-errors-during-a-failover-or-when-promoting-a-secondary-to-a-primary-site).
-- If you run into errors when using `--force` or `--skip-preflight-checks` before 13.5 during this process,
-  for more information, see this
-  [troubleshooting advice](../replication/troubleshooting.md#errors-when-using---skip-preflight-checks-or---force).
 
 #### Promoting a **secondary** site running on a single node running GitLab 14.5 and later
 
@@ -225,8 +218,6 @@ do this manually.
    sudo gitlab-ctl promote-db
    ```
 
-   In GitLab 12.8 and earlier, see [Message: `sudo: gitlab-pg-ctl: command not found`](../replication/troubleshooting.md#message-sudo-gitlab-pg-ctl-command-not-found).
-
 1. Edit `/etc/gitlab/gitlab.rb` on every node in the **secondary** site to
    reflect its new status as **primary** by removing any of the following
    lines that might be present:
diff --git a/doc/administration/geo/disaster_recovery/planned_failover.md b/doc/administration/geo/disaster_recovery/planned_failover.md
index ff6b2400267aa5d8fb37223505f1680e10b9f5ae..7879e8e364c7a88a8621a6e81c0107717333df6b 100644
--- a/doc/administration/geo/disaster_recovery/planned_failover.md
+++ b/doc/administration/geo/disaster_recovery/planned_failover.md
@@ -208,9 +208,6 @@ be disabled on the **primary** site:
 
 ## Finish replicating and verifying all data
 
-NOTE:
-GitLab 13.9 through GitLab 14.3 are affected by a bug in which the Geo secondary site statuses appears to stop updating and become unhealthy. For more information, see [Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode](../replication/troubleshooting.md#geo-admin-area-shows-unhealthy-after-enabling-maintenance-mode).
-
 1. If you are manually replicating any data not managed by Geo, trigger the
    final replication process now.
 1. On the **primary** site:
diff --git a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md
index a96963cfea1ef6cdefdecbf915db5cbca45089d2..ac8592fd73c934847a5ce705980920ebc679856d 100644
--- a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md
+++ b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_multi_node.md
@@ -63,9 +63,6 @@ Before following any of those steps, make sure you have `root` access to the
 **secondary** to promote it, because there isn't provided an automated way to
 promote a Geo replica and perform a failover.
 
-NOTE:
-GitLab 13.9 through GitLab 14.3 are affected by a bug in which the Geo secondary site statuses appear to stop updating and become unhealthy. For more information, see [Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode](../../replication/troubleshooting.md#geo-admin-area-shows-unhealthy-after-enabling-maintenance-mode).
-
 On the **secondary** site:
 
 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**).
@@ -257,8 +254,6 @@ Data that was created on the primary while the secondary was paused is lost.
    sudo gitlab-ctl promote-db
    ```
 
-   In GitLab 12.8 and earlier, see [Message: `sudo: gitlab-pg-ctl: command not found`](../../replication/troubleshooting.md#message-sudo-gitlab-pg-ctl-command-not-found).
-
 1. Edit `/etc/gitlab/gitlab.rb` on every machine in the **secondary** to
    reflect its new status as **primary** by removing any lines that enabled the
    `geo_secondary_role`:
diff --git a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md
index 7f94d6e4c1a8d5a1d2d575ef28c4c8fb26030304..40937aa038ec562bc56ed83a0f9ff5faac4def2f 100644
--- a/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md
+++ b/doc/administration/geo/disaster_recovery/runbooks/planned_failover_single_node.md
@@ -51,9 +51,6 @@ Before following any of those steps, make sure you have `root` access to the
 **secondary** to promote it, since there isn't provided an automated way to
 promote a Geo replica and perform a failover.
 
-NOTE:
-GitLab 13.9 through GitLab 14.3 are affected by a bug in which the Geo secondary site statuses appears to stop updating and become unhealthy. For more information, see [Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode](../../replication/troubleshooting.md#geo-admin-area-shows-unhealthy-after-enabling-maintenance-mode).
-
 On the **secondary** site, navigate to the **Admin Area > Geo** dashboard to
 review its status. Replicated objects (shown in green) should be close to 100%,
 and there should be no failures (shown in red). If a large proportion of
diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md
index edca747039603ecd7d9aba165315e385505e0ce6..94ee76fa3cd49d672171440fc9fd5a4dce0d9a7b 100644
--- a/doc/administration/geo/replication/troubleshooting.md
+++ b/doc/administration/geo/replication/troubleshooting.md
@@ -20,10 +20,10 @@ Here is a list of steps you should take to attempt to fix problem:
 
 Before attempting more advanced troubleshooting:
 
-- Check [the health of the **secondary** site](#check-the-health-of-the-secondary-site).
+- Check [the health of the Geo sites](#check-the-health-of-the-geo-sites).
 - Check [if PostgreSQL replication is working](#check-if-postgresql-replication-is-working).
 
-### Check the health of the **secondary** site
+### Check the health of the Geo sites
 
 On the **primary** site:
 
@@ -220,119 +220,7 @@ If you notice replication or verification failures, you can try to [resolve them
 
 If there are Repository check failures, you can try to [resolve them](#find-repository-check-failures-in-a-geo-secondary-site).
 
-### Check if PostgreSQL replication is working
-
-To check if PostgreSQL replication is working, check if:
-
-- [Sites are pointing to the correct database node](#are-sites-pointing-to-the-correct-database-node).
-- [Geo can detect the current site correctly](#can-geo-detect-the-current-site-correctly).
-
-#### Are sites pointing to the correct database node?
-
-You should make sure your **primary** Geo [site](../glossary.md) points to
-the database node that has write permissions.
-
-Any **secondary** sites should point only to read-only database nodes.
-
-#### Can Geo detect the current site correctly?
-
-Geo finds the current Puma or Sidekiq node's Geo [site](../glossary.md) name in
-`/etc/gitlab/gitlab.rb` with the following logic:
-
-1. Get the "Geo node name" (there is
-   [an issue to rename the settings to "Geo site name"](https://gitlab.com/gitlab-org/gitlab/-/issues/335944)):
-   - Linux package: get the `gitlab_rails['geo_node_name']` setting.
-   - GitLab Helm charts: get the `global.geo.nodeName` setting (see [Charts with GitLab Geo](https://docs.gitlab.com/charts/advanced/geo/index.html)).
-1. If that is not defined, then get the `external_url` setting.
-
-This name is used to look up the Geo site with the same **Name** in the **Geo Sites**
-dashboard.
-
-To check if the current machine has a site name that matches a site in the
-database, run the check task:
-
-```shell
-sudo gitlab-rake gitlab:geo:check
-```
-
-It displays the current machine's site name and whether the matching database
-record is a **primary** or **secondary** site.
-
-```plaintext
-This machine's Geo node name matches a database record ... yes, found a secondary node named "Shanghai"
-```
-
-```plaintext
-This machine's Geo node name matches a database record ... no
-  Try fixing it:
-  You could add or update a Geo node database record, setting the name to "https://example.com/".
-  Or you could set this machine's Geo node name to match the name of an existing database record: "London", "Shanghai"
-  For more information see:
-  doc/administration/geo/replication/troubleshooting.md#can-geo-detect-the-current-node-correctly
-```
-
-For more information about recommended site names in the description of the Name field, see
-[Geo Admin Area Common Settings](../../../administration/geo_sites.md#common-settings).
-
-### Reverify all uploads (or any SSF data type which is verified)
-
-1. SSH into a GitLab Rails node in the primary Geo site.
-1. Open [Rails console](../../operations/rails_console.md).
-1. Mark all uploads as "pending verification":
-
-WARNING:
-Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
-
-   ```ruby
-   Upload.verification_state_table_class.each_batch do |relation|
-     relation.update_all(verification_state: 0)
-   end
-   ```
-
-1. This causes the primary to start checksumming all Uploads.
-1. When a primary successfully checksums a record, then all secondaries recalculate the checksum as well, and they compare the values.
-
-A similar thing can be done for all Models handled by the [Geo Self-Service Framework](../../../development/geo/framework.md) which have implemented verification:
-
-- `LfsObject`
-- `MergeRequestDiff`
-- `Packages::PackageFile`
-- `Terraform::StateVersion`
-- `SnippetRepository`
-- `Ci::PipelineArtifact`
-- `PagesDeployment`
-- `Upload`
-- `Ci::JobArtifact`
-- `Ci::SecureFile`
-
-NOTE:
-`GroupWikiRepository` is not in the previous list since verification is not implemented.
-There is an [issue to implement this functionality in the Admin Area UI](https://gitlab.com/gitlab-org/gitlab/-/issues/364729).
-
-### Message: `WARNING: oldest xmin is far in the past` and `pg_wal` size growing
-
-If a replication slot is inactive,
-the `pg_wal` logs corresponding to the slot are reserved forever
-(or until the slot is active again). This causes continuous disk usage growth
-and the following messages appear repeatedly in the
-[PostgreSQL logs](../../logs/index.md#postgresql-logs):
-
-```plaintext
-WARNING: oldest xmin is far in the past
-HINT: Close open transactions soon to avoid wraparound problems.
-You might also need to commit or roll back old prepared transactions, or drop stale replication slots.
-```
-
-To fix this:
-
-1. [Connect to the primary database](https://docs.gitlab.com/omnibus/settings/database.html#connecting-to-the-bundled-postgresql-database).
-
-1. Run `SELECT * FROM pg_replication_slots;`.
-   Note the `slot_name` that reports `active` as `f` (false).
-
-1. Follow [the steps to remove that Geo site](remove_geo_site.md).
-
-## Fixing errors found when running the Geo check Rake task
+##### Fixing errors found when running the Geo check Rake task
 
 When running this Rake task, you may see error messages if the nodes are not properly configured:
 
@@ -455,7 +343,7 @@ sudo gitlab-rake gitlab:geo:check
   - If you are running the secondary site's tracking database in an external database, then follow [Geo with external PostgreSQL instances](../setup/external_database.md#configure-the-tracking-database)
   - If the Geo check task was run on a node which is not running a service which runs the GitLab Rails app (Puma, Sidekiq, or Geo Log Cursor), then this error can be ignored. The node does not need Rails to be configured.
 
-### Message: Machine clock is synchronized ... Exception
+##### Message: Machine clock is synchronized ... Exception
 
 The Rake task attempts to verify that the server clock is synchronized with NTP. Synchronized clocks
 are required for Geo to function correctly. As an example, for security, when the server time on the
@@ -489,7 +377,7 @@ generate an error because containers in Kubernetes do not have access to the hos
 Machine clock is synchronized ... Exception: getaddrinfo: Servname not supported for ai_socktype
 ```
 
-### Message: `ActiveRecord::StatementInvalid: PG::ReadOnlySqlTransaction: ERROR:  cannot execute INSERT in a read-only transaction`
+##### Message: `ActiveRecord::StatementInvalid: PG::ReadOnlySqlTransaction: ERROR:  cannot execute INSERT in a read-only transaction`
 
 When this error is encountered on a secondary site, it likely affects all usages of GitLab Rails such as `gitlab-rails` or `gitlab-rake` commands, as well the Puma, Sidekiq, and Geo Log Cursor services.
 
@@ -522,8 +410,122 @@ This situation can occur during initial configuration when a secondary site is n
 
 To resolve the error, follow [Step 3. Add the secondary site](configuration.md#step-3-add-the-secondary-site).
 
+### Check if PostgreSQL replication is working
+
+To check if PostgreSQL replication is working, check if:
+
+- [Sites are pointing to the correct database node](#are-sites-pointing-to-the-correct-database-node).
+- [Geo can detect the current site correctly](#can-geo-detect-the-current-site-correctly).
+
+#### Are sites pointing to the correct database node?
+
+You should make sure your **primary** Geo [site](../glossary.md) points to
+the database node that has write permissions.
+
+Any **secondary** sites should point only to read-only database nodes.
+
+#### Can Geo detect the current site correctly?
+
+Geo finds the current Puma or Sidekiq node's Geo [site](../glossary.md) name in
+`/etc/gitlab/gitlab.rb` with the following logic:
+
+1. Get the "Geo node name" (there is
+   [an issue to rename the settings to "Geo site name"](https://gitlab.com/gitlab-org/gitlab/-/issues/335944)):
+   - Linux package: get the `gitlab_rails['geo_node_name']` setting.
+   - GitLab Helm charts: get the `global.geo.nodeName` setting (see [Charts with GitLab Geo](https://docs.gitlab.com/charts/advanced/geo/index.html)).
+1. If that is not defined, then get the `external_url` setting.
+
+This name is used to look up the Geo site with the same **Name** in the **Geo Sites**
+dashboard.
+
+To check if the current machine has a site name that matches a site in the
+database, run the check task:
+
+```shell
+sudo gitlab-rake gitlab:geo:check
+```
+
+It displays the current machine's site name and whether the matching database
+record is a **primary** or **secondary** site.
+
+```plaintext
+This machine's Geo node name matches a database record ... yes, found a secondary node named "Shanghai"
+```
+
+```plaintext
+This machine's Geo node name matches a database record ... no
+  Try fixing it:
+  You could add or update a Geo node database record, setting the name to "https://example.com/".
+  Or you could set this machine's Geo node name to match the name of an existing database record: "London", "Shanghai"
+  For more information see:
+  doc/administration/geo/replication/troubleshooting.md#can-geo-detect-the-current-node-correctly
+```
+
+For more information about recommended site names in the description of the Name field, see
+[Geo Admin Area Common Settings](../../../administration/geo_sites.md#common-settings).
+
+### Check OS locale data compatibility
+
+If different operating systems or different operating system versions are deployed across Geo sites, you should perform a locale data compatibility check before setting up Geo.
+
+Geo uses PostgreSQL and Streaming Replication to replicate data across Geo sites. PostgreSQL uses locale data provided by the operating system's C library for sorting text. If the locale data in the C library is incompatible across Geo sites, it can cause erroneous query results that lead to [incorrect behavior on secondary sites](https://gitlab.com/gitlab-org/gitlab/-/issues/360723).
+
+For example, Ubuntu 18.04 (and earlier) and RHEL/Centos7 (and earlier) are incompatible with their later releases.
+See the [PostgreSQL wiki for more details](https://wiki.postgresql.org/wiki/Locale_data_changes).
+
+On all hosts running PostgreSQL, across all Geo sites, run the following shell command:
+
+```shell
+( echo "1-1"; echo "11" ) | LC_COLLATE=en_US.UTF-8 sort
+```
+
+The output looks like either:
+
+```plaintext
+1-1
+11
+```
+
+or the reverse order:
+
+```plaintext
+11
+1-1
+```
+
+If the output is identical on all hosts, then they running compatible versions of locale data.
+
+If the output differs on some hosts, PostgreSQL replication does not work properly: indexes are corrupted on the database replicas. You should select operating system versions that are compatible.
+
+A full index rebuild is required if the on-disk data is transferred 'at rest' to an operating system with an incompatible locale, or through replication.
+
+This check is also required when using a mixture of GitLab deployments. The locale might be different between an Linux package install, a GitLab Docker container, a Helm chart deployment, or external database services.
+
 ## Fixing PostgreSQL database replication errors
 
+### Message: `WARNING: oldest xmin is far in the past` and `pg_wal` size growing
+
+If a replication slot is inactive,
+the `pg_wal` logs corresponding to the slot are reserved forever
+(or until the slot is active again). This causes continuous disk usage growth
+and the following messages appear repeatedly in the
+[PostgreSQL logs](../../logs/index.md#postgresql-logs):
+
+```plaintext
+WARNING: oldest xmin is far in the past
+HINT: Close open transactions soon to avoid wraparound problems.
+You might also need to commit or roll back old prepared transactions, or drop stale replication slots.
+```
+
+To fix this:
+
+1. [Connect to the primary database](https://docs.gitlab.com/omnibus/settings/database.html#connecting-to-the-bundled-postgresql-database).
+
+1. Run `SELECT * FROM pg_replication_slots;`.
+   Note the `slot_name` that reports `active` as `f` (false).
+
+1. Follow [the steps to remove that Geo site](remove_geo_site.md).
+
 The following sections outline troubleshooting steps for fixing replication
 error messages (indicated by `Database replication working? ... no` in the
 [`geo:check` output](#health-check-rake-task).
@@ -677,31 +679,68 @@ In GitLab 13.4, a seed project is added when GitLab is first installed. This mak
 on a new Geo secondary site. There is an [issue to account for seed projects](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5618)
 when checking the database.
 
-### Message: `Synchronization failed - Error syncing repository`
+## Synchronization errors
 
-WARNING:
-If large repositories are affected by this problem,
-their resync may take a long time and cause significant load on your Geo sites,
-storage and network systems.
+### Reverify all uploads (or any SSF data type which is verified)
 
-If you see the error message `Synchronization failed - Error syncing repository` along with `fatal: fsck error in packed object`, this indicates
-a consistency check error when syncing the repository.
+1. SSH into a GitLab Rails node in the primary Geo site.
+1. Open [Rails console](../../operations/rails_console.md).
+1. Mark all uploads as "pending verification":
 
-One example of a consistency error is: `error: object f4a87a3be694fbbd6e50a668a31a8513caeaafe3: hasDotgit: contains '.git`.
+WARNING:
+Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
 
-Removing the malformed objects causing consistency errors require rewriting the repository history, which is not always an option. However,
-it's possible to override the consistency checks instead. To do that, follow
-[the instructions in the Gitaly docs](../../gitaly/configure_gitaly.md#repository-consistency-checks).
+   ```ruby
+   Upload.verification_state_table_class.each_batch do |relation|
+     relation.update_all(verification_state: 0)
+   end
+   ```
 
-You can also get the error message `Synchronization failed - Error syncing repository` along with the following log messages, this indicates that the expected `geo` remote is not present in the `.git/config` file
-of a repository on the secondary Geo site's file system:
+1. This causes the primary to start checksumming all Uploads.
+1. When a primary successfully checksums a record, then all secondaries recalculate the checksum as well, and they compare the values.
 
-```json
-{
-  "created": "@1603481145.084348757",
-  "description": "Error received from peer unix:/var/opt/gitlab/gitaly/gitaly.socket",
-  …
-  "grpc_message": "exit status 128",
+You can perform a similar operation with other the Models handled by the [Geo Self-Service Framework](../../../development/geo/framework.md) which have implemented verification:
+
+- `LfsObject`
+- `MergeRequestDiff`
+- `Packages::PackageFile`
+- `Terraform::StateVersion`
+- `SnippetRepository`
+- `Ci::PipelineArtifact`
+- `PagesDeployment`
+- `Upload`
+- `Ci::JobArtifact`
+- `Ci::SecureFile`
+
+NOTE:
+`GroupWikiRepository` is not in the previous list since verification is not implemented.
+There is an [issue to implement this functionality in the Admin Area UI](https://gitlab.com/gitlab-org/gitlab/-/issues/364729).
+
+### Message: `Synchronization failed - Error syncing repository`
+
+WARNING:
+If large repositories are affected by this problem,
+their resync may take a long time and cause significant load on your Geo sites,
+storage and network systems.
+
+If you see the error message `Synchronization failed - Error syncing repository` along with `fatal: fsck error in packed object`, this indicates
+a consistency check error when syncing the repository.
+
+One example of a consistency error is: `error: object f4a87a3be694fbbd6e50a668a31a8513caeaafe3: hasDotgit: contains '.git`.
+
+Removing the malformed objects causing consistency errors require rewriting the repository history, which is not always an option. However,
+it's possible to override the consistency checks instead. To do that, follow
+[the instructions in the Gitaly docs](../../gitaly/configure_gitaly.md#repository-consistency-checks).
+
+You can also get the error message `Synchronization failed - Error syncing repository` along with the following log messages, this indicates that the expected `geo` remote is not present in the `.git/config` file
+of a repository on the secondary Geo site's file system:
+
+```json
+{
+  "created": "@1603481145.084348757",
+  "description": "Error received from peer unix:/var/opt/gitlab/gitaly/gitaly.socket",
+  …
+  "grpc_message": "exit status 128",
   "grpc_status": 13
 }
 {  …
@@ -749,212 +788,11 @@ To solve this:
    end
    ```
 
-### Very large repositories never successfully synchronize on the **secondary** site
-
-#### GitLab 10.1 and earlier
-
-GitLab places a timeout on all repository clones, including project imports
-and Geo synchronization operations. If a fresh `git clone` of a repository
-on the **primary** takes more than the default three hours, you may be affected by this.
-
-To increase the timeout:
-
-1. On the **Sidekiq nodes on your secondary** site,
-add the following line to `/etc/gitlab/gitlab.rb`:
-
-   ```ruby
-   gitlab_rails['gitlab_shell_git_timeout'] = 14400
-   ```
-
-1. Reconfigure GitLab:
-
-   ```shell
-   sudo gitlab-ctl reconfigure
-   ```
-
-This increases the timeout to four hours (14400 seconds). Choose a time
-long enough to accommodate a full clone of your largest repositories.
-
-#### GitLab 10.2 and later
-
-Geo [replicates Git repositories over HTTPS](../index.md#how-it-works). GitLab does not place a timeout on these requests. If a Git repository is failing to replicate, with a consistent job execution time, then you should check for timeouts applied by external components such as load balancers.
-
-### New LFS objects are never replicated
-
-If new LFS objects are never replicated to secondary Geo sites, check the version of
-GitLab you are running. GitLab versions 11.11.x or 12.0.x are affected by
-[a bug that results in new LFS objects not being replicated to Geo secondary sites](https://gitlab.com/gitlab-org/gitlab/-/issues/32696).
-
-To resolve the issue, upgrade to GitLab 12.1 or later.
-
 ### Failures during backfill
 
 During a [backfill](../index.md#backfill), failures are scheduled to be retried at the end
 of the backfill queue, therefore these failures only clear up **after** the backfill completes.
 
-### Resetting Geo **secondary** site replication
-
-If you get a **secondary** site in a broken state and want to reset the replication state,
-to start again from scratch, there are a few steps that can help you:
-
-1. Stop Sidekiq and the Geo LogCursor.
-
-   It's possible to make Sidekiq stop gracefully, but making it stop getting new jobs and
-   wait until the current jobs to finish processing.
-
-   You need to send a **SIGTSTP** kill signal for the first phase and them a **SIGTERM**
-   when all jobs have finished. Otherwise just use the `gitlab-ctl stop` commands.
-
-   ```shell
-   gitlab-ctl status sidekiq
-   # run: sidekiq: (pid 10180) <- this is the PID you will use
-   kill -TSTP 10180 # change to the correct PID
-
-   gitlab-ctl stop sidekiq
-   gitlab-ctl stop geo-logcursor
-   ```
-
-   You can watch the [Sidekiq logs](../../logs/index.md#sidekiq-logs) to know when Sidekiq jobs processing has finished:
-
-   ```shell
-   gitlab-ctl tail sidekiq
-   ```
-
-1. Rename repository storage folders and create new ones. If you are not concerned about possible orphaned directories and files, you can skip this step.
-
-   ```shell
-   mv /var/opt/gitlab/git-data/repositories /var/opt/gitlab/git-data/repositories.old
-   mkdir -p /var/opt/gitlab/git-data/repositories
-   chown git:git /var/opt/gitlab/git-data/repositories
-   ```
-
-   NOTE:
-   You may want to remove the `/var/opt/gitlab/git-data/repositories.old` in the future
-   as soon as you confirmed that you don't need it anymore, to save disk space.
-
-1. Optional. Rename other data folders and create new ones.
-
-   WARNING:
-   You may still have files on the **secondary** site that have been removed from the **primary** site, but this
-   removal has not been reflected. If you skip this step, these files are not removed from the Geo **secondary** site.
-
-   Any uploaded content (like file attachments, avatars, or LFS objects) is stored in a
-   subfolder in one of these paths:
-
-   - `/var/opt/gitlab/gitlab-rails/shared`
-   - `/var/opt/gitlab/gitlab-rails/uploads`
-
-   To rename all of them:
-
-   ```shell
-   gitlab-ctl stop
-
-   mv /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-rails/shared.old
-   mkdir -p /var/opt/gitlab/gitlab-rails/shared
-
-   mv /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/uploads.old
-   mkdir -p /var/opt/gitlab/gitlab-rails/uploads
-
-   gitlab-ctl start postgresql
-   gitlab-ctl start geo-postgresql
-   ```
-
-   Reconfigure to recreate the folders and make sure permissions and ownership
-   are correct:
-
-   ```shell
-   gitlab-ctl reconfigure
-   ```
-
-1. Reset the Tracking Database.
-
-   WARNING:
-   If you skipped the optional step 3, be sure both `geo-postgresql` and `postgresql` services are running.
-
-   ```shell
-   gitlab-rake db:drop:geo DISABLE_DATABASE_ENVIRONMENT_CHECK=1   # on a secondary app node
-   gitlab-ctl reconfigure     # on the tracking database node
-   gitlab-rake db:migrate:geo # on a secondary app node
-   ```
-
-1. Restart previously stopped services.
-
-   ```shell
-   gitlab-ctl start
-   ```
-
-### Design repository failures on mirrored projects and project imports
-
-1. On the left sidebar, expand the top-most chevron (**{chevron-down}**).
-1. Select **Admin Area**.
-1. On the left sidebar, select **Geo > Sites**.
-
-If the Design repositories progress bar shows
-`Synced` and `Failed` greater than 100%, and negative `Queued`, the instance
-is likely affected by
-[a bug in GitLab 13.2 and 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/241668).
-It was [fixed in GitLab 13.4 and later](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/40643).
-
-To determine the actual replication status of design repositories in
-a [Rails console](../../operations/rails_console.md):
-
-```ruby
-secondary = Gitlab::Geo.current_node
-counts = {}
-secondary.designs.select("projects.id").find_each do |p|
-  registry = Geo::DesignRegistry.find_by(project_id: p.id)
-  state = registry ? "#{registry.state}" : "registry does not exist yet"
-  # puts "Design ID##{p.id}: #{state}" # uncomment this for granular information
-  counts[state] ||= 0
-  counts[state] += 1
-end
-puts "\nCounts:", counts
-```
-
-Example output:
-
-```plaintext
-Design ID#5: started
-Design ID#6: synced
-Design ID#7: failed
-Design ID#8: pending
-Design ID#9: synced
-
-Counts:
-{"started"=>1, "synced"=>2, "failed"=>1, "pending"=>1}
-```
-
-Example output if there are actually zero design repository replication failures:
-
-```plaintext
-Design ID#5: synced
-Design ID#6: synced
-Design ID#7: synced
-
-Counts:
-{"synced"=>3}
-```
-
-#### If you are promoting a Geo secondary site running on a single node
-
-`gitlab-ctl promotion-preflight-checks` fails due to the existence of
-`failed` rows in the `geo_design_registry` table. Use the
-[previous snippet](#design-repository-failures-on-mirrored-projects-and-project-imports) to
-determine the actual replication status of Design repositories.
-
-`gitlab-ctl promote-to-primary-node` fails since it runs preflight checks.
-If the [previous snippet](#design-repository-failures-on-mirrored-projects-and-project-imports)
-shows that all designs are synced, you can use the
-`--skip-preflight-checks` option or the `--force` option to move forward with
-promotion.
-
-#### If you are promoting a Geo secondary site running on multiple servers
-
-`gitlab-ctl promotion-preflight-checks` fails due to the existence of
-`failed` rows in the `geo_design_registry` table. Use the
-[previous snippet](#design-repository-failures-on-mirrored-projects-and-project-imports) to
-determine the actual replication status of Design repositories.
-
 ### Sync failure message: "Verification failed with: Error during verification: File is not checksummable"
 
 #### Missing files on the Geo primary site
@@ -1052,272 +890,280 @@ We recommend transferring each failing repository individually and checking for
 after each transfer. Follow the [single target `rsync` instructions](../../operations/moving_repositories.md#single-rsync-to-another-server)
 to transfer each affected repository from the primary to the secondary site.
 
-## Fixing errors during a failover or when promoting a secondary to a primary site
-
-The following are possible error messages that might be encountered during failover or
-when promoting a secondary to a primary site with strategies to resolve them.
+### Project or project wiki repositories
 
-### Message: `ActiveRecord::RecordInvalid: Validation failed: Name has already been taken`
+#### Find repository verification failures
 
-When [promoting a **secondary** site](../disaster_recovery/index.md#step-3-promoting-a-secondary-site),
-you might encounter the following error message:
+[Start a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session)
+**on the secondary Geo site** to gather more information.
 
-```plaintext
-Running gitlab-rake geo:set_secondary_as_primary...
+WARNING:
+Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
 
-rake aborted!
-ActiveRecord::RecordInvalid: Validation failed: Name has already been taken
-/opt/gitlab/embedded/service/gitlab-rails/ee/lib/tasks/geo.rake:236:in `block (3 levels) in <top (required)>'
-/opt/gitlab/embedded/service/gitlab-rails/ee/lib/tasks/geo.rake:221:in `block (2 levels) in <top (required)>'
-/opt/gitlab/embedded/bin/bundle:23:in `load'
-/opt/gitlab/embedded/bin/bundle:23:in `<main>'
-Tasks: TOP => geo:set_secondary_as_primary
-(See full trace by running task with --trace)
+##### Get the number of verification failed repositories
 
-You successfully promoted this node!
+```ruby
+Geo::ProjectRegistry.verification_failed('repository').count
 ```
 
-If you encounter this message when running `gitlab-rake geo:set_secondary_as_primary`
-or `gitlab-ctl promote-to-primary-node`, either:
-
-- Enter a Rails console and run:
+##### Find the verification failed repositories
 
-  ```ruby
-  Rails.application.load_tasks; nil
-  Gitlab::Geo.expire_cache!
-  Rake::Task['geo:set_secondary_as_primary'].invoke
-  ```
+```ruby
+Geo::ProjectRegistry.verification_failed('repository')
+```
 
-- Upgrade to GitLab 12.6.3 or later if it is safe to do so. For example,
-  if the failover was just a test. A
-  [caching-related bug](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22021) was fixed.
+##### Find repositories that failed to sync
 
-### Message: `ActiveRecord::RecordInvalid: Validation failed: Enabled Geo primary node cannot be disabled`
+```ruby
+Geo::ProjectRegistry.sync_failed('repository')
+```
 
-If you disabled a secondary site, either with the [replication pause task](../index.md#pausing-and-resuming-replication)
-(GitLab 13.2) or by using the user interface (GitLab 13.1 and earlier), you must first
-re-enable the site before you can continue. This is fixed in GitLab 13.4.
+#### Resync project and project wiki repositories
 
-This can be fixed in the database.
+[Start a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session)
+**on the secondary Geo site** to perform the following changes.
 
-1. Start a database console:
+WARNING:
+Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
 
-   In [GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/341210):
+##### Queue up all repositories for resync
 
-   ```shell
-   sudo gitlab-rails dbconsole --database main
-   ```
+When you run this, the sync is handled in the background by Sidekiq.
 
-   In GitLab 14.1 and earlier:
+```ruby
+Geo::ProjectRegistry.update_all(resync_repository: true, resync_wiki: true)
+```
 
-   ```shell
-   sudo gitlab-rails dbconsole
-   ```
+##### Sync individual repository now
 
-1. Run the following command, replacing  `https://<secondary url>/` with the URL
-   for your secondary node. You can use either `http` or `https`, but ensure that you
-   end the URL with a slash (`/`):
+```ruby
+project = Project.find_by_full_path('<group/project>')
 
-   ```sql
-   UPDATE geo_nodes SET enabled = true WHERE url = 'https://<secondary url>/' AND enabled = false;"
-   ```
+Geo::RepositorySyncService.new(project).execute
+```
 
-   This should update one row.
+##### Sync all failed repositories now
 
-### Message: ``NoMethodError: undefined method `secondary?' for nil:NilClass``
+The following script:
 
-When [promoting a **secondary** site](../disaster_recovery/index.md#step-3-promoting-a-secondary-site),
-you might encounter the following error message:
+- Loops over all currently failed repositories.
+- Displays the project details and the reasons for the last failure.
+- Attempts to resync the repository.
+- Reports back if a failure occurs, and why.
 
-```plaintext
-sudo gitlab-rake geo:set_secondary_as_primary
-
-rake aborted!
-NoMethodError: undefined method `secondary?' for nil:NilClass
-/opt/gitlab/embedded/service/gitlab-rails/ee/lib/tasks/geo.rake:232:in `block (3 levels) in <top (required)>'
-/opt/gitlab/embedded/service/gitlab-rails/ee/lib/tasks/geo.rake:221:in `block (2 levels) in <top (required)>'
-/opt/gitlab/embedded/bin/bundle:23:in `load'
-/opt/gitlab/embedded/bin/bundle:23:in `<main>'
-Tasks: TOP => geo:set_secondary_as_primary
-(See full trace by running task with --trace)
+```ruby
+Geo::ProjectRegistry.sync_failed('repository').find_each do |p|
+   begin
+     project = p.project
+     puts "#{project.full_path} | id: #{p.project_id} | last error: '#{p.last_repository_sync_failure}'"
+     Geo::RepositorySyncService.new(project).execute
+   rescue => e
+     puts "ID: #{p.project_id} failed: '#{e}'", e.backtrace.join("\n")
+   end
+end ; nil
 ```
 
-This command is intended to be executed on a secondary site only, and this error message
-is displayed if you attempt to run this command on a primary site.
+### Find repository check failures in a Geo secondary site
 
-### Message: `sudo: gitlab-pg-ctl: command not found`
+When [enabled for all projects](../../repository_checks.md#enable-repository-checks-for-all-projects), [Repository checks](../../repository_checks.md) are also performed on Geo secondary sites. The metadata is stored in the Geo tracking database.
 
-When
-[promoting a **secondary** site with multiple nodes](../disaster_recovery/index.md#promoting-a-secondary-site-with-multiple-nodes-running-gitlab-144-and-earlier),
-you need to run the `gitlab-pg-ctl` command to promote the PostgreSQL
-read-replica database.
+Repository check failures on a Geo secondary site do not necessarily imply a replication problem. Here is a general approach to resolve these failures.
 
-In GitLab 12.8 and earlier, this command fails with the message:
+1. Find affected repositories as mentioned below, as well as their [logged errors](../../repository_checks.md#what-to-do-if-a-check-failed).
+1. Try to diagnose specific `git fsck` errors. The range of possible errors is wide, try putting them into search engines.
+1. Test typical functions of the affected repositories. Pull from the secondary, view the files.
+1. Check if the primary site's copy of the repository has an identical `git fsck` error. If you are planning a failover, then consider prioritizing that the secondary site has the same information that the primary site has. Ensure you have a backup of the primary, and follow [planned failover guidelines](../disaster_recovery/planned_failover.md).
+1. Push to the primary and check if the change gets replicated to the secondary site.
+1. If replication is not automatically working, try to manually sync the repository.
 
-```plaintext
-sudo: gitlab-pg-ctl: command not found
+[Start a Rails console session](../../operations/rails_console.md#starting-a-rails-console-session)
+to enact the following, basic troubleshooting steps.
+
+WARNING:
+Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+
+#### Get the number of repositories that failed the repository check
+
+```ruby
+Geo::ProjectRegistry.where(last_repository_check_failed: true).count
 ```
 
-In this case, the workaround is to use the full path to the binary, for example:
+#### Find the repositories that failed the repository check
 
-```shell
-sudo /opt/gitlab/embedded/bin/gitlab-pg-ctl promote
+```ruby
+Geo::ProjectRegistry.where(last_repository_check_failed: true)
 ```
 
-GitLab 12.9 and later are [unaffected by this error message](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5147).
+#### Recheck repositories that failed the repository check
 
-### Message: `ERROR - Replication is not up-to-date` during `gitlab-ctl promotion-preflight-checks`
+When you run this, `fsck` is executed against each failed repository.
 
-In GitLab 13.7 and earlier, if you have a data type with zero items to sync,
-this command reports `ERROR - Replication is not up-to-date` even if
-replication is actually up-to-date. This bug was fixed in GitLab 13.8 and
-later.
+The [`fsck` Rake command](../../raketasks/check.md#check-project-code-repositories) can be used on the secondary site to understand why the repository check might be failing.
 
-### Message: `ERROR - Replication is not up-to-date` during `gitlab-ctl promote-to-primary-node`
+```ruby
+Geo::ProjectRegistry.where(last_repository_check_failed: true).each do |pr|
+    RepositoryCheck::SingleRepositoryWorker.new.perform(pr.project_id)
+end
+```
 
-In GitLab 13.7 and earlier, if you have a data type with zero items to sync,
-this command reports `ERROR - Replication is not up-to-date` even if
-replication is actually up-to-date. If replication and verification output
-shows that it is complete, you can add `--skip-preflight-checks` to make the command complete promotion. This bug was fixed in GitLab 13.8 and later.
+## Fixing non-PostgreSQL replication failures
 
-### Errors when using `--skip-preflight-checks` or `--force`
+If you notice replication failures in `Admin > Geo > Sites` or the [Sync status Rake task](#sync-status-rake-task), you can try to resolve the failures with the following general steps:
 
-In GitLab 13.4 and earlier, you could receive one of the following error messages when using
-`--skip-preflight-checks` or `--force`:
+1. Geo automatically retries failures. If the failures are new and few in number, or if you suspect the root cause is already resolved, then you can wait to see if the failures go away.
+1. If failures were present for a long time, then many retries have already occurred, and the interval between automatic retries has increased to up to 4 hours depending on the type of failure. If you suspect the root cause is already resolved, you can [manually retry replication or verification](#manually-retry-replication-or-verification).
+1. If the failures persist, use the following sections to try to resolve them.
 
-```plaintext
-get_ctl_options': invalid option: --skip-preflight-checks (OptionParser::InvalidOption)
+### Manually retry replication or verification
 
-get_ctl_options': invalid option: --force (OptionParser::InvalidOption)
-```
+Project Git repositories and Project Wiki Git repositories have the ability in `Admin > Geo > Replication` to `Resync all`, `Reverify all`, or for a single resource, `Resync`  or `Reverify`.
 
-This can happen with XFS or file systems that list files in lexical order, because the
-load order of the Linux package command files can be different than expected, and a global function would get redefined.
-More details can be found in [the related issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/6076).
+Adding this ability to other data types is proposed in issue [364725](https://gitlab.com/gitlab-org/gitlab/-/issues/364725).
 
-The workaround is to manually run the preflight checks and promote the database, by running
-the following commands on the Geo secondary site:
+The following sections describe how to use internal application commands in the [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session) to cause replication or verification immediately.
 
-```shell
-sudo gitlab-ctl promotion-preflight-checks
-sudo /opt/gitlab/embedded/bin/gitlab-pg-ctl promote
-sudo gitlab-ctl reconfigure
-sudo gitlab-rake geo:set_secondary_as_primary
-```
+WARNING:
+Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
 
-## Expired artifacts
+### Blob types
 
-If you notice for some reason there are more artifacts on the Geo
-**secondary** site than on the Geo **primary** site, you can use the Rake task
-to [cleanup orphan artifact files](../../../raketasks/cleanup.md#remove-orphan-artifact-files).
+- `Ci::JobArtifact`
+- `Ci::PipelineArtifact`
+- `Ci::SecureFile`
+- `LfsObject`
+- `MergeRequestDiff`
+- `Packages::PackageFile`
+- `PagesDeployment`
+- `Terraform::StateVersion`
+- `Upload`
 
-On a Geo **secondary** site, this command also cleans up all Geo
-registry record related to the orphan files on disk.
+`Packages::PackageFile` is used in the following
+[Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session)
+examples, but things generally work the same for the other types.
 
-## Fixing sign in errors
+WARNING:
+Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
 
-### Message: The redirect URI included is not valid
+### Repository types, except for project or project wiki repositories
 
-If you are able to sign in to the web interface for the **primary** site, but you receive this error message
-when attempting to sign in to a **secondary** web interface, you should verify the Geo
-site's URL matches its external URL.
+- `SnippetRepository`
+- `GroupWikiRepository`
 
-On the **primary** site:
+`SnippetRepository` is used in the examples below, but things generally work the same for the other Repository types.
 
-1. On the left sidebar, expand the top-most chevron (**{chevron-down}**).
-1. Select **Admin Area**.
-1. On the left sidebar, select **Geo > Sites**.
-1. Find the affected **secondary** site and select **Edit**.
-1. Ensure the **URL** field matches the value found in `/etc/gitlab/gitlab.rb`
-   in `external_url "https://gitlab.example.com"` on the **Rails nodes of the secondary** site.
+[Start a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session)
+to enact the following, basic troubleshooting steps.
 
-### Authenticating with SAML on the secondary site always lands on the primary site
+WARNING:
+Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
 
-This [problem is usually encountered when upgrading to GitLab 15.1](version_specific_upgrades.md#upgrading-to-151). To fix this problem, see [configuring instance-wide SAML in Geo with Single Sign-On](single_sign_on.md#configuring-instance-wide-saml).
+#### The Replicator
 
-## Fixing common errors
+The main kinds of classes are Registry, Model, and Replicator. If you have an instance of one of these classes, you can get the others. The Registry and Model mostly manage PostgreSQL DB state. The Replicator knows how to replicate/verify (or it can call a service to do it):
 
-This section documents common error messages reported in the Admin Area on the web interface, and how to fix them.
+```ruby
+model_record = Packages::PackageFile.last
+model_record.replicator.registry.replicator.model_record # just showing that these methods exist
+```
 
-### Geo database configuration file is missing
+#### Replicate a package file, synchronously, given an ID
 
-GitLab cannot find or doesn't have permission to access the `database_geo.yml` configuration file.
+```ruby
+model_record = Packages::PackageFile.find(id)
+model_record.replicator.send(:download)
+```
 
-In a Linux package installation, the file should be in `/var/opt/gitlab/gitlab-rails/etc`.
-If it doesn't exist or inadvertent changes have been made to it, run `sudo gitlab-ctl reconfigure` to restore it to its correct state.
+#### Replicate a package file, synchronously, given a registry ID
 
-If this path is mounted on a remote volume, ensure your volume configuration
-has the correct permissions.
+```ruby
+registry = Geo::PackageFileRegistry.find(registry_id)
+registry.replicator.send(:download)
+```
 
-### An existing tracking database cannot be reused
+#### Find registry records of blobs that failed to sync
 
-Geo cannot reuse an existing tracking database.
+```ruby
+Geo::PackageFileRegistry.failed
+```
 
-It is safest to use a fresh secondary, or reset the whole secondary by following
-[Resetting Geo secondary site replication](#resetting-geo-secondary-site-replication).
+#### Find registry records of blobs that are missing on the primary site
 
-### Geo site has a database that is writable which is an indication it is not configured for replication with the primary site
+```ruby
+Geo::PackageFileRegistry.where(last_sync_failure: 'The file is missing on the Geo primary site')
+```
 
-This error message refers to a problem with the database replica on a **secondary** site,
-which Geo expects to have access to. It usually means, either:
+#### Verify package files on the secondary manually
 
-- An unsupported replication method was used (for example, logical replication).
-- The instructions to set up a [Geo database replication](../setup/database.md) were not followed correctly.
-- Your database connection details are incorrect, that is you have specified the wrong
-  user in your `/etc/gitlab/gitlab.rb` file.
+This iterates over all package files on the secondary, looking at the
+`verification_checksum` stored in the database (which came from the primary)
+and then calculate this value on the secondary to check if they match. This
+does not change anything in the UI.
 
-Geo **secondary** sites require two separate PostgreSQL instances:
+For GitLab 14.4 and later:
 
-- A read-only replica of the **primary** site.
-- A regular, writable instance that holds replication metadata. That is, the Geo tracking database.
+```ruby
+# Run on secondary
+status = {}
 
-This error message indicates that the replica database in the **secondary** site is misconfigured and replication has stopped.
+Packages::PackageFile.find_each do |package_file|
+  primary_checksum = package_file.verification_checksum
+  secondary_checksum = Packages::PackageFile.sha256_hexdigest(package_file.file.path)
+  verification_status = (primary_checksum == secondary_checksum)
 
-To restore the database and resume replication, you can do one of the following:
+  status[verification_status.to_s] ||= []
+  status[verification_status.to_s] << package_file.id
+end
 
-- [Reset the Geo secondary site replication](#resetting-geo-secondary-site-replication).
-- [Set up a new Geo secondary using the Linux package](../setup/index.md#using-linux-package-installations).
+# Count how many of each value we get
+status.keys.each {|key| puts "#{key} count: #{status[key].count}"}
 
-If you set up a new secondary from scratch, you must also [remove the old site from the Geo cluster](remove_geo_site.md#removing-secondary-geo-sites).
+# See the output in its entirety
+status
+```
 
-### Geo site does not appear to be replicating the database from the primary site
+For GitLab 14.3 and earlier:
 
-The most common problems that prevent the database from replicating correctly are:
+```ruby
+# Run on secondary
+status = {}
 
-- **Secondary** sites cannot reach the **primary** site. Check credentials and
-  [firewall rules](../index.md#firewall-rules).
-- SSL certificate problems. Make sure you copied `/etc/gitlab/gitlab-secrets.json` from the **primary** site.
-- Database storage disk is full.
-- Database replication slot is misconfigured.
-- Database is not using a replication slot or another alternative and cannot catch-up because WAL files were purged.
+Packages::PackageFile.find_each do |package_file|
+  primary_checksum = package_file.verification_checksum
+  secondary_checksum = Packages::PackageFile.hexdigest(package_file.file.path)
+  verification_status = (primary_checksum == secondary_checksum)
 
-Make sure you follow the [Geo database replication](../setup/database.md) instructions for supported configuration.
+  status[verification_status.to_s] ||= []
+  status[verification_status.to_s] << package_file.id
+end
 
-### Geo database version (...) does not match latest migration (...)
+# Count how many of each value we get
+status.keys.each {|key| puts "#{key} count: #{status[key].count}"}
 
-If you are using the Linux package installation, something might have failed during upgrade. You can:
+# See the output in its entirety
+status
+```
 
-- Run `sudo gitlab-ctl reconfigure`.
-- Manually trigger the database migration by running: `sudo gitlab-rake db:migrate:geo` as root on the **secondary** site.
+#### Reverify all uploads (or any SSF data type which is verified)
 
-### GitLab indicates that more than 100% of repositories were synced
+1. SSH into a GitLab Rails node in the primary Geo site.
+1. Open [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session).
+1. Mark all uploads as "pending verification":
 
-This can be caused by orphaned records in the project registry. You can clear them
-[using the Rake task to remove orphaned project registries](../../../administration/raketasks/geo.md#remove-orphaned-project-registries).
+   ```ruby
+   Upload.verification_state_table_class.each_batch do |relation|
+     relation.update_all(verification_state: 0)
+   end
+   ```
 
-### Geo Admin Area returns 404 error for a secondary site
+1. This causes the primary to start checksumming all Uploads.
+1. When a primary successfully checksums a record, then all secondaries recalculate the checksum as well, and they compare the values.
 
-Sometimes `sudo gitlab-rake gitlab:geo:check` indicates that **Rails nodes of the secondary** sites are
-healthy, but a 404 Not Found error message for the **secondary** site is returned in the Geo Admin Area on the web interface for
-the **primary** site.
+For other SSF data types replace `Upload` in the command above with the desired model class.
 
-To resolve this issue:
+NOTE:
+There is an [issue to implement this functionality in the Admin Area UI](https://gitlab.com/gitlab-org/gitlab/-/issues/364729).
 
-- Try restarting **each Rails, Sidekiq and Gitaly nodes on your secondary site** using `sudo gitlab-ctl restart`.
-- Check `/var/log/gitlab/gitlab-rails/geo.log` on Sidekiq nodes to see if the **secondary** site is
-  using IPv6 to send its status to the **primary** site. If it is, add an entry to
-  the **primary** site using IPv4 in the `/etc/hosts` file. Alternatively, you should
-  [enable IPv6 on the **primary** site](https://docs.gitlab.com/omnibus/settings/nginx.html#setting-the-nginx-listen-address-or-addresses).
+## HTTP response code errors
 
 ### Secondary site returns 502 errors with Geo proxying
 
@@ -1343,14 +1189,6 @@ and changing the `8k` size, for example by doubling it to `16k`.
 If using a load balancer, ensure that the load balancer's URL is set as the `external_url` in the
 `/etc/gitlab/gitlab.rb` of the nodes behind the load balancer.
 
-### Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode
-
-In GitLab 13.9 through GitLab 14.3, when [GitLab Maintenance Mode](../../maintenance_mode/index.md) is enabled, the status of Geo secondary sites stops getting updated. After 10 minutes, the status changes to `Unhealthy`.
-
-Geo secondary sites continue to replicate and verify data, and the secondary sites should still be usable. You can use the [Sync status Rake task](#sync-status-rake-task) to determine the actual status of a secondary site during Maintenance Mode.
-
-This bug was [fixed in GitLab 14.4](https://gitlab.com/gitlab-org/gitlab/-/issues/292983).
-
 ### Primary site returns 500 error when accessing `/admin/geo/replication/projects`
 
 Navigating to **Admin > Geo > Replication** (or `/admin/geo/replication/projects`) on a primary Geo site, shows a 500 error, while that same link on the secondary works fine. The primary's `production.log` has a similar entry to the following:
@@ -1411,340 +1249,219 @@ The bug causes all wildcard domains (`.example.com`) to be ignored except for th
 
 You can have only one wildcard domain in the `no_proxy` list.
 
-### Secondary site shows "Unhealthy" in UI after changing the value of `external_url` for the primary site
+### Geo Admin Area returns 404 error for a secondary site
 
-If you have updated the value of `external_url` in `/etc/gitlab/gitlab.rb` for the primary site or changed the protocol from `http` to `https`, you may see that secondary sites are shown as `Unhealthy`. You may also find the following error in `geo.log`:
+Sometimes `sudo gitlab-rake gitlab:geo:check` indicates that **Rails nodes of the secondary** sites are
+healthy, but a 404 Not Found error message for the **secondary** site is returned in the Geo Admin Area on the web interface for
+the **primary** site.
 
-```plaintext
-"class": "Geo::NodeStatusRequestService",
-...
-"message": "Failed to Net::HTTP::Post to primary url: http://primary-site.gitlab.tld/api/v4/geo/status",
-  "error": "Failed to open TCP connection to <PRIMARY_IP_ADDRESS>:80 (Connection refused - connect(2) for \"<PRIMARY_ID_ADDRESS>\" port 80)"
-```
+To resolve this issue:
 
-In this case, make sure to update the changed URL on all your sites:
+- Try restarting **each Rails, Sidekiq and Gitaly nodes on your secondary site** using `sudo gitlab-ctl restart`.
+- Check `/var/log/gitlab/gitlab-rails/geo.log` on Sidekiq nodes to see if the **secondary** site is
+  using IPv6 to send its status to the **primary** site. If it is, add an entry to
+  the **primary** site using IPv4 in the `/etc/hosts` file. Alternatively, you should
+  [enable IPv6 on the **primary** site](https://docs.gitlab.com/omnibus/settings/nginx.html#setting-the-nginx-listen-address-or-addresses).
 
-1. On the left sidebar, expand the top-most chevron (**{chevron-down}**).
-1. Select **Admin Area**.
-1. On the left sidebar, select **Geo > Sites**.
-1. Change the URL and save the change.
-
-### Message: `ERROR: canceling statement due to conflict with recovery` during backup
-
-Running a backup on a Geo **secondary** [is not supported](https://gitlab.com/gitlab-org/gitlab/-/issues/211668).
-
-When running a backup on a **secondary** you might encounter the following error message:
-
-```plaintext
-Dumping PostgreSQL database gitlabhq_production ...
-pg_dump: error: Dumping the contents of table "notes" failed: PQgetResult() failed.
-pg_dump: error: Error message from server: ERROR:  canceling statement due to conflict with recovery
-DETAIL:  User query might have needed to see row versions that must be removed.
-pg_dump: error: The command was: COPY public.notes (id, note, [...], last_edited_at) TO stdout;
-```
-
-To prevent a database backup being made automatically during GitLab upgrades on your Geo **secondaries**,
-create the following empty file:
-
-```shell
-sudo touch /etc/gitlab/skip-auto-backup
-```
-
-## Fixing non-PostgreSQL replication failures
-
-If you notice replication failures in `Admin > Geo > Sites` or the [Sync status Rake task](#sync-status-rake-task), you can try to resolve the failures with the following general steps:
-
-1. Geo automatically retries failures. If the failures are new and few in number, or if you suspect the root cause is already resolved, then you can wait to see if the failures go away.
-1. If failures were present for a long time, then many retries have already occurred, and the interval between automatic retries has increased to up to 4 hours depending on the type of failure. If you suspect the root cause is already resolved, you can [manually retry replication or verification](#manually-retry-replication-or-verification).
-1. If the failures persist, use the following sections to try to resolve them.
-
-### Manually retry replication or verification
-
-Project Git repositories and Project Wiki Git repositories have the ability in `Admin > Geo > Replication` to `Resync all`, `Reverify all`, or for a single resource, `Resync`  or `Reverify`.
-
-Adding this ability to other data types is proposed in issue [364725](https://gitlab.com/gitlab-org/gitlab/-/issues/364725).
-
-The following sections describe how to use internal application commands in the [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session) to cause replication or verification immediately.
-
-WARNING:
-Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+## Fixing common errors
 
-### Blob types
+This section documents common error messages reported in the Admin Area on the web interface, and how to fix them.
 
-- `Ci::JobArtifact`
-- `Ci::PipelineArtifact`
-- `Ci::SecureFile`
-- `LfsObject`
-- `MergeRequestDiff`
-- `Packages::PackageFile`
-- `PagesDeployment`
-- `Terraform::StateVersion`
-- `Upload`
+### Geo database configuration file is missing
 
-`Packages::PackageFile` is used in the following
-[Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session)
-examples, but things generally work the same for the other types.
+GitLab cannot find or doesn't have permission to access the `database_geo.yml` configuration file.
 
-WARNING:
-Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+In a Linux package installation, the file should be in `/var/opt/gitlab/gitlab-rails/etc`.
+If it doesn't exist or inadvertent changes have been made to it, run `sudo gitlab-ctl reconfigure` to restore it to its correct state.
 
-#### The Replicator
+If this path is mounted on a remote volume, ensure your volume configuration
+has the correct permissions.
 
-The main kinds of classes are Registry, Model, and Replicator. If you have an instance of one of these classes, you can get the others. The Registry and Model mostly manage PostgreSQL DB state. The Replicator knows how to replicate/verify (or it can call a service to do it):
+### An existing tracking database cannot be reused
 
-```ruby
-model_record = Packages::PackageFile.last
-model_record.replicator.registry.replicator.model_record # just showing that these methods exist
-```
+Geo cannot reuse an existing tracking database.
 
-#### Replicate a package file, synchronously, given an ID
+It is safest to use a fresh secondary, or reset the whole secondary by following
+[Resetting Geo secondary site replication](#resetting-geo-secondary-site-replication).
 
-```ruby
-model_record = Packages::PackageFile.find(id)
-model_record.replicator.send(:download)
-```
+### Geo site has a database that is writable which is an indication it is not configured for replication with the primary site
 
-#### Replicate a package file, synchronously, given a registry ID
+This error message refers to a problem with the database replica on a **secondary** site,
+which Geo expects to have access to. It usually means, either:
 
-```ruby
-registry = Geo::PackageFileRegistry.find(registry_id)
-registry.replicator.send(:download)
-```
+- An unsupported replication method was used (for example, logical replication).
+- The instructions to set up a [Geo database replication](../setup/database.md) were not followed correctly.
+- Your database connection details are incorrect, that is you have specified the wrong
+  user in your `/etc/gitlab/gitlab.rb` file.
 
-#### Find registry records of blobs that failed to sync
+Geo **secondary** sites require two separate PostgreSQL instances:
 
-```ruby
-Geo::PackageFileRegistry.failed
-```
+- A read-only replica of the **primary** site.
+- A regular, writable instance that holds replication metadata. That is, the Geo tracking database.
 
-#### Find registry records of blobs that are missing on the primary site
+This error message indicates that the replica database in the **secondary** site is misconfigured and replication has stopped.
 
-```ruby
-Geo::PackageFileRegistry.where(last_sync_failure: 'The file is missing on the Geo primary site')
-```
+To restore the database and resume replication, you can do one of the following:
 
-#### Verify package files on the secondary manually
+- [Reset the Geo secondary site replication](#resetting-geo-secondary-site-replication).
+- [Set up a new Geo secondary using the Linux package](../setup/index.md#using-linux-package-installations).
 
-This iterates over all package files on the secondary, looking at the
-`verification_checksum` stored in the database (which came from the primary)
-and then calculate this value on the secondary to check if they match. This
-does not change anything in the UI.
+If you set up a new secondary from scratch, you must also [remove the old site from the Geo cluster](remove_geo_site.md#removing-secondary-geo-sites).
 
-For GitLab 14.4 and later:
+### Geo site does not appear to be replicating the database from the primary site
 
-```ruby
-# Run on secondary
-status = {}
+The most common problems that prevent the database from replicating correctly are:
 
-Packages::PackageFile.find_each do |package_file|
-  primary_checksum = package_file.verification_checksum
-  secondary_checksum = Packages::PackageFile.sha256_hexdigest(package_file.file.path)
-  verification_status = (primary_checksum == secondary_checksum)
+- **Secondary** sites cannot reach the **primary** site. Check credentials and
+  [firewall rules](../index.md#firewall-rules).
+- SSL certificate problems. Make sure you copied `/etc/gitlab/gitlab-secrets.json` from the **primary** site.
+- Database storage disk is full.
+- Database replication slot is misconfigured.
+- Database is not using a replication slot or another alternative and cannot catch-up because WAL files were purged.
 
-  status[verification_status.to_s] ||= []
-  status[verification_status.to_s] << package_file.id
-end
+Make sure you follow the [Geo database replication](../setup/database.md) instructions for supported configuration.
 
-# Count how many of each value we get
-status.keys.each {|key| puts "#{key} count: #{status[key].count}"}
+### Geo database version (...) does not match latest migration (...)
 
-# See the output in its entirety
-status
-```
+If you are using the Linux package installation, something might have failed during upgrade. You can:
 
-For GitLab 14.3 and earlier:
+- Run `sudo gitlab-ctl reconfigure`.
+- Manually trigger the database migration by running: `sudo gitlab-rake db:migrate:geo` as root on the **secondary** site.
 
-```ruby
-# Run on secondary
-status = {}
+### GitLab indicates that more than 100% of repositories were synced
 
-Packages::PackageFile.find_each do |package_file|
-  primary_checksum = package_file.verification_checksum
-  secondary_checksum = Packages::PackageFile.hexdigest(package_file.file.path)
-  verification_status = (primary_checksum == secondary_checksum)
+This can be caused by orphaned records in the project registry. You can clear them
+[using the Rake task to remove orphaned project registries](../../../administration/raketasks/geo.md#remove-orphaned-project-registries).
 
-  status[verification_status.to_s] ||= []
-  status[verification_status.to_s] << package_file.id
-end
+### Secondary site shows "Unhealthy" in UI after changing the value of `external_url` for the primary site
 
-# Count how many of each value we get
-status.keys.each {|key| puts "#{key} count: #{status[key].count}"}
+If you have updated the value of `external_url` in `/etc/gitlab/gitlab.rb` for the primary site or changed the protocol from `http` to `https`, you may see that secondary sites are shown as `Unhealthy`. You may also find the following error in `geo.log`:
 
-# See the output in its entirety
-status
+```plaintext
+"class": "Geo::NodeStatusRequestService",
+...
+"message": "Failed to Net::HTTP::Post to primary url: http://primary-site.gitlab.tld/api/v4/geo/status",
+  "error": "Failed to open TCP connection to <PRIMARY_IP_ADDRESS>:80 (Connection refused - connect(2) for \"<PRIMARY_ID_ADDRESS>\" port 80)"
 ```
 
-#### Reverify all uploads (or any SSF data type which is verified)
-
-1. SSH into a GitLab Rails node in the primary Geo site.
-1. Open [Rails console](../../../administration/operations/rails_console.md#starting-a-rails-console-session).
-1. Mark all uploads as "pending verification":
-
-   ```ruby
-   Upload.verification_state_table_class.each_batch do |relation|
-     relation.update_all(verification_state: 0)
-   end
-   ```
-
-1. This causes the primary to start checksumming all Uploads.
-1. When a primary successfully checksums a record, then all secondaries recalculate the checksum as well, and they compare the values.
-
-For other SSF data types replace `Upload` in the command above with the desired model class.
-
-NOTE:
-There is an [issue to implement this functionality in the Admin Area UI](https://gitlab.com/gitlab-org/gitlab/-/issues/364729).
-
-### Repository types, except for project or project wiki repositories
-
-- `SnippetRepository`
-- `GroupWikiRepository`
-
-`SnippetRepository` is used in the examples below, but things generally work the same for the other Repository types.
-
-[Start a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session)
-to enact the following, basic troubleshooting steps.
-
-WARNING:
-Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+In this case, make sure to update the changed URL on all your sites:
 
-#### The Replicator
+1. On the left sidebar, expand the top-most chevron (**{chevron-down}**).
+1. Select **Admin Area**.
+1. On the left sidebar, select **Geo > Sites**.
+1. Change the URL and save the change.
 
-The main kinds of classes are Registry, Model, and Replicator. If you have an instance of one of these classes, you can get the others. The Registry and Model mostly manage PostgreSQL DB state. The Replicator knows how to replicate/verify (or it can call a service to do it).
+### Message: `ERROR: canceling statement due to conflict with recovery` during backup
 
-```ruby
-model_record = SnippetRepository.last
-model_record.replicator.registry.replicator.model_record # just showing that these methods exist
-```
+Running a backup on a Geo **secondary** [is not supported](https://gitlab.com/gitlab-org/gitlab/-/issues/211668).
 
-#### Replicate a snippet repository, synchronously, given an ID
+When running a backup on a **secondary** you might encounter the following error message:
 
-```ruby
-model_record = SnippetRepository.find(id)
-model_record.replicator.send(:sync_repository)
+```plaintext
+Dumping PostgreSQL database gitlabhq_production ...
+pg_dump: error: Dumping the contents of table "notes" failed: PQgetResult() failed.
+pg_dump: error: Error message from server: ERROR:  canceling statement due to conflict with recovery
+DETAIL:  User query might have needed to see row versions that must be removed.
+pg_dump: error: The command was: COPY public.notes (id, note, [...], last_edited_at) TO stdout;
 ```
 
-#### Replicate a snippet repository, synchronously, given a registry ID
+To prevent a database backup being made automatically during GitLab upgrades on your Geo **secondaries**,
+create the following empty file:
 
-```ruby
-registry = Geo::SnippetRepositoryRegistry.find(registry_id)
-registry.replicator.send(:sync_repository)
+```shell
+sudo touch /etc/gitlab/skip-auto-backup
 ```
 
-### Project or project wiki repositories
-
-#### Find repository verification failures
-
-[Start a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session)
-**on the secondary Geo site** to gather more information.
-
-WARNING:
-Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+## Fixing errors during a failover or when promoting a secondary to a primary site
 
-##### Get the number of verification failed repositories
+The following are possible error messages that might be encountered during failover or
+when promoting a secondary to a primary site with strategies to resolve them.
 
-```ruby
-Geo::ProjectRegistry.verification_failed('repository').count
-```
+### Message: `ActiveRecord::RecordInvalid: Validation failed: Name has already been taken`
 
-##### Find the verification failed repositories
+When [promoting a **secondary** site](../disaster_recovery/index.md#step-3-promoting-a-secondary-site),
+you might encounter the following error message:
 
-```ruby
-Geo::ProjectRegistry.verification_failed('repository')
-```
+```plaintext
+Running gitlab-rake geo:set_secondary_as_primary...
 
-##### Find repositories that failed to sync
+rake aborted!
+ActiveRecord::RecordInvalid: Validation failed: Name has already been taken
+/opt/gitlab/embedded/service/gitlab-rails/ee/lib/tasks/geo.rake:236:in `block (3 levels) in <top (required)>'
+/opt/gitlab/embedded/service/gitlab-rails/ee/lib/tasks/geo.rake:221:in `block (2 levels) in <top (required)>'
+/opt/gitlab/embedded/bin/bundle:23:in `load'
+/opt/gitlab/embedded/bin/bundle:23:in `<main>'
+Tasks: TOP => geo:set_secondary_as_primary
+(See full trace by running task with --trace)
 
-```ruby
-Geo::ProjectRegistry.sync_failed('repository')
+You successfully promoted this node!
 ```
 
-#### Resync project and project wiki repositories
-
-[Start a Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session)
-**on the secondary Geo site** to perform the following changes.
-
-WARNING:
-Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
-
-##### Queue up all repositories for resync
-
-When you run this, the sync is handled in the background by Sidekiq.
-
-```ruby
-Geo::ProjectRegistry.update_all(resync_repository: true, resync_wiki: true)
-```
+If you encounter this message when running `gitlab-rake geo:set_secondary_as_primary`
+or `gitlab-ctl promote-to-primary-node`, either:
 
-##### Sync individual repository now
+- Enter a Rails console and run:
 
-```ruby
-project = Project.find_by_full_path('<group/project>')
+  ```ruby
+  Rails.application.load_tasks; nil
+  Gitlab::Geo.expire_cache!
+  Rake::Task['geo:set_secondary_as_primary'].invoke
+  ```
 
-Geo::RepositorySyncService.new(project).execute
-```
+- Upgrade to GitLab 12.6.3 or later if it is safe to do so. For example,
+  if the failover was just a test. A
+  [caching-related bug](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/22021) was fixed.
 
-##### Sync all failed repositories now
+### Message: ``NoMethodError: undefined method `secondary?' for nil:NilClass``
 
-The following script:
+When [promoting a **secondary** site](../disaster_recovery/index.md#step-3-promoting-a-secondary-site),
+you might encounter the following error message:
 
-- Loops over all currently failed repositories.
-- Displays the project details and the reasons for the last failure.
-- Attempts to resync the repository.
-- Reports back if a failure occurs, and why.
+```plaintext
+sudo gitlab-rake geo:set_secondary_as_primary
 
-```ruby
-Geo::ProjectRegistry.sync_failed('repository').find_each do |p|
-   begin
-     project = p.project
-     puts "#{project.full_path} | id: #{p.project_id} | last error: '#{p.last_repository_sync_failure}'"
-     Geo::RepositorySyncService.new(project).execute
-   rescue => e
-     puts "ID: #{p.project_id} failed: '#{e}'", e.backtrace.join("\n")
-   end
-end ; nil
+rake aborted!
+NoMethodError: undefined method `secondary?' for nil:NilClass
+/opt/gitlab/embedded/service/gitlab-rails/ee/lib/tasks/geo.rake:232:in `block (3 levels) in <top (required)>'
+/opt/gitlab/embedded/service/gitlab-rails/ee/lib/tasks/geo.rake:221:in `block (2 levels) in <top (required)>'
+/opt/gitlab/embedded/bin/bundle:23:in `load'
+/opt/gitlab/embedded/bin/bundle:23:in `<main>'
+Tasks: TOP => geo:set_secondary_as_primary
+(See full trace by running task with --trace)
 ```
 
-#### Find repository check failures in a Geo secondary site
-
-When [enabled for all projects](../../repository_checks.md#enable-repository-checks-for-all-projects), [Repository checks](../../repository_checks.md) are also performed on Geo secondary sites. The metadata is stored in the Geo tracking database.
-
-Repository check failures on a Geo secondary site do not necessarily imply a replication problem. Here is a general approach to resolve these failures.
-
-1. Find affected repositories as mentioned below, as well as their [logged errors](../../repository_checks.md#what-to-do-if-a-check-failed).
-1. Try to diagnose specific `git fsck` errors. The range of possible errors is wide, try putting them into search engines.
-1. Test typical functions of the affected repositories. Pull from the secondary, view the files.
-1. Check if the primary site's copy of the repository has an identical `git fsck` error. If you are planning a failover, then consider prioritizing that the secondary site has the same information that the primary site has. Ensure you have a backup of the primary, and follow [planned failover guidelines](../disaster_recovery/planned_failover.md).
-1. Push to the primary and check if the change gets replicated to the secondary site.
-1. If replication is not automatically working, try to manually sync the repository.
+This command is intended to be executed on a secondary site only, and this error message
+is displayed if you attempt to run this command on a primary site.
 
-[Start a Rails console session](../../operations/rails_console.md#starting-a-rails-console-session)
-to enact the following, basic troubleshooting steps.
+### Expired artifacts
 
-WARNING:
-Commands that change data can cause damage if not run correctly or under the right conditions. Always run commands in a test environment first and have a backup instance ready to restore.
+If you notice for some reason there are more artifacts on the Geo
+**secondary** site than on the Geo **primary** site, you can use the Rake task
+to [cleanup orphan artifact files](../../../raketasks/cleanup.md#remove-orphan-artifact-files).
 
-##### Get the number of repositories that failed the repository check
+On a Geo **secondary** site, this command also cleans up all Geo
+registry record related to the orphan files on disk.
 
-```ruby
-Geo::ProjectRegistry.where(last_repository_check_failed: true).count
-```
+### Fixing sign in errors
 
-##### Find the repositories that failed the repository check
+#### Message: The redirect URI included is not valid
 
-```ruby
-Geo::ProjectRegistry.where(last_repository_check_failed: true)
-```
+If you are able to sign in to the web interface for the **primary** site, but you receive this error message
+when attempting to sign in to a **secondary** web interface, you should verify the Geo
+site's URL matches its external URL.
 
-##### Recheck repositories that failed the repository check
+On the **primary** site:
 
-When you run this, `fsck` is executed against each failed repository.
+1. On the left sidebar, expand the top-most chevron (**{chevron-down}**).
+1. Select **Admin Area**.
+1. On the left sidebar, select **Geo > Sites**.
+1. Find the affected **secondary** site and select **Edit**.
+1. Ensure the **URL** field matches the value found in `/etc/gitlab/gitlab.rb`
+   in `external_url "https://gitlab.example.com"` on the **Rails nodes of the secondary** site.
 
-The [`fsck` Rake command](../../raketasks/check.md#check-project-code-repositories) can be used on the secondary site to understand why the repository check might be failing.
+#### Authenticating with SAML on the secondary site always lands on the primary site
 
-```ruby
-Geo::ProjectRegistry.where(last_repository_check_failed: true).each do |pr|
-    RepositoryCheck::SingleRepositoryWorker.new.perform(pr.project_id)
-end
-```
+This [problem is usually encountered when upgrading to GitLab 15.1](version_specific_upgrades.md#upgrading-to-151). To fix this problem, see [configuring instance-wide SAML in Geo with Single Sign-On](single_sign_on.md#configuring-instance-wide-saml).
 
 ## Fixing client errors
 
@@ -1816,43 +1533,6 @@ If the above steps are **not successful**, proceed through the next steps:
 1. Verify you can connect to the newly-promoted **primary** site using the URL used previously for the **secondary** site.
 1. If successful, the **secondary** site is now promoted to the **primary** site.
 
-## Check OS locale data compatibility
-
-If different operating systems or different operating system versions are deployed across Geo sites, you should perform a locale data compatibility check before setting up Geo.
-
-Geo uses PostgreSQL and Streaming Replication to replicate data across Geo sites. PostgreSQL uses locale data provided by the operating system's C library for sorting text. If the locale data in the C library is incompatible across Geo sites, it can cause erroneous query results that lead to [incorrect behavior on secondary sites](https://gitlab.com/gitlab-org/gitlab/-/issues/360723).
-
-For example, Ubuntu 18.04 (and earlier) and RHEL/Centos7 (and earlier) are incompatible with their later releases.
-See the [PostgreSQL wiki for more details](https://wiki.postgresql.org/wiki/Locale_data_changes).
-
-On all hosts running PostgreSQL, across all Geo sites, run the following shell command:
-
-```shell
-( echo "1-1"; echo "11" ) | LC_COLLATE=en_US.UTF-8 sort
-```
-
-The output looks like either:
-
-```plaintext
-1-1
-11
-```
-
-or the reverse order:
-
-```plaintext
-11
-1-1
-```
-
-If the output is identical on all hosts, then they running compatible versions of locale data.
-
-If the output differs on some hosts, PostgreSQL replication does not work properly: indexes are corrupted on the database replicas. You should select operating system versions that are compatible.
-
-A full index rebuild is required if the on-disk data is transferred 'at rest' to an operating system with an incompatible locale, or through replication.
-
-This check is also required when using a mixture of GitLab deployments. The locale might be different between an Linux package install, a GitLab Docker container, a Helm chart deployment, or external database services.
-
 ## Investigate causes of database replication lag
 
 If the output of `sudo gitlab-rake geo:status` shows that `Database replication lag` remains significantly high over time, the primary node in database replication can be checked to determine the status of lag for
@@ -1879,3 +1559,94 @@ If one or more of these values is significantly high, this could indicate a prob
 - The difference in time between `write_lag` and `flush_lag` indicates that WAL bytes have been sent to the underlying storage system, but it has not reported that they were flushed.
   This data is most likely not fully written to a persistent storage, and likely held in some kind of volatile write cache.
 - The difference between `flush_lag` and `replay_lag` indicates WAL bytes that have been successfully persisted to storage, but could not be replayed by the database system.
+
+## Resetting Geo **secondary** site replication
+
+If you get a **secondary** site in a broken state and want to reset the replication state,
+to start again from scratch, there are a few steps that can help you:
+
+1. Stop Sidekiq and the Geo LogCursor.
+
+   It's possible to make Sidekiq stop gracefully, but making it stop getting new jobs and
+   wait until the current jobs to finish processing.
+
+   You need to send a **SIGTSTP** kill signal for the first phase and them a **SIGTERM**
+   when all jobs have finished. Otherwise just use the `gitlab-ctl stop` commands.
+
+   ```shell
+   gitlab-ctl status sidekiq
+   # run: sidekiq: (pid 10180) <- this is the PID you will use
+   kill -TSTP 10180 # change to the correct PID
+
+   gitlab-ctl stop sidekiq
+   gitlab-ctl stop geo-logcursor
+   ```
+
+   You can watch the [Sidekiq logs](../../logs/index.md#sidekiq-logs) to know when Sidekiq jobs processing has finished:
+
+   ```shell
+   gitlab-ctl tail sidekiq
+   ```
+
+1. Rename repository storage folders and create new ones. If you are not concerned about possible orphaned directories and files, you can skip this step.
+
+   ```shell
+   mv /var/opt/gitlab/git-data/repositories /var/opt/gitlab/git-data/repositories.old
+   mkdir -p /var/opt/gitlab/git-data/repositories
+   chown git:git /var/opt/gitlab/git-data/repositories
+   ```
+
+   NOTE:
+   You may want to remove the `/var/opt/gitlab/git-data/repositories.old` in the future
+   as soon as you confirmed that you don't need it anymore, to save disk space.
+
+1. Optional. Rename other data folders and create new ones.
+
+   WARNING:
+   You may still have files on the **secondary** site that have been removed from the **primary** site, but this
+   removal has not been reflected. If you skip this step, these files are not removed from the Geo **secondary** site.
+
+   Any uploaded content (like file attachments, avatars, or LFS objects) is stored in a
+   subfolder in one of these paths:
+
+   - `/var/opt/gitlab/gitlab-rails/shared`
+   - `/var/opt/gitlab/gitlab-rails/uploads`
+
+   To rename all of them:
+
+   ```shell
+   gitlab-ctl stop
+
+   mv /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-rails/shared.old
+   mkdir -p /var/opt/gitlab/gitlab-rails/shared
+
+   mv /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/uploads.old
+   mkdir -p /var/opt/gitlab/gitlab-rails/uploads
+
+   gitlab-ctl start postgresql
+   gitlab-ctl start geo-postgresql
+   ```
+
+   Reconfigure to recreate the folders and make sure permissions and ownership
+   are correct:
+
+   ```shell
+   gitlab-ctl reconfigure
+   ```
+
+1. Reset the Tracking Database.
+
+   WARNING:
+   If you skipped the optional step 3, be sure both `geo-postgresql` and `postgresql` services are running.
+
+   ```shell
+   gitlab-rake db:drop:geo DISABLE_DATABASE_ENVIRONMENT_CHECK=1   # on a secondary app node
+   gitlab-ctl reconfigure     # on the tracking database node
+   gitlab-rake db:migrate:geo # on a secondary app node
+   ```
+
+1. Restart previously stopped services.
+
+   ```shell
+   gitlab-ctl start
+   ```
diff --git a/doc/administration/geo/replication/version_specific_upgrades.md b/doc/administration/geo/replication/version_specific_upgrades.md
index f9b96fdebbcd04a07ba2b3829f8a8c0091627737..193ef8575469359410e857f7738140942dd76447 100644
--- a/doc/administration/geo/replication/version_specific_upgrades.md
+++ b/doc/administration/geo/replication/version_specific_upgrades.md
@@ -87,10 +87,6 @@ Otherwise, for each **secondary** site, on a Rails application node, open a [Rai
 
 If you are running a version prior to 14.1 and are using Geo and multi-arch containers in your Container Registry, we recommend [upgrading](upgrading_the_geo_sites.md) to at least GitLab 14.1.
 
-### Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode
-
-GitLab 13.9 through GitLab 14.3 are affected by a bug in which enabling [GitLab Maintenance Mode](../../maintenance_mode/index.md) causes Geo secondary site statuses to appear to stop upgrading and become unhealthy. For more information, see [Troubleshooting - Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode](troubleshooting.md#geo-admin-area-shows-unhealthy-after-enabling-maintenance-mode).
-
 ## Upgrading to GitLab 14.0/14.1
 
 ### Primary sites cannot be removed from the UI
@@ -100,7 +96,3 @@ We found an issue where [Primary sites cannot be removed from the UI](https://gi
 This bug only exists in the UI and does not block the removal of Primary sites using any other method.
 
 If you are running an affected version and need to remove your Primary site, you can manually remove the Primary site by using the [Geo Sites API](../../../api/geo_nodes.md#delete-a-geo-node).
-
-### Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode
-
-GitLab 13.9 through GitLab 14.3 are affected by a bug in which enabling [GitLab Maintenance Mode](../../maintenance_mode/index.md) causes Geo secondary site statuses to appear to stop upgrading and become unhealthy. For more information, see [Troubleshooting - Geo Admin Area shows 'Unhealthy' after enabling Maintenance Mode](troubleshooting.md#geo-admin-area-shows-unhealthy-after-enabling-maintenance-mode).