doc/user/project/settings/import_export.md
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
File exports give you a portable package of your GitLab data that works in offline environments. This migration method preserves most project data, including repositories, issues, merge requests, and comments.
Use file exports to:
Direct transfer remains the recommended migration method for most situations.
[!note] You should not use project export files to back up your data. Using project export files for backups does not always work, and not all items are exported.
PG::QueryCanceled: ERROR: canceling statement due to statement timeout error.
For more information, see the
troubleshooting documentation.18.0 will become 18.0 (imported-3d-1770206299). To avoid this, rename the milestone in the source group or project before initiating a direct transfer.Existing projects can be exported to a file and then imported into another GitLab instance.
The requirements for preserving user contribution depends on whether you're migrating to GitLab.com or to a GitLab Self-Managed instance.
When migrating projects by using file exports, an administrator's access token is required for user contributions to map correctly.
Therefore, user contributions never map correctly when importing file exports from a GitLab Self-Managed instance to GitLab.com. Instead, all GitLab user associations (such as comment author) are changed to the user importing the project. To preserve contribution history, do one of the following:
To ensure GitLab maps users and their contributions correctly:
When the email of an existing user matches the email of an imported user, that user is added as a direct member to the imported project.
If any of the previous conditions are not met, user contributions are not mapped correctly. Instead, all GitLab user associations are changed to the user who performed the import. That user becomes an author of merge requests created by other users. Supplementary comments mentioning original authors are:
You can add or remove data from export files. For example, you can:
project_members.ndjson file.ci_pipelines.ndjson file.To edit a project export file:
.tar.gz file.tree/project/project_members.ndjson..tar.gz file.You can also make sure that all members were exported by checking the project_members.ndjson file.
{{< history >}}
{{< /history >}}
Project file exports are in NDJSON format.
You can import project file exports that were exported from a version of GitLab up to two minor versions behind.
For example:
| Destination version | Compatible source versions |
|---|---|
| 13.0 | 13.0, 12.10, 12.9 |
| 13.1 | 13.1, 13.0, 12.10 |
{{< details >}}
{{< /details >}}
Before you can migrate projects on GitLab Self-Managed using file exports, GitLab administrators must:
To enable file exports as an import source for the destination instance:
You can export projects from the Community Edition to the Enterprise Edition and vice versa, assuming compatibility is met.
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 reverting from EE to CE.
Before you can import a project, you must export it.
Prerequisites:
To export a project and its data, follow these steps:
The export is generated in your configured shared_path, a temporary shared directory
(by default, <shared_path>/tmp/gitlab_exports), and then either:
uploads_directory.Every 24 hours, a worker deletes these export files.
On GitLab instances with separate Sidekiq, Gitaly, and GitLab application (Rails) nodes,
the directory specified in the
shared_path
setting must be available to all nodes.
Exported project items depend on the version of GitLab you use. To determine if a specific project item is exported:
exporters array.project/import_export.yml
file for projects for your GitLab version. For example, https://gitlab.com/gitlab-org/gitlab/-/blob/16-8-stable-ee/lib/gitlab/import_export/project/import_export.yml for GitLab 16.8.For a quick overview, items that are exported include:
Items that are not exported include:
You can import a project and its data. The amount of data you can import depends on the maximum import file size:
[!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.
{{< history >}}
{{< /history >}}
tar command must be installed on both the source and destination GitLab instances.To import a project:
You can query the status of an import by using the API. The query might return an import error or exceptions.
Exported items are imported with the following changes:
Internal visibility level is restricted,
all imported projects are given Private visibility.Deploy keys aren't imported. To use deploy keys, you must enable them in your imported project and update protected branches.
{{< details >}}
{{< /details >}}
If you have a larger project, consider using a Rake task.
{{< details >}}
{{< /details >}}
Administrators can set the maximum import file size one of two ways:
max_import_size option in the Application settings API.The default is 0 (unlimited).
To help avoid abuse, by default, users are rate limited to:
| Request type | Limit |
|---|---|
| Export | 6 projects per minute |
| Download export | 1 download per project per minute |
| Import | 6 projects per minute |
{{< history >}}
{{< /history >}}
[!warning] This feature was deprecated in GitLab 14.6 and replaced by migrating groups by direct transfer. However, this feature is still recommended for migrations in offline environments. Support for migration between offline instances is proposed in epic 8985.
Prerequisites:
Using file exports, you can:
GitLab maps user contributions correctly when an admin access token is used to perform the import. GitLab does not map user contributions correctly when you are importing from a GitLab Self-Managed instance to GitLab.com. Correct mapping of user contributions when importing from a GitLab Self-Managed instance to GitLab.com can be preserved with paid involvement of Professional Services team.
private visibility level, unless imported into a parent group.The maximum import file size depends on whether you import to GitLab Self-Managed or GitLab.com:
max_import_size option in the Application settings API.{{< history >}}
{{< /history >}}
Group file exports are in NDJSON format.
You can import group file exports that were exported from a version of GitLab up to two minor versions behind.
For example:
| Destination version | Compatible source versions |
|---|---|
| 13.0 | 13.0, 12.10, 12.9 |
| 13.1 | 13.1, 13.0, 12.10 |
The import_export.yml
file for groups lists items exported and imported when migrating groups using file exports. View this file in the branch
for your version of GitLab to check which items can be imported to the destination GitLab instance. For example,
import_export.yml on the 16-8-stable-ee branch.
Group items that are exported include:
Items that are not exported include:
Prerequisites:
To export the contents of a group:
To import the group:
To help avoid abuse, by default, users are rate limited to:
| Request Type | Limit |
|---|---|
| Export | 6 groups per minute |
| Download export | 1 download per group per minute |
| Import | 6 groups per minute |