Merge branch 'jyavorska-master-patch-88152' into 'master'

Enhance CI troubleshooting guide

Closes #232464

See merge request gitlab-org/gitlab!39070

doc/.vale/gitlab/spelling-exceptions.txt

@@ -403,6 +403,7 @@ sanitization
 sbt
 scatterplot
 scatterplots
+Schemastore
 Sendmail
 Sentry
 serializer

doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md

@@ -127,5 +127,5 @@ unexpected timing. For example, when a source or target branch is advanced.
 In this case, the pipeline fails because of `fatal: reference is not a tree:` error,
 which indicates that the checkout-SHA is not found in the merge ref.
 
-This behavior was improved at GitLab 12.4 by introducing [Persistent pipeline refs](../../pipelines/index.md#troubleshooting-fatal-reference-is-not-a-tree).
+This behavior was improved at GitLab 12.4 by introducing [Persistent pipeline refs](../../troubleshooting.md#fatal-reference-is-not-a-tree-error).
 You should be able to create pipelines at any timings without concerning the error.

doc/ci/pipelines/index.md

@@ -535,32 +535,3 @@ GitLab provides API endpoints to:
 - Trigger pipeline runs. For more information, see:
   - [Triggering pipelines through the API](../triggers/README.md).
   - [Pipeline triggers API](../../api/pipeline_triggers.md).
-
-## Troubleshooting `fatal: reference is not a tree:`
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17043) in GitLab 12.4.
-
-Previously, you'd have encountered unexpected pipeline failures when you force-pushed
-a branch to its remote repository. To illustrate the problem, suppose you've had the current workflow:
-
-1. A user creates a feature branch named `example` and pushes it to a remote repository.
-1. A new pipeline starts running on the `example` branch.
-1. A user rebases the `example` branch on the latest `master` branch and force-pushes it to its remote repository.
-1. A new pipeline starts running on the `example` branch again, however,
-   the previous pipeline (2) fails because of `fatal: reference is not a tree:` error.
-
-This is because the previous pipeline cannot find a checkout-SHA (which associated with the pipeline record)
-from the `example` branch that the commit history has already been overwritten by the force-push.
-Similarly, [Pipelines for merged results](../merge_request_pipelines/pipelines_for_merged_results/index.md)
-might have failed intermittently due to [the same reason](../merge_request_pipelines/pipelines_for_merged_results/index.md#intermittently-pipelines-fail-by-fatal-reference-is-not-a-tree-error).
-
-As of GitLab 12.4, we've improved this behavior by persisting pipeline refs exclusively.
-To illustrate its life cycle:
-
-1. A pipeline is created on a feature branch named `example`.
-1. A persistent pipeline ref is created at `refs/pipelines/<pipeline-id>`,
-   which retains the checkout-SHA of the associated pipeline record.
-   This persistent ref stays intact during the pipeline execution,
-   even if the commit history of the `example` branch has been overwritten by force-push.
-1. The runner fetches the persistent pipeline ref and gets source code from the checkout-SHA.
-1. When the pipeline finished, its persistent ref is cleaned up in a background process.

doc/user/project/repository/reducing_the_repo_size_using_git.md

@@ -35,7 +35,7 @@ other internal references (refs) that are automatically created by GitLab. These
 
 - `refs/merge-requests/*` for merge requests.
 - `refs/pipelines/*` for
-  [pipelines](../../../ci/pipelines/index.md#troubleshooting-fatal-reference-is-not-a-tree).
+  [pipelines](../../../ci/troubleshooting.md#fatal-reference-is-not-a-tree-error).
 - `refs/environments/*` for environments.
 
 Git doesn't usually download these refs to make cloning and fetch faster, but we can use the `--mirror` option to