diff options
Diffstat (limited to 'doc/user/project/settings/import_export.md')
| -rw-r--r-- | doc/user/project/settings/import_export.md | 296 |
1 files changed, 148 insertions, 148 deletions
diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index da0336d01ff..06bdf4ca14b 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -6,129 +6,69 @@ info: "To determine the technical writer assigned to the Stage/Group associated # Project import/export **(FREE)** -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/3050) in GitLab 8.9. -> - From GitLab 10.0, administrators can disable the project export option on the GitLab instance. +Existing projects on any self-managed GitLab instance or GitLab.com can be exported to a file and +then imported into a new GitLab instance. -Existing projects running on any GitLab instance or GitLab.com can be exported with all their related -data and be moved into a new GitLab instance. +## Set up project import/export -The **GitLab import/export** button is displayed if the project import option is enabled. +Before you can import or export a project and its data, you must set it up. -See also: +1. On the left sidebar, select **Settings > General**. +1. Expand **Visibility and access controls**. +1. Scroll to **Import sources**. +1. Enable the desired **Import sources**. -- [Project import/export API](../../../api/project_import_export.md) -- [Project import/export administration Rake tasks](../../../administration/raketasks/project_import_export.md) **(FREE SELF)** -- [Group import/export](../../group/settings/import_export.md) -- [Group import/export API](../../../api/group_import_export.md) - -To set up a project import/export: - - 1. On the top bar, go to **Menu > Admin > Settings > General > Visibility and access controls**. - 1. Scroll to **Import sources**. - 1. Enable the desired **Import sources**. - -## Important notes - -Note the following: - -- Before you can import a project, you must export the data first. - See [Export a project and its data](#export-a-project-and-its-data) - for how you can export a project through the UI. -- Imports from a newer version of GitLab are not supported. - The Importing GitLab version must be greater than or equal to the Exporting GitLab version. -- Imports fail unless the import and export GitLab instances are - compatible as described in the [Version history](#version-history). -- Exports are generated in your configured `shared_path`, a temporary shared directory, - and are moved to your configured `uploads_directory`. Every 24 hours, a specific worker deletes these export files. -- Group members are exported as project members, as long as the user has - a maintainer or administrator role in the group where the exported project lives. -- Project members with the [Owner role](../../permissions.md) are imported as Maintainers. -- Imported users can be mapped by their public email on self-managed instances, if an administrative user (not an owner) does the import. - The public email is not set by default. Users must [set it in their profiles](../../profile/index.md#set-your-public-email) - for mapping to work correctly. Additionally, the user must be an existing member of the namespace, - or the user can be added as a member of the project for contributions to be mapped. - Otherwise, a supplementary comment is left to mention that the original author and - the MRs, notes, or issues are owned by the importer. - - For project migration imports performed over GitLab.com Groups, preserving author information is - possible through a [professional services engagement](https://about.gitlab.com/services/migration/). -- If an imported project contains merge requests originating from forks, - then new branches associated with such merge requests are created - in a project during the import/export. Thus, the number of branches - in the exported project could be bigger than in the original project. -- Deploy keys allowed to push to protected branches are not exported. Therefore, - you must recreate this association by first enabling these deploy keys in your - imported project and then updating your protected branches accordingly. - -## Version history - -### 14.0+ - -In GitLab 14.0, the JSON format is no longer supported for project and group exports. To allow for a -transitional period, you can still import any JSON exports. The new format for imports and exports -is NDJSON. +## Between CE and EE -### 13.0+ +You can export projects from the [Community Edition to the Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/) +and vice versa. This assumes [version history](#version-history) +requirements are met. -Starting with GitLab 13.0, GitLab can import bundles that were exported from a different GitLab deployment. -This ability is limited to two previous GitLab [minor](../../../policy/maintenance.md#versioning) -releases, which is similar to our process for [Security Releases](../../../policy/maintenance.md#security-releases). +If you're exporting a project from the Enterprise Edition to the Community Edition, you may lose +data that is retained only in the Enterprise Edition. For more information, see +[downgrading from EE to CE](../../../index.md). -For example: +## Export a project and its data -| Current version | Can import bundles exported from | -|-----------------|----------------------------------| -| 13.0 | 13.0, 12.10, 12.9 | -| 13.1 | 13.1, 13.0, 12.10 | +Before you can import a project, you must export it. -### 12.x +Prerequisites: -Prior to 13.0 this was a defined compatibility table: +- Review the list of [data that will be exported](#items-that-are-exported). + Not all data is exported. +- You must have at least the Maintainer role for the project. -| Exporting GitLab version | Importing GitLab version | -| -------------------------- | -------------------------- | -| 11.7 to 12.10 | 11.7 to 12.10 | -| 11.1 to 11.6 | 11.1 to 11.6 | -| 10.8 to 11.0 | 10.8 to 11.0 | -| 10.4 to 10.7 | 10.4 to 10.7 | -| 10.3 | 10.3 | -| 10.0 to 10.2 | 10.0 to 10.2 | -| 9.4 to 9.6 | 9.4 to 9.6 | -| 9.2 to 9.3 | 9.2 to 9.3 | -| 8.17 to 9.1 | 8.17 to 9.1 | -| 8.13 to 8.16 | 8.13 to 8.16 | -| 8.12 | 8.12 | -| 8.10.3 to 8.11 | 8.10.3 to 8.11 | -| 8.10.0 to 8.10.2 | 8.10.0 to 8.10.2 | -| 8.9.5 to 8.9.11 | 8.9.5 to 8.9.11 | -| 8.9.0 to 8.9.4 | 8.9.0 to 8.9.4 | - -Projects can be exported and imported only between versions of GitLab with matching Import/Export versions. - -For example, 8.10.3 and 8.11 have the same Import/Export version (0.1.3) -and the exports between them are compatible. - -## Between CE and EE +To export a project and its data, follow these steps: -You can export projects from the [Community Edition to the Enterprise Edition](https://about.gitlab.com/install/ce-or-ee/) and vice versa. -This assumes [version history](#version-history) requirements are met. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings**. +1. Expand **Advanced**. +1. Select **Export project**. +1. After the export is generated, you should receive an email with a link to download the file. +1. Alternatively, you can come back to the project settings and download the file from there or + generate a new export. After the file is available, the page should show the **Download export** + button. -If you're exporting a project from the Enterprise Edition to the Community Edition, you may lose data that is retained only in the Enterprise Edition. For more information, see [downgrading from EE to CE](../../../index.md). +The export is generated in your configured `shared_path`, a temporary shared directory, and then +moved to your configured `uploads_directory`. Every 24 hours, a worker deletes these export files. -## Exported contents +### Items that are exported The following items are exported: - Project and wiki repositories - Project uploads - Project configuration, excluding integrations -- Issues with comments, merge requests with diffs and comments, labels, milestones, snippets, time tracking, - and other project entities +- Issues with comments, merge requests with diffs and comments, labels, milestones, snippets, time + tracking, and other project entities - Design Management files and data - LFS objects - Issue boards - Pipelines history - Push Rules - Awards +- Group members are exported as project members, as long as the user has the Maintainer role in the + exported project's group, or is an administrator The following items are **not** exported: @@ -140,6 +80,7 @@ The following items are **not** exported: - Any encrypted tokens - Merge Request Approvers - Repository size limits +- Deploy keys allowed to push to protected branches These content rules also apply to creating projects from templates on the [group](../../group/custom_project_templates.md) @@ -150,87 +91,146 @@ NOTE: For more details on the specific data persisted in a project export, see the [`import_export.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/import_export/project/import_export.yml) file. -## Export a project and its data - -Full project export functionality is limited to project maintainers and owners. -You can configure such functionality through [project settings](index.md): - -To export a project and its data, follow these steps: +## Import a project and its data -1. Go to your project's homepage. +> Default maximum import file size [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to unlimited in GitLab 13.8. -1. Select **Settings** in the sidebar. +WARNING: +Only import projects from sources you trust. If you import a project from an untrusted source, it +may be possible for an attacker to steal your sensitive data. -1. Scroll down and expand the **Advanced** section. +Prerequisites: -1. Scroll down to find the **Export project** button: +- You must have [exported the project and its data](#export-a-project-and-its-data). +- Compare GitLab versions and ensure you are importing to a GitLab version that is the same or later + than the GitLab version you exported to. +- Review the [Version history](#version-history) + for compatibility issues. -  +To import a project: -1. After the export is generated, you should receive an email with a link to - download the file: +1. When [creating a new project](../working_with_projects.md#create-a-project), + select **Import project**. +1. In **Import project from**, select **GitLab export**. +1. Enter your project name and URL. Then select the file you exported previously. +1. Select **Import project** to begin importing. Your newly imported project page appears shortly. -  +To get the status of an import, you can query it through the [Project import/export API](../../../api/project_import_export.md#import-status). +As described in the API documentation, the query may return an import error or exceptions. -1. Alternatively, you can come back to the project settings and download the - file from there, or generate a new export. After the file is available, the page - should show the **Download export** button: +### Items that are imported -  +The following items are imported but changed slightly: -## Import the project +- Project members with the [Owner role](../../permissions.md) + are imported as Maintainers. +- If an imported project contains merge requests originating from forks, then new branches + associated with such merge requests are created in a project during the import/export. Thus, the + number of branches in the exported project might be bigger than in the original project. +- If use of the `Internal` visibility level + [is restricted](../../../public_access/public_access.md#restrict-use-of-public-or-internal-projects), + all imported projects are given `Private` visibility. -> Default maximum import file size [changed](https://gitlab.com/gitlab-org/gitlab/-/issues/251106) from 50 MB to unlimited in GitLab 13.8. +Deploy keys aren't imported. To use deploy keys, you must enable them in your imported project and update protected branches. -WARNING: -Only import projects from sources you trust. If you import a project from an untrusted source, it -may be possible for an attacker to steal your sensitive data. +### Import large projects **(FREE SELF)** -1. The GitLab project import feature is the first import option when creating a - new project. Select **GitLab export**: +If you have a larger project, consider using a Rake task as described in the [developer documentation](../../../development/import_project.md#importing-via-a-rake-task). -  +## Automate group and project import **(PREMIUM)** -1. Enter your project name and URL. Then select the file you exported previously: +For information on automating user, group, and project import API calls, see +[Automate group and project import](../import/index.md#automate-group-and-project-import). -  +## Maximum import file size -1. Select **Import project** to begin importing. Your newly imported project - page appears shortly. +Administrators can set the maximum import file size one of two ways: -NOTE: -If use of the `Internal` visibility level -[is restricted](../../../public_access/public_access.md#restrict-use-of-public-or-internal-projects), -all imported projects are given the visibility of `Private`. +- With the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings). +- In the [Admin Area UI](../../admin_area/settings/account_and_limit_settings.md#max-import-size). -The maximum import file size can be set by the Administrator, and the default is `0` (unlimited). -As an administrator, you can modify the maximum import file size. To do so, use the `max_import_size` option in the [Application settings API](../../../api/settings.md#change-application-settings) or the [Admin Area UI](../../admin_area/settings/account_and_limit_settings.md). +The default is `0` (unlimited). -### Project import status +## Map users for import -You can query an import through the [Project import/export API](../../../api/project_import_export.md#import-status). -As described in the API documentation, the query may return an import error or exceptions. +Imported users can be mapped by their public email addresses on self-managed instances, if an administrator (not an owner) does the import. -### Import large projects **(FREE SELF)** +- Public email addresses are not set by default. Users must +[set it in their profiles](../../profile/index.md#set-your-public-email) +for mapping to work correctly. +- For contributions to be mapped correctly, users must be an existing member of the namespace, + or they can be added as a member of the project. Otherwise, a supplementary comment is left to mention that the original author and the MRs, notes, or issues that are owned by the importer. -If you have a larger project, consider using a Rake task, as described in our [developer documentation](../../../development/import_project.md#importing-via-a-rake-task). +For project migration imports performed over GitLab.com groups, preserving author information is +possible through a [professional services engagement](https://about.gitlab.com/services/migration/). ## Rate Limits To help avoid abuse, by default, users are rate limited to: -| Request Type | Limit | -| ---------------- | ---------------------------------------- | -| Export | 6 projects per minute | -| Download export | 1 download per group per minute | -| Import | 6 projects per minute | +| Request Type | Limit | +| ---------------- | ----- | +| Export | 6 projects per minute | +| Download export | 1 download per group per minute | +| Import | 6 projects per minute | -GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) from the defaults. +GitLab.com may have [different settings](../../gitlab_com/index.md#importexport) +from the defaults. -## Automate group and project import **(PREMIUM)** +## Version history -For information on automating user, group, and project import API calls, see -[Automate group and project import](../import/index.md#automate-group-and-project-import). +### 14.0+ + +In GitLab 14.0, the JSON format is no longer supported for project and group exports. To allow for a +transitional period, you can still import any JSON exports. The new format for imports and exports +is NDJSON. + +### 13.0+ + +Starting with GitLab 13.0, GitLab can import bundles that were exported from a different GitLab deployment. +This ability is limited to two previous GitLab [minor](../../../policy/maintenance.md#versioning) +releases, which is similar to our process for [Security Releases](../../../policy/maintenance.md#security-releases). + +For example: + +| Current version | Can import bundles exported from | +|-----------------|----------------------------------| +| 13.0 | 13.0, 12.10, 12.9 | +| 13.1 | 13.1, 13.0, 12.10 | + +### 12.x + +Prior to 13.0 this was a defined compatibility table: + +| Exporting GitLab version | Importing GitLab version | +| -------------------------- | -------------------------- | +| 11.7 to 12.10 | 11.7 to 12.10 | +| 11.1 to 11.6 | 11.1 to 11.6 | +| 10.8 to 11.0 | 10.8 to 11.0 | +| 10.4 to 10.7 | 10.4 to 10.7 | +| 10.3 | 10.3 | +| 10.0 to 10.2 | 10.0 to 10.2 | +| 9.4 to 9.6 | 9.4 to 9.6 | +| 9.2 to 9.3 | 9.2 to 9.3 | +| 8.17 to 9.1 | 8.17 to 9.1 | +| 8.13 to 8.16 | 8.13 to 8.16 | +| 8.12 | 8.12 | +| 8.10.3 to 8.11 | 8.10.3 to 8.11 | +| 8.10.0 to 8.10.2 | 8.10.0 to 8.10.2 | +| 8.9.5 to 8.9.11 | 8.9.5 to 8.9.11 | +| 8.9.0 to 8.9.4 | 8.9.0 to 8.9.4 | + +Projects can be exported and imported only between versions of GitLab with matching Import/Export versions. + +For example, 8.10.3 and 8.11 have the same Import/Export version (0.1.3) +and the exports between them are compatible. + +## Related topics + +- [Project import/export API](../../../api/project_import_export.md) +- [Project import/export administration Rake tasks](../../../administration/raketasks/project_import_export.md) **(FREE SELF)** +- [Group import/export](../../group/settings/import_export.md) +- [Group import/export API](../../../api/group_import_export.md) ## Troubleshooting @@ -245,7 +245,7 @@ Review [issue 276930](https://gitlab.com/gitlab-org/gitlab/-/issues/276930), and ### Import workarounds for large repositories -[Maximum import size limitations](#import-the-project) +[Maximum import size limitations](#import-a-project-and-its-data) can prevent an import from being successful. If changing the import limits is not possible, you can try one of the workarounds listed here. |