Commit bc3b44f9 authored by Nick Gaskill's avatar Nick Gaskill

Merge branch 'docs-ctrt-group-migration' into 'master'

CTRT edits for group migration doc

See merge request gitlab-org/gitlab!76897
parents 63eab949 07f0198f
......@@ -11,10 +11,7 @@
.gl-alert-body
- docs_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: help_page_path('user/group/import/index.md') }
- link_end = '</a>'.html_safe
= s_('GroupsNew|This feature is deprecated and replaced by %{docs_link_start}Group Migration%{docs_link_end}.').html_safe % { docs_link_start: docs_link_start, docs_link_end: link_end }
- if Feature.enabled?(:bulk_import, default_enabled: :yaml)
- enable_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: help_page_path('user/group/import/index.md', anchor: 'enable-or-disable-gitlab-group-migration') }
= s_('GroupsNew|Ask your administrator to %{enable_link_start}enable%{enable_link_end} Group Migration.').html_safe % { enable_link_start: enable_link_start, enable_link_end: link_end }
= s_('GroupsNew|This feature is deprecated and replaced by %{docs_link_start}group migration%{docs_link_end}.').html_safe % { docs_link_start: docs_link_start, docs_link_end: link_end }
.form-group.gl-display-flex.gl-flex-direction-column.gl-mt-5
= f.label :name, _('New group name'), for: 'import_group_name'
......
......@@ -10,7 +10,7 @@
.gl-alert-body
- docs_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: help_page_path('user/group/import/index.md') }
- docs_link_end = '</a>'.html_safe
= s_('GroupsNew|This feature is deprecated and replaced by %{docs_link_start}Group Migration%{docs_link_end}.').html_safe % { docs_link_start: docs_link_start, docs_link_end: docs_link_end }
= s_('GroupsNew|This feature is deprecated and replaced by %{docs_link_start}group migration%{docs_link_end}.').html_safe % { docs_link_start: docs_link_start, docs_link_end: docs_link_end }
%p
- export_information = _('After the export is complete, download the data file from a notification email or from this page. You can then import the data file from the %{strong_text_start}Create new group%{strong_text_end} page of another GitLab instance.') % { strong_text_start: '<strong>'.html_safe, strong_text_end: '</strong>'.html_safe}
= export_information.html_safe
......
......@@ -18,7 +18,7 @@ With the Project Relations Export API, you can partially export project structur
similar to [project export](project_import_export.md),
but it exports each top-level relation (for example, milestones/boards/labels) as a separate file
instead of one archive. The project relations export API is primarily used in
[group migration](../user/group/import/index.md#enable-or-disable-gitlab-group-migration)
[group migration](../user/group/import/index.md)
to support group project import.
## Schedule new export
......
......@@ -10,20 +10,81 @@ info: To determine the technical writer assigned to the Stage/Group associated w
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/249160) in GitLab 13.7 [with a flag](../../feature_flags.md) named `bulk_import`. Disabled by default.
> - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/338985) in GitLab 14.3.
FLAG:
On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../../administration/feature_flags.md) named `bulk_import`. On GitLab.com, this feature is available.
You can migrate your existing top-level groups to any of the following:
- Another GitLab instance, including GitLab.com.
- Another top-level group.
- The subgroup of any existing top-level group.
Migrating groups is not the same as [group import/export](../settings/import_export.md).
- Group import/export requires you to export a group to a file and then import that file in
another GitLab instance.
- Group migration automates this process.
## Import your groups into GitLab
When you migrate a group, you connect to your GitLab instance and then choose
groups to import. Not all the data is migrated. View the
[Migrated resources](#migrated-resources) list for details.
Leave feedback about group migration in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/284495).
NOTE:
The importer migrates **only** the group data listed on this page. To leave feedback on this
feature, see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/284495).
You might need to reconfigure your firewall to prevent blocking the connection on the self-managed
instance.
### Connect to the remote GitLab instance
Using GitLab Group Migration, you can migrate existing top-level groups from GitLab.com or a self-managed instance. Groups can be migrated to a target instance, as a top-level group, or as a subgroup of any existing top-level group.
Before you begin, ensure that the target GitLab instance can communicate with the source over HTTPS
(HTTP is not supported). You might need to reconfigure your firewall to prevent blocking the connection on the self-managed
instance.
The following resources are migrated to the target instance:
Then create the group you want to import into, and connect:
1. Create a new group or subgroup:
- On the top bar, select `+` and then **New group**.
- Or, on an existing group's page, in the top right, select **New subgroup**.
1. Select **Import group**.
1. Enter the source URL of your GitLab instance.
1. Generate or copy a [personal access token](../../../user/profile/personal_access_tokens.md)
with the `api` and `read_repository` scopes on your remote GitLab instance.
1. Enter the [personal access token](../../../user/profile/personal_access_tokens.md) for your remote GitLab instance.
1. Select **Connect instance**.
### Select the groups to import
After you have authorized access to the GitLab instance, you are redirected to the GitLab Group
Migration importer page. The remote groups you have the Owner role for are listed.
1. By default, the proposed group namespaces match the names as they exist in remote instance, but based on your permissions, you can choose to edit these names before you proceed to import any of them.
1. Next to the groups you want to import, select **Import**.
1. The **Status** column shows the import status of each group. If you leave the page open, it updates in real-time.
1. After a group has been imported, select its GitLab path to open its GitLab URL.
![Group Importer page](img/bulk_imports_v14_1.png)
## Automate group and project import **(PREMIUM)**
For information on automating user, group, and project import API calls, see
[Automate group and project import](../../project/import/index.md#automate-group-and-project-import).
## Migrated resources
Only the following resources are migrated to the target instance. Any other items are **not**
migrated:
- Groups ([Introduced](https://gitlab.com/groups/gitlab-org/-/epics/4374) in 13.7)
- description
- attributes
- subgroups
- avatar ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/322904) in 14.0)
- Group Labels ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292429) in 13.9)
- Group labels ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/292429) in 13.9)
- title
- description
- color
......@@ -71,67 +132,3 @@ The following resources are migrated to the target instance:
- image URL
- Boards
- Board Lists
Any other items are **not** migrated.
## Enable or disable GitLab Group Migration
GitLab Migration is deployed behind the `bulk_import` feature flag, which is **enabled by default**.
[GitLab administrators with access to the GitLab Rails console](../../../administration/feature_flags.md)
can disable it.
To disable it:
```ruby
Feature.disable(:bulk_import)
```
To enable it:
```ruby
Feature.enable(:bulk_import)
```
## Import your groups into GitLab
Before you begin, ensure that the target instance of GitLab can communicate with the source
over HTTPS (HTTP is not supported).
NOTE:
This might involve reconfiguring your firewall to prevent blocking connection on the side of self-managed instance.
### Connect to the remote GitLab instance
1. Go to the New Group page:
- On the top bar, select `+` and then **New group**.
- Or, on an existing group's page, in the top right, select **New subgroup**.
![Navigation paths to create a new group](img/new_group_navigation_v13_8.png)
1. On the New Group page, select **Import group**.
![Fill in import details](img/import_panel_v14_1.png)
1. Enter the source URL of your GitLab instance.
1. Generate or copy a [personal access token](../../../user/profile/personal_access_tokens.md)
with the `api` and `read_repository` scopes on your remote GitLab instance.
1. Enter the [personal access token](../../../user/profile/personal_access_tokens.md) for your remote GitLab instance.
1. Select **Connect instance**.
### Selecting which groups to import
After you have authorized access to the GitLab instance, you are redirected to the GitLab Group
Migration importer page. The remote groups you have the Owner role for are listed.
1. By default, the proposed group namespaces match the names as they exist in remote instance, but based on your permissions, you can choose to edit these names before you proceed to import any of them.
1. Next to the groups you want to import, select **Import**.
1. The **Status** column shows the import status of each group. If you leave the page open, it updates in real-time.
1. After a group has been imported, select its GitLab path to open its GitLab URL.
![Group Importer page](img/bulk_imports_v14_1.png)
## Automate group and project import **(PREMIUM)**
For information on automating user, group, and project import API calls, see
[Automate group and project import](../../project/import/index.md#automate-group-and-project-import).
......@@ -17402,9 +17402,6 @@ msgstr ""
msgid "GroupsNew|%{linkStart}Groups%{linkEnd} allow you to manage and collaborate across multiple projects. Members of a group have access to all of its projects."
msgstr ""
msgid "GroupsNew|Ask your administrator to %{enable_link_start}enable%{enable_link_end} Group Migration."
msgstr ""
msgid "GroupsNew|Assemble related projects together and grant members access to several projects at once."
msgstr ""
......@@ -17459,7 +17456,7 @@ msgstr ""
msgid "GroupsNew|Provide credentials for another instance of GitLab to import your groups directly."
msgstr ""
msgid "GroupsNew|This feature is deprecated and replaced by %{docs_link_start}Group Migration%{docs_link_end}."
msgid "GroupsNew|This feature is deprecated and replaced by %{docs_link_start}group migration%{docs_link_end}."
msgstr ""
msgid "GroupsNew|To import a group, navigate to the group settings for the GitLab source instance, %{link_start}generate an export file%{link_end}, and upload it here."
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment