diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-05-19 18:44:42 +0300 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-05-19 18:44:42 +0300 |
| commit | 4555e1b21c365ed8303ffb7a3325d773c9b8bf31 (patch) | |
| tree | 5423a1c7516cffe36384133ade12572cf709398d /doc/user/project/import | |
| parent | e570267f2f6b326480d284e0164a6464ba4081bc (diff) | |
Add latest changes from gitlab-org/gitlab@13-12-stable-eev13.12.0-rc42
Diffstat (limited to 'doc/user/project/import')
20 files changed, 211 insertions, 318 deletions
diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md index 6f274dd12a2..e77932c6427 100644 --- a/doc/user/project/import/bitbucket.md +++ b/doc/user/project/import/bitbucket.md @@ -14,26 +14,27 @@ Server (aka Stash). If you are trying to import projects from Bitbucket Server, Import your projects from Bitbucket Cloud to GitLab with minimal effort. -## Overview - -- At its current state, the Bitbucket importer can import: - - the repository description (GitLab 7.7+) - - the Git repository data (GitLab 7.7+) - - the issues (GitLab 7.7+) - - the issue comments (GitLab 8.15+) - - the pull requests (GitLab 8.4+) - - the pull request comments (GitLab 8.15+) - - the milestones (GitLab 8.15+) - - the wiki (GitLab 8.15+) -- References to pull requests and issues are preserved (GitLab 8.7+) -- Repository public access is retained. If a repository is private in Bitbucket - it will be created as private in GitLab as well. +The Bitbucket importer can import: + +- Repository description (GitLab 7.7+) +- Git repository data (GitLab 7.7+) +- Issues (GitLab 7.7+) +- Issue comments (GitLab 8.15+) +- Pull requests (GitLab 8.4+) +- Pull request comments (GitLab 8.15+) +- Milestones (GitLab 8.15+) +- Wiki (GitLab 8.15+) + +When importing: + +- References to pull requests and issues are preserved (GitLab 8.7+). +- Repository public access is retained. If a repository is private in Bitbucket, it's created as + private in GitLab as well. ## Requirements -The [Bitbucket Cloud integration](../../../integration/bitbucket.md) must be first enabled in order to be -able to import your projects from Bitbucket Cloud. Ask your GitLab administrator -to enable this if not already. +To import your projects from Bitbucket Cloud, the [Bitbucket Cloud integration](../../../integration/bitbucket.md) +must be enabled. Ask your GitLab administrator to enable this if it isn't already enabled. ## How it works diff --git a/doc/user/project/import/bitbucket_server.md b/doc/user/project/import/bitbucket_server.md index bb2256c9464..1e79107d76f 100644 --- a/doc/user/project/import/bitbucket_server.md +++ b/doc/user/project/import/bitbucket_server.md @@ -15,51 +15,49 @@ Use the [Bitbucket Cloud importer](bitbucket.md) for that. Import your projects from Bitbucket Server to GitLab with minimal effort. -## Overview +The Bitbucket importer can import: -- In its current state, the Bitbucket importer can import: - - the repository description (GitLab 11.2+) - - the Git repository data (GitLab 11.2+) - - the pull requests (GitLab 11.2+) - - the pull request comments (GitLab 11.2+) -- Repository public access is retained. If a repository is private in Bitbucket - it will be created as private in GitLab as well. +- Repository description (GitLab 11.2+) +- Git repository data (GitLab 11.2+) +- Pull requests (GitLab 11.2+) +- Pull request comments (GitLab 11.2+) + +When importing, repository public access is retained. If a repository is private in Bitbucket, it's +created as private in GitLab as well. ## Limitations -1. Currently GitLab doesn't allow comments on arbitrary lines of code, so any - Bitbucket comments out of bounds will be inserted as comments in the merge - request. -1. Bitbucket Server allows multiple levels of threading. GitLab import - will collapse this into one thread and quote part of the original comment. -1. Declined pull requests have unreachable commits, which prevents the GitLab - importer from generating a proper diff. These pull requests will show up as - empty changes. -1. Attachments in Markdown are currently not imported. -1. Task lists are not imported. -1. Emoji reactions are not imported -1. Project filtering does not support fuzzy search (only `starts with` or `full - match strings` are currently supported) +- GitLab doesn't allow comments on arbitrary lines of code, so any Bitbucket comments out of bounds + are inserted as comments in the merge request. +- Bitbucket Server allows multiple levels of threading. GitLab import collapses this into one thread + and quote part of the original comment. +- Declined pull requests have unreachable commits, which prevents the GitLab importer from + generating a proper diff. These pull requests show up as empty changes. +- Attachments in Markdown are not imported. +- Task lists are not imported. +- Emoji reactions are not imported. +- Project filtering does not support fuzzy search (only `starts with` or `full match strings` are + supported). ## How it works The Bitbucket Server importer works as follows: -1. The user will be prompted to enter the URL, username, and password (or personal access token) to log in to Bitbucket. +1. The user is prompted to enter the URL, username, and password (or personal access token) to log in to Bitbucket. These credentials are preserved only as long as the importer is running. -1. The importer will attempt to list all the current repositories on the Bitbucket Server. -1. Upon selection, the importer will clone the repository and import pull requests and comments. +1. The importer attempts to list all the current repositories on the Bitbucket Server. +1. Upon selection, the importer clones the repository and import pull requests and comments. ### User assignment When issues/pull requests are being imported, the Bitbucket importer tries to find the author's e-mail address with a confirmed e-mail address in the GitLab user database. If no such user is available, the project creator is set as -the author. The importer will append a note in the comment to mark the original +the author. The importer appends a note in the comment to mark the original creator. -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 +The importer creates any new namespaces (groups) if they don't exist or in +the case the namespace is taken, the repository is imported under the user's namespace that started the import process. #### User assignment by username @@ -104,7 +102,7 @@ To disable it: Feature.disable(:bitbucket_server_user_mapping_by_username) ``` -## Importing your Bitbucket repositories +## Import your Bitbucket repositories 1. Sign in to GitLab and go to your dashboard. 1. Click on **New project**. @@ -118,7 +116,7 @@ Feature.disable(:bitbucket_server_user_mapping_by_username)  1. Click on the projects that you'd like to import or **Import all projects**. - You can also filter projects by name and select the namespace under which each project will be + You can also filter projects by name and select the namespace under which each project is imported.  diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md index 1371ca57bc9..09505d94a8c 100644 --- a/doc/user/project/import/fogbugz.md +++ b/doc/user/project/import/fogbugz.md @@ -8,12 +8,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Import your project from FogBugz to GitLab It only takes a few simple steps to import your project from FogBugz. -The importer will import all of your cases and comments with original case -numbers and timestamps. You will also have the opportunity to map FogBugz -users to GitLab users. +The importer imports all your cases and comments with original case +numbers and timestamps. You can also map FogBugz users to GitLab users. -1. From your GitLab dashboard click 'New project' -1. Click on the 'FogBugz' button +Follow these steps to import your project from FogBugz: + +1. From your GitLab dashboard, select **New project**. + +1. Select the **FogBugz** button.  @@ -25,11 +27,11 @@ users to GitLab users.  -1. Select the projects you wish to import by clicking the Import buttons +1. Select the projects you wish to import by selecting the **Import** buttons.  -1. Once the import has finished click the link to take you to the project +1. Once the import finishes, click the link to go to the project dashboard. Follow the directions to push your existing repository.  diff --git a/doc/user/project/import/gemnasium.md b/doc/user/project/import/gemnasium.md index bac10cb0948..5a4b16d57f5 100644 --- a/doc/user/project/import/gemnasium.md +++ b/doc/user/project/import/gemnasium.md @@ -1,117 +1,8 @@ --- -type: reference, howto -stage: Manage -group: Import -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +redirect_to: 'index.md' --- -# Gemnasium **(ULTIMATE)** +This document was deleted. -This guide describes how to migrate from Gemnasium.com to your own GitLab -instance or GitLab.com. - -## Why is Gemnasium.com closed? - -Gemnasium was [acquired by GitLab](https://about.gitlab.com/press/releases/2018-01-30-gemnasium-acquisition.html) -in January 2018. Since May 15, 2018, the services provided by Gemnasium are no longer available. -The team behind Gemnasium has joined GitLab as the new Security Products team -and is working on a [wide range of tools](../../application_security/index.md), -including: - -- [Dependency Scanning](../../application_security/dependency_scanning/index.md) -- [SAST](../../application_security/sast/index.md) -- [DAST](../../application_security/dast/index.md) -- [Container Scanning](../../application_security/container_scanning/index.md) - -If you want to continue monitoring your dependencies, see the -[Migrating to GitLab](#migrating-to-gitlab) section below. - -## What happened to my account? - -Your account has been automatically closed on May 15th, 2018. If you had a paid -subscription at that time, your card will be refunded on a -<!-- vale gitlab.Spelling = NO --> pro rata temporis <!-- vale gitlab.Spelling = YES --> basis. -You may contact `gemnasium@gitlab.com` regarding your closed account. - -## Will my account/data be transferred to GitLab Inc.? - -All accounts and data have been deleted on May 15th, 2018. GitLab Inc. -doesn't know anything about your private data, nor your projects, and therefore -if they were vulnerable or not. GitLab Inc. takes personal information very seriously. - -## What happened to my badge? - -To avoid broken 404 images, all badges pointing to Gemnasium.com will be a -placeholder, inviting you to migrate to GitLab (and pointing to this page). - -## Migrating to GitLab - -Gemnasium has been ported and integrated directly into GitLab CI/CD. -You can still benefit from our dependency monitoring features, and it requires -some steps to migrate your projects. There is no automatic import since GitLab -doesn't know anything about any projects which existed on Gemnasium.com. -Security features are free for public (open-source) projects hosted on GitLab.com. - -### If your project is hosted on GitLab (`https://gitlab.com` / self-managed) - -You're almost set! If you're already using -[Auto DevOps](../../../topics/autodevops/), you are already covered. -Otherwise, you must configure your `.gitlab-ci.yml` according to the -[dependency scanning page](../../application_security/dependency_scanning/index.md). - -### If your project is hosted on GitHub (`https://github.com` / GitHub Enterprise) - -Since [GitLab 10.6 comes with GitHub integration](https://about.gitlab.com/solutions/github/), -GitLab users can now create a CI/CD project in GitLab connected to an external -GitHub.com or GitHub Enterprise repository. This will automatically prompt -GitLab CI/CD to run whenever code is pushed to GitHub and post CI/CD results -back to both GitLab and GitHub when completed. - -<!-- vale gitlab.Spelling = NO --> - -1. Create a new project, and select **CI/CD for external repo**: - -  - <!-- vale gitlab.Spelling = YES --> - -1. Use the **GitHub** button to connect your repositories. - -  - -1. Select the project(s) to be set up with GitLab CI/CD and choose **Connect**. - -  - - After the configuration is done, you may click on your new - project on GitLab. - -  - - Your project is now mirrored on GitLab, where the runners will be able to access - your source code and run your tests. - - Optional step: If you set this up on GitLab.com, make sure the project is - public (in the project settings) if your GitHub project is public, since - the security feature is available only for [GitLab Ultimate](https://about.gitlab.com/pricing/). - -1. To set up the dependency scanning job, corresponding to what Gemnasium was - doing, you must create a `.gitlab-ci.yml` file, or update it according to - the [dependency scanning docs](../../application_security/dependency_scanning/index.md). - The mirroring is pull-only by default, so you may create or update the file on - GitHub: - -  - -1. Once your file has been committed, a new pipeline will be automatically - triggered if your file is valid: - -  - -1. The result of the job will be visible directly from the pipeline view: - -  - -NOTE: -If you don't commit very often to your project, you may want to use -[scheduled pipelines](../../../ci/pipelines/schedules.md) to run the job on a regular -basis. +<!-- This redirect file can be deleted after <2021-08-15>. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
\ No newline at end of file diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md index 26e5a86b808..41141902468 100644 --- a/doc/user/project/import/gitea.md +++ b/doc/user/project/import/gitea.md @@ -9,20 +9,20 @@ info: To determine the technical writer assigned to the Stage/Group associated w Import your projects from Gitea to GitLab with minimal effort. -## Overview - NOTE: This requires Gitea `v1.0.0` or newer. -- 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. +The Gitea importer can import: + +- Repository description (GitLab 8.15+) +- Git repository data (GitLab 8.15+) +- Issues (GitLab 8.15+) +- Pull requests (GitLab 8.15+) +- Milestones (GitLab 8.15+) +- Labels (GitLab 8.15+) + +When importing, repository public access is retained. If a repository is private in Gitea, it's +created as private in GitLab as well. ## How it works @@ -31,23 +31,23 @@ to users in your GitLab 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 +The importer creates any new namespaces (groups) if they don't exist or in +the case the namespace is taken, the repository is imported under the user's namespace that started the import process. -## Importing your Gitea repositories +## Import your Gitea repositories The importer page is visible when you create a new project.  -Click on the **Gitea** link and the import authorization process will start. +Click the **Gitea** link and the import authorization process starts.  ### Authorize access to your repositories using a personal access token -With this method, you will perform a one-off authorization with Gitea to grant +With this method, you perform a one-off authorization with Gitea to grant GitLab access your repositories: 1. Go to `https://your-gitea-instance/user/settings/applications` (replace @@ -58,27 +58,27 @@ GitLab access your repositories: 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 + your repositories' information. Once done, you are 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 +After you've authorized access to your Gitea repositories, you are 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 +- Those that are being imported show a _started_ status, +- those already successfully imported are green with a _done_ status, +- whereas those that are not yet imported have an **Import** button on the right side of the table. You also can: - Import all your Gitea projects in one go by hitting **Import all projects** in - the upper left corner + the upper left corner. - Filter projects by name. If filter is applied, hitting **Import all projects** - will only import matched projects + only imports matched projects.  diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index eb426a9f126..c8b973b673e 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -10,8 +10,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w Using the importer, you can import your GitHub repositories to GitLab.com or to your self-managed GitLab instance. -## Overview - The following aspects of a project are imported: - Repository description (GitLab.com & 7.7+) @@ -37,12 +35,12 @@ The namespace is a user or group in GitLab, such as `gitlab.com/janedoe` or `git This process does not migrate or import any types of groups or organizations from GitHub to GitLab. -### Use cases +## Use cases The steps you take depend on whether you are importing from GitHub.com or GitHub Enterprise, as well as whether you are importing to GitLab.com or self-managed GitLab instance. - If you're importing to GitLab.com, you can alternatively import GitHub repositories - using a [personal access token](#using-a-github-token). We do not recommend + using a [personal access token](#use-a-github-token). We do not recommend this method, as it does not associate all user activity (such as issues and pull requests) with matching GitLab users. - If you're importing to a self-managed GitLab instance, you can alternatively use the @@ -62,9 +60,16 @@ For this association to succeed, each GitHub author and assignee in the reposito must meet one of the following conditions prior to the import: - Have previously logged in to a GitLab account using the GitHub icon. -- Have a GitHub account with a publicly visible - [primary email address](https://docs.github.com/en/rest/reference/users#get-a-user) - on their profile that matches their GitLab account's primary or secondary email address. +- Have a GitHub account with a [public-facing email address](https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/setting-your-commit-email-address) + that matches their GitLab account's email address. + + NOTE: + GitLab content imports that use GitHub accounts require that the GitHub public-facing + email address is populated so that all comments and contributions are properly mapped + to the same user in GitLab. GitHub Enterprise (on premise) does not require this field + to be populated to use the product, so you may need to add it on existing GitHub Enterprise + accounts for imported content to be properly mapped to the user in the new system. + Refer to GitHub documentation for instructions on how to add that address. If a user referenced in the project is not found in the GitLab database, the project creator (typically the user that initiated the import process) is set as the author/assignee, but a note on the issue mentioning the original @@ -86,7 +91,7 @@ For an overview of the import process, see the video [Migrating from GitHub to G ## Import your GitHub repository into GitLab -### Using the GitHub integration +### Use the GitHub integration Before you begin, ensure that any GitHub users who you want to map to GitLab users have either: @@ -105,9 +110,9 @@ If you are using a self-managed GitLab instance or if you are importing from Git 1. Select the **Import project** tab and then select **GitHub**. 1. Select the first button to **List your GitHub repositories**. You are redirected to a page on [GitHub](https://github.com) to authorize the GitLab application. 1. Click **Authorize GitlabHQ**. You are redirected back to the GitLab Import page and all of your GitHub repositories are listed. -1. Continue on to [selecting which repositories to import](#selecting-which-repositories-to-import). +1. Continue on to [selecting which repositories to import](#select-which-repositories-to-import). -### Using a GitHub token +### Use a GitHub token NOTE: Using a personal access token to import projects is not recommended. If you are a GitLab.com user, @@ -115,7 +120,7 @@ you can use a personal access token to import your project from GitHub, but this associate all user activity (such as issues and pull requests) with matching GitLab users. If you are an administrator of a self-managed GitLab instance or if you are importing from GitHub Enterprise, you cannot use a personal access token. -The [GitHub integration method (above)](#using-the-github-integration) is recommended for all users. +The [GitHub integration method (above)](#use-the-github-integration) is recommended for all users. Read more in the [How it works](#how-it-works) section. If you are not using the GitHub integration, you can still perform an authorization with GitHub to grant GitLab access your repositories: @@ -129,7 +134,7 @@ If you are not using the GitHub integration, you can still perform an authorizat 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. -### Selecting which repositories to import +### Select which repositories to import After you have authorized access to your GitHub repositories, you are redirected to the GitHub importer page and your GitHub repositories are listed. @@ -155,7 +160,7 @@ Additionally, you can configure GitLab to send pipeline status updates back GitH If you import your project using [CI/CD for external repository](../../../ci/ci_cd_for_external_repos/index.md), then both of the above are automatically configured. **(PREMIUM)** -## Improving the speed of imports on self-managed instances +## Improve the speed of imports on self-managed instances NOTE: Administrator access to the GitLab server is required. diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index add457c217e..9e63b1cb617 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -19,10 +19,10 @@ you'll need to follow the instructions for [exporting a project](../settings/imp  -Go to the **Import Projects** tab, then click on **GitLab.com**, and you will be redirected to GitLab.com -for permission to access your projects. After accepting, you'll be automatically redirected to the importer. +Go to the **Import Projects** tab, then click on **GitLab.com**, and you are redirected to GitLab.com +for permission to access your projects. After accepting, you are automatically redirected to the importer.  -To import a project, click "Import". The importer will import your repository and issues. -Once the importer is done, a new GitLab project will be created with your imported data. +To import a project, click "Import". The importer imports your repository and issues. +Once the importer is done, a new GitLab project is created with your imported data. diff --git a/doc/user/project/import/img/gemnasium/connect_github_v13_5.png b/doc/user/project/import/img/gemnasium/connect_github_v13_5.png Binary files differdeleted file mode 100644 index 575d257a213..00000000000 --- a/doc/user/project/import/img/gemnasium/connect_github_v13_5.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/create_project_v13_5.png b/doc/user/project/import/img/gemnasium/create_project_v13_5.png Binary files differdeleted file mode 100644 index 37467bc3fed..00000000000 --- a/doc/user/project/import/img/gemnasium/create_project_v13_5.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/edit_gitlab-ci.png b/doc/user/project/import/img/gemnasium/edit_gitlab-ci.png Binary files differdeleted file mode 100644 index 8336c803b83..00000000000 --- a/doc/user/project/import/img/gemnasium/edit_gitlab-ci.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/pipeline.png b/doc/user/project/import/img/gemnasium/pipeline.png Binary files differdeleted file mode 100644 index ae4d5295ffa..00000000000 --- a/doc/user/project/import/img/gemnasium/pipeline.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/project_connected.png b/doc/user/project/import/img/gemnasium/project_connected.png Binary files differdeleted file mode 100644 index 332d2230ef8..00000000000 --- a/doc/user/project/import/img/gemnasium/project_connected.png +++ /dev/null diff --git a/doc/user/project/import/img/gemnasium/select_project_v13_5.png b/doc/user/project/import/img/gemnasium/select_project_v13_5.png Binary files differdeleted file mode 100644 index 30575954811..00000000000 --- a/doc/user/project/import/img/gemnasium/select_project_v13_5.png +++ /dev/null diff --git a/doc/user/project/import/img/jira/import_issues_from_jira_form_v13_2.png b/doc/user/project/import/img/jira/import_issues_from_jira_form_v13_2.png Binary files differindex 8a94d33d47b..dca60b2bc5c 100644 --- a/doc/user/project/import/img/jira/import_issues_from_jira_form_v13_2.png +++ b/doc/user/project/import/img/jira/import_issues_from_jira_form_v13_2.png diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index f6ed53763dd..3728a486070 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -5,50 +5,52 @@ group: Import info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments --- -# Migrating projects to a GitLab instance - -1. [From Bitbucket Cloud](bitbucket.md) -1. [From Bitbucket Server (also known as Stash)](bitbucket_server.md) -1. [From ClearCase](clearcase.md) -1. [From CVS](cvs.md) -1. [From FogBugz](fogbugz.md) -1. [From GitHub.com or GitHub Enterprise](github.md) -1. [From GitLab.com](gitlab_com.md) -1. [From Gitea](gitea.md) -1. [From Perforce](perforce.md) -1. [From SVN](svn.md) -1. [From TFVC](tfvc.md) -1. [From repository by URL](repo_by_url.md) -1. [By uploading a manifest file (AOSP)](manifest.md) -1. [From Gemnasium](gemnasium.md) -1. [From Phabricator](phabricator.md) -1. [From Jira (issues only)](jira.md) - -In addition to the specific migration documentation above, you can import any -Git repository via HTTP from the New Project page. Be aware that if the -repository is too large the import can timeout. - -There is also the option of [connecting your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)** +# Migrate projects to a GitLab instance + +See these documents to migrate to GitLab: + +- [From Bitbucket Cloud](bitbucket.md) +- [From Bitbucket Server (also known as Stash)](bitbucket_server.md) +- [From ClearCase](clearcase.md) +- [From CVS](cvs.md) +- [From FogBugz](fogbugz.md) +- [From GitHub.com or GitHub Enterprise](github.md) +- [From GitLab.com](gitlab_com.md) +- [From Gitea](gitea.md) +- [From Perforce](perforce.md) +- [From SVN](svn.md) +- [From TFVC](tfvc.md) +- [From repository by URL](repo_by_url.md) +- [By uploading a manifest file (AOSP)](manifest.md) +- [From Phabricator](phabricator.md) +- [From Jira (issues only)](jira.md) + +You can also import any Git repository through HTTP from the **New Project** page. Note that if the +repository is too large, the import can timeout. + +You can also [connect your external repository to get CI/CD benefits](../../../ci/ci_cd_for_external_repos/index.md). **(PREMIUM)** ## LFS authentication When importing a project that contains LFS objects, if the project has an [`.lfsconfig`](https://github.com/git-lfs/git-lfs/blob/master/docs/man/git-lfs-config.5.ronn) file with a URL host (`lfs.url`) different from the repository URL host, LFS files are not downloaded. -## Migrating from self-managed GitLab to GitLab.com +## Migrate from self-managed GitLab to GitLab.com -If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md). Issues and merge requests can't be imported. - -If you want to retain all metadata like issues and merge requests, you can use -the [import/export feature](../settings/import_export.md) to export projects from self-managed GitLab and import those projects into GitLab.com. - -All GitLab user associations (such as comment author) will be changed to the user importing the project. For more information, please see [the import notes](../settings/import_export.md#important-notes). - -If you need to migrate all data over, you can leverage our [API](../../../api/README.md) to migrate from self-managed to GitLab.com. -The order of assets to migrate from a self-managed instance to GitLab.com is the following: +If you only need to migrate Git repositories, you can [import each project by URL](repo_by_url.md). +However, you can't import issues and merge requests this way. To retain all metadata like issues and +merge requests, use the [import/export feature](../settings/import_export.md) +to export projects from self-managed GitLab and import those projects into GitLab.com. All GitLab +user associations (such as comment author) are changed to the user importing the project. For more +information, see [the import notes](../settings/import_export.md#important-notes). NOTE: -When migrating to GitLab.com, users would need to be manually created unless [SCIM](../../../user/group/saml_sso/scim_setup.md) is going to be used. Creating users with the API is limited to self-managed instances as it requires administrator access. +When migrating to GitLab.com, you must create users manually unless [SCIM](../../../user/group/saml_sso/scim_setup.md) +will be used. Creating users with the API is limited to self-managed instances as it requires +administrator access. + +To migrate all data from self-managed to GitLab.com, you can leverage the [API](../../../api/README.md). +Migrate the assets in this order: 1. [Groups](../../../api/groups.md) 1. [Projects](../../../api/projects.md) @@ -56,43 +58,43 @@ When migrating to GitLab.com, users would need to be manually created unless [SC Keep in mind the limitations of the [import/export feature](../settings/import_export.md#exported-contents). -You will still need to migrate your Container Registry over a series of -Docker pulls and pushes and re-run any CI pipelines to retrieve any build artifacts. +You must still migrate your [Container Registry](../../packages/container_registry/) +over a series of Docker pulls and pushes. Re-run any CI pipelines to retrieve any build artifacts. -## Migrating from GitLab.com to self-managed GitLab +## Migrate from GitLab.com to self-managed GitLab -The process is essentially the same as for [migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). The main difference is that users can be created on the self-managed GitLab instance by an administrator through the UI or the [users API](../../../api/users.md#user-creation). +The process is essentially the same as [migrating from self-managed GitLab to GitLab.com](#migrate-from-self-managed-gitlab-to-gitlabcom). +The main difference is that an administrator can create users on the self-managed GitLab instance +through the UI or the [users API](../../../api/users.md#user-creation). -## Migrating between two self-managed GitLab instances +## Migrate between two self-managed GitLab instances -The best method for migrating from one GitLab instance to another, -perhaps from an old server to a new server for example, is to -[back up the instance](../../../raketasks/backup_restore.md), -then restore it on the new server. +To migrate from an existing self-managed GitLab instance to a new self-managed GitLab instance, it's +best to [back up](../../../raketasks/backup_restore.md) +the existing instance and restore it on the new instance. For example, this is useful when migrating +a self-managed instance from an old server to a new server. -In the event of merging two GitLab instances together (for example, both instances have existing data on them and one can't be wiped), -refer to the instructions in [Migrating from self-managed GitLab to GitLab.com](#migrating-from-self-managed-gitlab-to-gitlabcom). +To instead merge two self-managed GitLab instances together, use the instructions in +[Migrate from self-managed GitLab to GitLab.com](#migrate-from-self-managed-gitlab-to-gitlabcom). +This method is useful when both self-managed instances have existing data that must be preserved. -Additionally, you can migrate users using the [Users API](../../../api/users.md) with an administrator user. +Also note that administrators can use the [Users API](../../../api/users.md) +to migrate users. ## Project aliases **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/3264) in GitLab Premium 12.1. -When migrating repositories to GitLab and they are being accessed by other systems, -it's very useful to be able to access them using the same name especially when -they are a lot. It reduces the risk of changing significant number of Git URLs in -a large number of systems. - -GitLab provides a functionality to help with this. In GitLab, repositories are -usually accessed with a namespace and project name. It is also possible to access -them via a project alias. This feature is only available on Git over SSH. +GitLab repositories are usually accessed with a namespace and a project name. When migrating +frequently accessed repositories to GitLab, however, you can use project aliases to access those +repositories with the original name. Accessing repositories through a project alias reduces the risk +associated with migrating such repositories. -A project alias can be only created via API and only by GitLab administrators. -Follow the [Project Aliases API documentation](../../../api/project_aliases.md) for -more details. +This feature is only available on Git over SSH. Also, only GitLab administrators can create project +aliases, and they can only do so through the API. For more information, see the +[Project Aliases API documentation](../../../api/project_aliases.md). -After an alias has been created for a project (such as an alias `gitlab` for the -project `https://gitlab.com/gitlab-org/gitlab`), you can clone the repository -with the alias (e.g `git clone git@gitlab.com:gitlab.git` instead of -`git clone git@gitlab.com:gitlab-org/gitlab.git`). +After an administrator creates an alias for a project, you can use the alias to clone the +repository. For example, if an administrator creates the alias `gitlab` for the project +`https://gitlab.com/gitlab-org/gitlab`, you can clone the project with +`git clone git@gitlab.com:gitlab.git` instead of `git clone git@gitlab.com:gitlab-org/gitlab.git`. diff --git a/doc/user/project/import/jira.md b/doc/user/project/import/jira.md index 5fb737cf74a..4273f90c1e7 100644 --- a/doc/user/project/import/jira.md +++ b/doc/user/project/import/jira.md @@ -54,13 +54,13 @@ Make sure you have the integration set up before trying to import Jira issues. > New import form [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/216145) in GitLab 13.2. -To import Jira issues to a GitLab project, follow the steps below. - NOTE: Importing Jira issues is done as an asynchronous background job, which may result in delays based on import queues load, system load, or other factors. Importing large projects may take several minutes depending on the size of the import. +To import Jira issues to a GitLab project: + 1. On the **{issues}** **Issues** page, click **Import Issues** (**{import}**) **> Import from Jira**.  diff --git a/doc/user/project/import/manifest.md b/doc/user/project/import/manifest.md index 6ef91a54987..94eba319a17 100644 --- a/doc/user/project/import/manifest.md +++ b/doc/user/project/import/manifest.md @@ -29,7 +29,7 @@ A manifest must be an XML file. There must be one `remote` tag with a `review` attribute that contains a URL to a Git server, and each `project` tag must have a `name` and `path` attribute. GitLab will then build the URL to the repository by combining the URL from the `remote` tag with a project name. -A path attribute will be used to represent the project path in GitLab. +A path attribute is used to represent the project path in GitLab. Below is a valid example of a manifest file: @@ -42,23 +42,23 @@ Below is a valid example of a manifest file: </manifest> ``` -As a result, the following projects will be created: +As a result, the following projects are created: | GitLab | Import URL | |:------------------------------------------------|:------------------------------------------------------------| | `https://gitlab.com/YOUR_GROUP/build/make` | <https://android.googlesource.com/platform/build> | | `https://gitlab.com/YOUR_GROUP/build/blueprint` | <https://android.googlesource.com/platform/build/blueprint> | -## Importing the repositories +## Import the repositories -You can start the import with: +To start the import: -1. From your GitLab dashboard click **New project** -1. Switch to the **Import project** tab -1. Click on the **Manifest file** button -1. Provide GitLab with a manifest XML file -1. Select a group you want to import to (you need to create a group first if you don't have one) -1. Click **List available repositories**. At this point, you will be redirected +1. From your GitLab dashboard click **New project**. +1. Switch to the **Import project** tab. +1. Click on the **Manifest file** button. +1. Provide GitLab with a manifest XML file. +1. Select a group you want to import to (you need to create a group first if you don't have one). +1. Click **List available repositories**. At this point, you are redirected to the import status page with projects list based on the manifest file. 1. Check the list and click **Import all repositories** to start the import. diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index 91fd7b8928b..30a63a72cf9 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -20,7 +20,7 @@ GitLab allows you to import all tasks from a Phabricator instance into GitLab issues. The import creates a single project with the repository disabled. -Currently, only the following basic fields are imported: +Only the following basic fields are imported: - Title - Description @@ -34,6 +34,6 @@ The assignee and author of a user are deducted from a Task's owner and author: If a user with the same username has access to the namespace of the project being imported into, then the user will be linked. -## Enabling this feature +## Enable this feature Enable Phabricator as an [import source](../../admin_area/settings/visibility_and_access_controls.md#import-sources) in the Admin Area. diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index a816dca59bc..e39976e00f6 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -11,18 +11,16 @@ Subversion (SVN) is a central version control system (VCS) while Git is a distributed version control system. There are some major differences between the two, for more information consult your favorite search engine. -## Overview - There are two approaches to SVN to Git migration: -1. [Git/SVN Mirror](#smooth-migration-with-a-gitsvn-mirror-using-subgit) which: - - Makes the GitLab repository to mirror the SVN project. - - Git and SVN repositories are kept in sync; you can use either one. - - Smoothens the migration process and allows to manage migration risks. +- [Git/SVN Mirror](#smooth-migration-with-a-gitsvn-mirror-using-subgit) which: + - Makes the GitLab repository to mirror the SVN project. + - Git and SVN repositories are kept in sync; you can use either one. + - Smoothens the migration process and allows you to manage migration risks. -1. [Cut over migration](#cut-over-migration-with-svn2git) which: - - Translates and imports the existing data and history from SVN to Git. - - Is a fire and forget approach, good for smaller teams. +- [Cut over migration](#cut-over-migration-with-svn2git) which: + - Translates and imports the existing data and history from SVN to Git. + - Is a fire and forget approach, good for smaller teams. ## Smooth migration with a Git/SVN mirror using SubGit @@ -38,15 +36,15 @@ directly in a file system level. follow [this article](http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html). 1. Download SubGit from <https://subgit.com/download>. 1. Unpack the downloaded SubGit zip archive to the `/opt` directory. The `subgit` - command will be available at `/opt/subgit-VERSION/bin/subgit`. + command is available at `/opt/subgit-VERSION/bin/subgit`. ### SubGit configuration The first step to mirror you SVN repository in GitLab is to create a new empty -project which will be used as a mirror. For Omnibus installations the path to -the repository will be located at +project that is used as a mirror. For Omnibus installations the path to +the repository is `/var/opt/gitlab/git-data/repositories/USER/REPO.git` by default. For -installations from source, the default repository directory will be +installations from source, the default repository directory is `/home/git/repositories/USER/REPO.git`. For convenience, assign this path to a variable: @@ -54,7 +52,7 @@ variable: GIT_REPO_PATH=/var/opt/gitlab/git-data/repositories/USER/REPOS.git ``` -SubGit will keep this repository in sync with a remote SVN project. For +SubGit keeps this repository in sync with a remote SVN project. For convenience, assign your remote SVN project URL to a variable: ```shell @@ -89,9 +87,9 @@ initial translation of existing SVN revisions into the Git repository: subgit install $GIT_REPO_PATH ``` -After the initial translation is completed, the Git repository and the SVN -project will be kept in sync by `subgit` - new Git commits will be translated to -SVN revisions and new SVN revisions will be translated to Git commits. Mirror +After the initial translation is completed, `subgit` keeps the Git repository and the SVN +project sync - new Git commits are translated to +SVN revisions and new SVN revisions are translated to Git commits. Mirror works transparently and does not require any special commands. If you would prefer to perform one-time cut over migration with `subgit`, use @@ -134,12 +132,12 @@ sudo apt-get install git-core git-svn ruby ``` Optionally, prepare an authors file so `svn2git` can map SVN authors to Git authors. -If you choose not to create the authors file then commits will not be attributed +If you choose not to create the authors file then commits are not attributed to the correct GitLab user. Some users may not consider this a big issue while -others will want to ensure they complete this step. If you choose to map authors -you will be required to map every author that is present on changes in the SVN -repository. If you don't, the conversion will fail and you will have to update -the author file accordingly. The following command will search through the +others want to ensure they complete this step. If you choose to map authors, +you must map every author present on changes in the SVN +repository. If you don't, the conversion fails and you have to update +the author file accordingly. The following command searches through the repository and output a list of authors. ```shell @@ -159,7 +157,7 @@ not nested) the conversion is simple. For a non-standard repository see [svn2git documentation](https://github.com/nirvdrum/svn2git). The following command will checkout the repository and do the conversion in the current working directory. Be sure to create a new directory for each repository before -running the `svn2git` command. The conversion process will take some time. +running the `svn2git` command. The conversion process takes some time. ```shell svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt @@ -167,13 +165,13 @@ svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt If your SVN repository requires a username and password add the `--username <username>` and `--password <password>` flags to the above command. -`svn2git` also supports excluding certain file paths, branches, tags, etc. See +`svn2git` also supports excluding certain file paths, branches, tags, and so on. See [svn2git documentation](https://github.com/nirvdrum/svn2git) or run `svn2git --help` for full documentation on all of the available options. -Create a new GitLab project, where you will eventually push your converted code. +Create a new GitLab project, into which you push your converted code. Copy the SSH or HTTP(S) repository URL from the project page. Add the GitLab -repository as a Git remote and push all the changes. This will push all commits, +repository as a Git remote and push all the changes. This pushes all commits, branches and tags. ```shell diff --git a/doc/user/project/import/tfvc.md b/doc/user/project/import/tfvc.md index 0d347a16697..705df686fe0 100644 --- a/doc/user/project/import/tfvc.md +++ b/doc/user/project/import/tfvc.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: concepts --- -# Migrating from TFVC to Git +# Migrate from TFVC to Git Team Foundation Server (TFS), renamed [Azure DevOps Server](https://azure.microsoft.com/en-us/services/devops/server/) in 2019, is a set of tools developed by Microsoft which also includes @@ -46,12 +46,8 @@ Advantages of migrating to Git/GitLab: Migration options from TFVC to Git depend on your operating system. -- If you're migrating on Microsoft Windows: - - Use the [`git-tfs`](https://github.com/git-tfs/git-tfs) -tool. - Read the [Migrate TFS to Git](https://github.com/git-tfs/git-tfs/blob/master/doc/usecases/migrate_tfs_to_git.md) guide for details. - -- If you're on a Unix-based system: - - Follow the procedures described with this [TFVC to Git migration tool](https://github.com/turbo/gtfotfs). +- If you're migrating on Microsoft Windows, use the [`git-tfs`](https://github.com/git-tfs/git-tfs) + tool. See [Migrate TFS to Git](https://github.com/git-tfs/git-tfs/blob/master/doc/usecases/migrate_tfs_to_git.md) + for details. +- If you're on a Unix-based system, follow the procedures described with this + [TFVC to Git migration tool](https://github.com/turbo/gtfotfs). |
