Skip to content

G
gitlab-ce
Commit 6fa714ee authored by Suzanne Selhorn's avatar Suzanne Selhorn
Browse files
Options

Merge branch 'docs-ctrt-project-import-export' into 'master' 

CTRT edits for project import export doc

See merge request gitlab-org/gitlab!76894
parents aeb6ed9c 6802a6da
Show whitespace changes
Inline Side-by-side
Showing with 156 additions and 153 deletions
doc/development/import_project.md
View file @ 6fa714ee
......@@ -16,7 +16,7 @@ There are several ways to import a project.
### Importing via UI
The first option is to simply [import the Project tarball file via the GitLab UI](../user/project/settings/import_export.md#import-the-project):
The first option is to simply [import the Project tarball file via the GitLab UI](../user/project/settings/import_export.md#import-a-project-and-its-data):
1. Create the group `qa-perf-testing`
1. Import the [GitLab FOSS project tarball](https://gitlab.com/gitlab-org/quality/performance-data/-/blob/master/projects_export/gitlabhq_export.tar.gz) into the Group.
......
doc/user/gitlab_com/index.md
View file @ 6fa714ee
......@@ -70,7 +70,7 @@ To back up an entire project on GitLab.com, you can export it either:
can also use the API to programmatically upload exports to a storage platform,
such as Amazon S3.
With exports, be aware of [what is and is not](../project/settings/import_export.md#exported-contents)
With exports, be aware of [what is and is not](../project/settings/import_export.md#items-that-are-exported)
included in a project export.
GitLab is built on Git, so you can back up just the repository of a project by
......
doc/user/project/import/index.md
View file @ 6fa714ee
......@@ -42,7 +42,10 @@ However, you can't import issues and merge requests this way. To retain all meta
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).
information, see the prerequisites and imporant notes in these sections:
- [Export a project and its data](../settings/import_export.md#export-a-project-and-its-data).
- [Import the project](../settings/import_export.md#import-a-project-and-its-data).
NOTE:
When migrating to GitLab.com, you must create users manually unless [SCIM](../../../user/group/saml_sso/scim_setup.md)
......@@ -56,7 +59,7 @@ Migrate the assets in this order:
1. [Projects](../../../api/projects.md)
1. [Project variables](../../../api/project_level_variables.md)
Keep in mind the limitations of the [import/export feature](../settings/import_export.md#exported-contents).
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/)
over a series of Docker pulls and pushes. Re-run any CI pipelines to retrieve any build artifacts.
......
doc/user/project/settings/import_export.md
View file @ 6fa714ee
......@@ -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.
![Export button](img/import_export_export_button.png)
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.
![Email download link](img/import_export_mail_link.png)
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
![Download export](img/import_export_download_export.png)
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).
![New project](img/import_export_new_project.png)
## 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).
![Select file](img/import_export_select_file.png)
## 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 |
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.
......
doc/user/project/settings/index.md
View file @ 6fa714ee
......@@ -324,7 +324,7 @@ Enable [Service Desk](../service_desk.md) for your project to offer customer sup
### Export project
Learn how to [export a project](import_export.md#import-the-project) in GitLab.
Learn how to [export a project](import_export.md#import-a-project-and-its-data) in GitLab.
### Advanced settings
......
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7