diff options
Diffstat (limited to 'doc/user/project/import')
| -rw-r--r-- | doc/user/project/import/clearcase.md | 2 | ||||
| -rw-r--r-- | doc/user/project/import/github.md | 11 | ||||
| -rw-r--r-- | doc/user/project/import/gitlab_com.md | 37 | ||||
| -rw-r--r-- | doc/user/project/import/img/gitlab_importer.png | bin | 12864 -> 0 bytes | |||
| -rw-r--r-- | doc/user/project/import/img/gitlab_new_project_page_v12_2.png | bin | 66644 -> 0 bytes | |||
| -rw-r--r-- | doc/user/project/import/index.md | 11 | ||||
| -rw-r--r-- | doc/user/project/import/repo_by_url.md | 3 | ||||
| -rw-r--r-- | doc/user/project/import/svn.md | 211 |
8 files changed, 94 insertions, 181 deletions
diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md index d9ad0c57d79..2d9f92c38e4 100644 --- a/doc/user/project/import/clearcase.md +++ b/doc/user/project/import/clearcase.md @@ -11,7 +11,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w tools developed by IBM which also include a centralized version control system similar to Git. -A good read of ClearCase's basic concepts is can be found in this +A good read of ClearCase's basic concepts is can be found in this [StackOverflow post](https://stackoverflow.com/a/645771/974710). The following table illustrates the main differences between ClearCase and Git: diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md index a3dfa3edff0..c04f734e8bb 100644 --- a/doc/user/project/import/github.md +++ b/doc/user/project/import/github.md @@ -26,7 +26,7 @@ If you are importing from GitHub Enterprise to a self-managed GitLab instance: - You must first enable [GitHub integration](../../../integration/github.md). - To import projects from GitHub Enterprise to GitLab.com, use the [Import API](../../../api/import.md). -- If GitLab is behind a HTTP/HTTPS proxy, you must populate the [allowlist for local requests](../../../security/webhooks.md#allowlist-for-local-requests) +- If GitLab is behind a HTTP/HTTPS proxy, you must populate the [allowlist for local requests](../../../security/webhooks.md#create-an-allowlist-for-local-requests) with `github.com` and `api.github.com` to solve the hostname. For more information, read the issue [Importing a GitHub project requires DNS resolution even when behind a proxy](https://gitlab.com/gitlab-org/gitlab/-/issues/37941). @@ -62,7 +62,7 @@ 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 [public-facing email address](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-user-account/managing-email-preferences/setting-your-commit-email-address) +- Have a GitHub account with a [public-facing email address](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address) that matches their GitLab account's email address. GitLab content imports that use GitHub accounts require that the GitHub public-facing email address is populated. This means @@ -76,7 +76,7 @@ field to be populated so you may have to add it on existing accounts. Before you begin, ensure that any GitHub users who you want to map to GitLab users have either: - A GitLab account that has logged in using the GitHub icon. -- A GitLab account with an email address that matches the [publicly visible email address](https://docs.github.com/en/rest/reference/users#get-a-user) in the profile of the GitHub user +- A GitLab account with an email address that matches the [publicly visible email address](https://docs.github.com/en/rest/users#get-a-user) in the profile of the GitHub user If you are importing to GitLab.com, you can alternatively import GitHub repositories 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. @@ -171,12 +171,15 @@ The following items of a project are imported: - Repository description. - Git repository data. +- Branch protection rules. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/22650) in GitLab 15.4. - Issues. - Pull requests. - Wiki pages. - Milestones. - Labels. - Release note descriptions. +- Release note attachments. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15620) in GitLab 15.4 with `github_importer_attachments_import` + [feature flag](../../../administration/feature_flags.md) disabled by default. - Pull request review comments. - Regular issue and pull request comments. - [Git Large File Storage (LFS) Objects](../../../topics/git/lfs/index.md). @@ -184,6 +187,8 @@ The following items of a project are imported: - Pull request "merged by" information (GitLab.com and GitLab 13.7 and later). - Pull request comments replies in discussions ([GitLab.com and GitLab 14.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/336596)). - Diff Notes suggestions ([GitLab.com and GitLab 14.7 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/340624)). +- Issue events and pull requests events. [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/7673) in GitLab 15.4 with `github_importer_issue_events_import` + [feature flag](../../../administration/feature_flags.md) disabled by default. References to pull requests and issues are preserved. Each imported repository maintains visibility level unless that [visibility level is restricted](../../public_access.md#restrict-use-of-public-or-internal-projects), in which case it diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md index 4103367accc..8d30a9c7f52 100644 --- a/doc/user/project/import/gitlab_com.md +++ b/doc/user/project/import/gitlab_com.md @@ -5,29 +5,30 @@ 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 --- -# Project importing from GitLab.com to your private GitLab instance **(FREE)** +# Import a project from GitLab.com to your private GitLab instance **(FREE)** -You can import your existing GitLab.com projects to your GitLab instance, but keep in -mind that it is possible only if GitLab.com integration is enabled on your GitLab instance. -[Read more about GitLab.com integration for self-managed GitLab instances](../../../integration/gitlab.md). +You can import your existing GitLab.com projects to your GitLab instance. -To get to the importer page you need to go to "New project" page. +Prerequisite: -NOTE: -If you are interested in importing Wiki and merge request data to your new instance, -you'll need to follow the instructions for [exporting a project](../settings/import_export.md#export-a-project-and-its-data) +- GitLab.com integration must be enabled on your GitLab instance. + [Read more about GitLab.com integration for self-managed GitLab instances](../../../integration/gitlab.md). - +To import a GitLab.com project to your self-managed GitLab instance: -Go to the **Import Projects** tab, then select **GitLab.com**, and you are redirected to GitLab.com -for permission to access your projects. After accepting, you are automatically redirected to the importer. +1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. +1. Select **Import project**. +1. Select **GitLab.com**. +1. Give GitLab.com permission to access your projects. +1. Select **Import**. - +The importer imports your repository and issues. +When the importer is done, a new GitLab project is created with your imported data. -To import a project, select **Import**. The importer imports your repository and issues. -Once the importer is done, a new GitLab project is created with your imported data. +## Related topics -## Automate group and project import **(PREMIUM)** - -For information on automating user, group, and project import API calls, see -[Automate group and project import](index.md#automate-group-and-project-import). +- To automate user, group, and project import API calls, see + [Automate group and project import](index.md#automate-group-and-project-import). +- To import Wiki and merge request data to your new instance, + see [exporting a project](../settings/import_export.md#export-a-project-and-its-data). diff --git a/doc/user/project/import/img/gitlab_importer.png b/doc/user/project/import/img/gitlab_importer.png Binary files differdeleted file mode 100644 index 27d42eb492e..00000000000 --- a/doc/user/project/import/img/gitlab_importer.png +++ /dev/null diff --git a/doc/user/project/import/img/gitlab_new_project_page_v12_2.png b/doc/user/project/import/img/gitlab_new_project_page_v12_2.png Binary files differdeleted file mode 100644 index ff6e5dbf4a1..00000000000 --- a/doc/user/project/import/img/gitlab_new_project_page_v12_2.png +++ /dev/null diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index 432f043f945..72d533efd1b 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -85,7 +85,7 @@ Migrate the assets in this order: Keep in mind the limitations of the [import/export feature](../settings/import_export.md#items-that-are-exported). -You must still migrate your [Container Registry](../../packages/container_registry/) +You must still migrate your [Container Registry](../../packages/container_registry/index.md) over a series of Docker pulls and pushes. Re-run any CI pipelines to retrieve any build artifacts. ## Migrate from GitLab.com to self-managed GitLab @@ -142,5 +142,10 @@ GitLab from: - Bitbucket Server - Bitbucket Data Center -See the [Quick Start Guide](https://gitlab.com/gitlab-org/professional-services-automation/tools/migration/congregate/-/blob/master/docs/using-congregate.md#quick-start) -to learn how to use this approach for migrating users, groups, and projects at scale. +For more information, see: + +- [Quick Start](https://gitlab.com/gitlab-org/professional-services-automation/tools/migration/congregate/-/blob/master/docs/using-congregate.md#quick-start). +- [Frequently Asked Migration Questions](https://gitlab.com/gitlab-org/professional-services-automation/tools/migration/congregate/-/blob/master/customer/famq.md), + including settings that need checking afterwards and other limitations. + +For support, customers must enter into a paid engagement with GitLab Professional Services. diff --git a/doc/user/project/import/repo_by_url.md b/doc/user/project/import/repo_by_url.md index 5163f957171..d64bea2bb41 100644 --- a/doc/user/project/import/repo_by_url.md +++ b/doc/user/project/import/repo_by_url.md @@ -9,7 +9,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w You can import your existing repositories by providing the Git URL: -1. On the top bar, select **Menu > Create new project**. +1. In GitLab, on the top bar, select **Main menu > Projects > View all projects**. +1. On the right of the page, select **New project**. 1. Select the **Import project** tab. 1. Select **Repository by URL**. 1. Enter a **Git repository URL**. diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md index b88abf91ae1..d6bcb0a2018 100644 --- a/doc/user/project/import/svn.md +++ b/doc/user/project/import/svn.md @@ -5,186 +5,87 @@ 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 from SVN to GitLab **(FREE)** +# Migrate from Subversion to GitLab **(FREE)** -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. +GitLab uses Git as its version control system. If you're using Subversion (SVN) as your version control system, +you can migrate to using a Git repository in GitLab using `svn2git`. -There are two approaches to SVN to Git migration: +You can follow the steps on this page to migrate to Git if your SVN repository: -- [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. +- Has a standard format (trunk, branches, and tags). +- Is not nested. -- [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. +For a non-standard repository see the [`svn2git` documentation](https://github.com/nirvdrum/svn2git). -## Smooth migration with a Git/SVN mirror using SubGit +We recommend a hard cut over from SVN to Git and GitLab. Run the migration command once and then have all users use the +new GitLab repository immediately. -[SubGit](https://subgit.com) is a tool for a smooth, stress-free SVN to Git -migration. It creates a writable Git mirror of a local or remote Subversion -repository and that way you can use both Subversion and Git as long as you like. -It requires access to your GitLab server as it talks with the Git repositories -directly in a file system level. +## Install `svn2git` -### SubGit prerequisites +Install `svn2git` on a local workstation rather than the GitLab server: -1. Install Oracle JRE 1.8 or newer. On Debian-based Linux distributions you can - 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 is available at `/opt/subgit-VERSION/bin/subgit`. +- On all systems you can install as a Ruby gem if you already have Ruby and Git installed: -### SubGit configuration + ```shell + sudo gem install svn2git + ``` -The first step to mirror you SVN repository in GitLab is to create a new empty -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 is -`/home/git/repositories/USER/REPO.git`. For convenience, assign this path to a -variable: +- On Debian-based Linux distributions you can install the native packages: -```shell -GIT_REPO_PATH=/var/opt/gitlab/git-data/repositories/USER/REPOS.git -``` + ```shell + sudo apt-get install git-core git-svn ruby + ``` -SubGit keeps this repository in sync with a remote SVN project. For -convenience, assign your remote SVN project URL to a variable: +## Prepare an authors file (recommended) -```shell -SVN_PROJECT_URL=http://svn.company.com/repos/project -``` +Prepare an authors file so `svn2git` can map SVN authors to Git authors. If you choose not to create the authors file, +commits are not attributed to the correct GitLab user. -Next you need to run SubGit to set up a Git/SVN mirror. Make sure the following -`subgit` command is ran on behalf of the same user that keeps ownership of -GitLab Git repositories (by default `git`): +To map authors, you must map every author present on changes in the SVN repository. If you don't, the +migration fails and you have to update the author file accordingly. -```shell -subgit configure --layout auto $SVN_PROJECT_URL $GIT_REPO_PATH -``` +1. Search through the SVN repository and output a list of authors: -Adjust authors and branches mappings, if necessary. Open with your favorite -text editor: + ```shell + svn log --quiet | grep -E "r[0-9]+ \| .+ \|" | cut -d'|' -f2 | sed 's/ //g' | sort | uniq + ``` -```shell -edit $GIT_REPO_PATH/subgit/authors.txt -edit $GIT_REPO_PATH/subgit/config -``` +1. Use the output from the last command to construct the authors file. Create a file called `authors.txt` and add one + mapping per line. For example: -For more information regarding the SubGit configuration options, refer to -[SubGit's documentation](https://subgit.com/documentation/) website. + ```plaintext + sidneyjones = Sidney Jones <sidneyjones@example.com> + ``` -### Initial translation +## Migrate SVN repository to Git repository -Now that SubGit has configured the Git/SVN repositories, run `subgit` to perform the -initial translation of existing SVN revisions into the Git repository: +`svn2git` supports excluding certain file paths, branches, tags, and more. See +the [`svn2git` documentation](https://github.com/nirvdrum/svn2git) or run `svn2git --help` for full documentation on all of +the available options. -```shell -subgit install $GIT_REPO_PATH -``` +For each repository to migrate: -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. +1. Create a new directory and change into it. +1. For repositories that: -If you would prefer to perform one-time cut over migration with `subgit`, use -the `import` command instead of `install`: + - Don't require a username and password, run: -```shell -subgit import $GIT_REPO_PATH -``` + ```shell + svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt + ``` -### SubGit licensing + - Do require a username and password, run: -Running SubGit in a mirror mode requires a -[registration](https://subgit.com/pricing). Registration is free for open -source, academic and startup projects. + ```shell + svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt --username <username> --password <password> + ``` -### SubGit support +1. Create a new GitLab project for your migrated code. +1. Copy the SSH or HTTP(S) repository URL from the GitLab project page. +1. Add the GitLab repository as a Git remote and push all the changes. This pushes all commits, branches, and tags. -For any questions related to SVN to GitLab migration with SubGit, you can -contact the SubGit team directly at [support@subgit.com](mailto:support@subgit.com). - -## Cut over migration with svn2git - -NOTE: -Any issues with svn2git should be directed to the [relevant project and maintainer](https://github.com/nirvdrum/svn2git). -Check for existing issues and history for update frequency. - -If you are currently using an SVN repository, you can migrate the repository -to Git and GitLab. We recommend a hard cut over - run the migration command once -and then have all developers start using the new GitLab repository immediately. -Otherwise, it's hard to keep changing in sync in both directions. The conversion -process should be run on a local workstation. - -Install `svn2git`. On all systems you can install as a Ruby gem if you already -have Ruby and Git installed. - -```shell -sudo gem install svn2git -``` - -On Debian-based Linux distributions you can install the native packages: - -```shell -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 are not attributed -to the correct GitLab user. Some users may not consider this a big issue while -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 -svn log --quiet | grep -E "r[0-9]+ \| .+ \|" | cut -d'|' -f2 | sed 's/ //g' | sort | uniq -``` - -Use the output from the last command to construct the authors file. -Create a file called `authors.txt` and add one mapping per line. - -```plaintext -janedoe = Jane Doe <janedoe@example.com> -johndoe = John Doe <johndoe@example.com> -``` - -If your SVN repository is in the standard format (trunk, branches, tags, -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 takes some time. - -```shell -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, 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, 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 pushes all commits, -branches and tags. - -```shell -git remote add origin git@gitlab.com:<group>/<project>.git -git push --all origin -git push --tags origin -``` - -## Contribute to this guide - -We welcome all contributions that would expand this guide with instructions on -how to migrate from SVN and other version control systems. + ```shell + git remote add origin git@gitlab.example.com:<group>/<project>.git + git push --all origin + git push --tags origin + ``` |
