Merge branch '22348-gitea-importer-docs' into 'master'

Add doc for the Gitea importer

This adds documentation for !8116. It's mostly a copy/paste of the GitHub import documentation without the OAuth parts since Gitea is not yet an OAuth provider.

Part of #22348.

See merge request !8139

4 files changed, 85 insertions, 5 deletions

diff --git a/doc/workflow/importing/README.md b/doc/workflow/importing/README.md
index 18e5d950866..2d91bee0e94 100644
--- a/doc/workflow/importing/README.md
+++ b/doc/workflow/importing/README.md
@@ -4,6 +4,7 @@
 1. [GitHub](import_projects_from_github.md)

 1. [GitLab.com](import_projects_from_gitlab_com.md)

 1. [FogBugz](import_projects_from_fogbugz.md)

+1. [Gitea](import_projects_from_gitea.md)

 1. [SVN](migrating_from_svn.md)

 

 In addition to the specific migration documentation above, you can import any

@@ -14,4 +15,3 @@ repository is too large the import can timeout.
 

 You can copy your repos by changing the remote and pushing to the new server;

 but issues and merge requests can't be imported.

-

diff --git a/doc/workflow/importing/img/import_projects_from_gitea_new_import.png b/doc/workflow/importing/img/import_projects_from_gitea_new_import.png
new file mode 100644
index 00000000000..a3f603cbd0a
--- /dev/null
+++ b/doc/workflow/importing/img/import_projects_from_gitea_new_import.png
diff --git a/doc/workflow/importing/import_projects_from_gitea.md b/doc/workflow/importing/import_projects_from_gitea.md
new file mode 100644
index 00000000000..936cee89f45
--- /dev/null
+++ b/doc/workflow/importing/import_projects_from_gitea.md
@@ -0,0 +1,80 @@
+# Import your project from Gitea to GitLab
+
+Import your projects from Gitea to GitLab with minimal effort.
+
+## Overview
+
+>**Note:**
+As of Gitea `v1.0.0`, issue & pull-request comments cannot be imported! This is
+a [known issue][issue-401] that should be fixed in a near-future.
+
+- At its current state, Gitea importer can import:
+  - the repository description (GitLab 8.15+)
+  - the Git repository data (GitLab 8.15+)
+  - the issues (GitLab 8.15+)
+  - the pull requests (GitLab 8.15+)
+  - the milestones (GitLab 8.15+)
+  - the labels (GitLab 8.15+)
+- Repository public access is retained. If a repository is private in Gitea
+  it will be created as private in GitLab as well.
+
+## How it works
+
+Since Gitea is currently not an OAuth provider, author/assignee cannot be mapped
+to users in your GitLab's instance. This means that the project creator (most of
+the times the current user that started the import process) is set as the author,
+but a reference on the issue about the original Gitea author is kept.
+
+The importer will create any new namespaces (groups) if they don't exist or in
+the case the namespace is taken, the repository will be imported under the user's
+namespace that started the import process.
+
+## Importing your Gitea repositories
+
+The importer page is visible when you create a new project.
+
+![New project page on GitLab](img/import_projects_from_new_project_page.png)
+
+Click on the **Gitea** link and the import authorization process will start.
+
+![New Gitea project import](img/import_projects_from_gitea_new_import.png)
+
+### Authorize access to your repositories using a personal access token
+
+With this method, you will perform a one-off authorization with Gitea to grant
+GitLab access your repositories:
+
+1. Go to <https://you-gitea-instance/user/settings/applications> (replace
+   `you-gitea-instance` with the host of your Gitea instance).
+1. Click **Generate New Token**.
+1. Enter a token description.
+1. Click **Generate Token**.
+1. Copy the token hash.
+1. Go back to GitLab and provide the token to the Gitea importer.
+1. Hit the **List Your Gitea Repositories** button and wait while GitLab reads
+   your repositories' information. Once done, you'll be taken to the importer
+   page to select the repositories to import.
+
+### Select which repositories to import
+
+After you've authorized access to your Gitea repositories, you will be
+redirected to the Gitea importer page.
+
+From there, you can see the import statuses of your Gitea repositories.
+
+- Those that are being imported will show a _started_ status,
+- those already successfully imported will be green with a _done_ status,
+- whereas those that are not yet imported will have an **Import** button on the
+  right side of the table.
+
+If you want, you can import all your Gitea projects in one go by hitting
+**Import all projects** in the upper left corner.
+
+![Gitea importer page](img/import_projects_from_github_importer.png)
+
+---
+
+You can also choose a different name for the project and a different namespace,
+if you have the privileges to do so.
+
+[issue-401]: https://github.com/go-gitea/gitea/issues/401
diff --git a/doc/workflow/importing/import_projects_from_github.md b/doc/workflow/importing/import_projects_from_github.md
index b3660aa8030..86a016fc6d6 100644
--- a/doc/workflow/importing/import_projects_from_github.md
+++ b/doc/workflow/importing/import_projects_from_github.md
@@ -6,8 +6,9 @@ Import your projects from GitHub to GitLab with minimal effort.
 

 >**Note:**

 If you are an administrator you can enable the [GitHub integration][gh-import]

-in your GitLab instance sitewide. This configuration is optional, users will be

-able import their GitHub repositories with a [personal access token][gh-token].

+in your GitLab instance sitewide. This configuration is optional, users will

+still be able to import their GitHub repositories with a

+[personal access token][gh-token].

 

 - At its current state, GitHub importer can import:

   - the repository description (GitLab 7.7+)

@@ -85,7 +86,7 @@ authorization with GitHub to grant GitLab access your repositories:
 1. Click **Generate token**.

 1. Copy the token hash.

 1. Go back to GitLab and provide the token to the GitHub importer.

-1. Hit the **List your GitHub repositories** button and wait while GitLab reads

+1. Hit the **List Your GitHub Repositories** button and wait while GitLab reads

    your repositories' information. Once done, you'll be taken to the importer

    page to select the repositories to import.

 

@@ -112,7 +113,6 @@ You can also choose a different name for the project and a different namespace,
 if you have the privileges to do so.

 

 [gh-import]: ../../integration/github.md "GitHub integration"

-[new-project]: ../../gitlab-basics/create-project.md "How to create a new project in GitLab"

 [gh-integration]: #authorize-access-to-your-repositories-using-the-github-integration

 [gh-token]: #authorize-access-to-your-repositories-using-a-personal-access-token

 [social sign-in]: ../../profile/account/social_sign_in.md