From e07e0d66f7ca4df8da3e547ef82832bc537e5b97 Mon Sep 17 00:00:00 2001
From: Katrin Leinweber <kleinweber@gitlab.com>
Date: Fri, 31 Mar 2023 11:08:11 +0000
Subject: [PATCH] Add troubleshooting docs for project migrations

---
 doc/administration/logs/index.md       |  4 +++-
 doc/administration/logs/log_parsing.md | 15 +++++++++++++--
 doc/user/project/import/index.md       | 11 +++++++++++
 3 files changed, 27 insertions(+), 3 deletions(-)

diff --git a/doc/administration/logs/index.md b/doc/administration/logs/index.md
index 1a2fa7bbafa67..c03971ab4c1a7 100644
--- a/doc/administration/logs/index.md
+++ b/doc/administration/logs/index.md
@@ -725,7 +725,7 @@ Depending on your installation method, this file is located at:
 - Omnibus GitLab: `/var/log/gitlab/gitlab-rails/importer.log`
 - Installations from source: `/home/git/gitlab/log/importer.log`
 
-It logs the progress of the import process.
+This file logs the progress of [project imports and migrations](../../user/project/import/index.md).
 
 ## `exporter.log`
 
@@ -821,6 +821,8 @@ Depending on your installation method, this file is located at:
 - Omnibus GitLab: `/var/log/gitlab/gitlab-rails/migrations.log`
 - Installations from source: `/home/git/gitlab/log/migrations.log`
 
+This file logs the progress of [database migrations](../raketasks/maintenance.md#display-status-of-database-migrations).
+
 ## `mail_room_json.log` (default)
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19186) in GitLab 12.6.
diff --git a/doc/administration/logs/log_parsing.md b/doc/administration/logs/log_parsing.md
index 84c517e6120c4..40d6059d2460d 100644
--- a/doc/administration/logs/log_parsing.md
+++ b/doc/administration/logs/log_parsing.md
@@ -158,7 +158,7 @@ CT: 297  ROUTE: /api/:version/projects/:id/repository/tags       DURS: 731.39,
 CT: 190  ROUTE: /api/:version/projects/:id/repository/commits    DURS: 1079.02,  979.68,  958.21
 ```
 
-### Print top API user agents
+#### Print top API user agents
 
 ```shell
 jq --raw-output '[.route, .ua] | @tsv' api_json.log | sort | uniq -c | sort -n
@@ -180,9 +180,20 @@ if the output contains many:
 
 You can also [use `fast-stats top`](#parsing-gitlab-logs-with-jq) to extract performance statistics.
 
+### Parsing `gitlab-rails/importer.log`
+
+To troubleshoot [project imports](../../administration/raketasks/project_import_export.md) or
+[migrations](../../user/project/import/index.md), run this command:
+
+```shell
+jq 'select(.project_path == "<namespace>/<project>").error_messages' importer.log
+```
+
+For common issues, see [troubleshooting](../../administration/raketasks/project_import_export.md#troubleshooting).
+
 ### Parsing `gitlab-workhorse/current`
 
-### Print top Workhorse user agents
+#### Print top Workhorse user agents
 
 ```shell
 jq --raw-output '[.uri, .user_agent] | @tsv' current | sort | uniq -c | sort -n
diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md
index 41ac535465612..f0d75895e6e41 100644
--- a/doc/user/project/import/index.md
+++ b/doc/user/project/import/index.md
@@ -172,3 +172,14 @@ For more information, see:
   including settings that need checking afterwards and other limitations.
 
 For support, customers must enter into a paid engagement with GitLab Professional Services.
+
+## Troubleshooting
+
+### Imported repository is missing branches
+
+If an imported repository does not contain all branches of the source repository:
+
+1. Set the [environment variable](../../../administration/logs/index.md#override-default-log-level) `IMPORT_DEBUG=true`.
+1. Retry the import with a [different group, subgroup, or project name](https://about.gitlab.com/releases/2023/02/22/gitlab-15-9-released/#re-import-projects-from-external-providers).
+1. If some branches are still missing, inspect [`importer.log`](../../../administration/logs/index.md#importerlog)
+   (for example, with [`jq`](../../../administration/logs/log_parsing.md#parsing-gitlab-railsimporterlog)).
-- 
GitLab