doc/user/import/gitlab_instances/offline-transfer-migrations.md
{{< details >}}
{{< /details >}}
{{< history >}}
offline_transfer_exports, offline_transfer_imports, and offline_transfer_ui. Disabled by default.{{< /history >}}
[!flag] The availability of this feature is controlled by feature flags. For more information, see the history. This feature is available for testing, but not ready for production use.
Offline transfer copies GitLab groups and projects between instances through object storage, without a direct network connection between the source and destination instances. The source instance exports data to a storage bucket, and the destination instance imports the data from a bucket it can read.
Unlike migration by direct transfer, which requires the destination instance to connect to the source instance, offline transfer decouples the export and import. The export bucket and import bucket do not have to be the same bucket, or use the same object storage provider. If the destination instance cannot access the export bucket, move the export files to a bucket the destination can access. GitLab does not move these files for you.
Offline transfer is gated by both feature flags and application settings. All of them are off by default, and for a given operation both layers must be on:
offline_transfer_exports_enabled application setting.offline_transfer_imports_enabled application setting.To perform exports and imports, use the offline transfer REST API. Support offline transfers in the GitLab UI is proposed in work item 19870.
To create an offline transfer export, the source instance must run GitLab 19.3 or later. To import an export, the destination instance must run GitLab 19.3 or later.
Every export records the version of the source instance that created it. If that version is earlier
than the minimum version the destination instance supports, the import fails with an
Unsupported GitLab version error.
Offline transfer supports these object storage providers:
| Provider | Description |
|---|---|
| AWS S3 | Amazon S3 object storage. |
| S3-compatible | MinIO and other S3-compatible providers. Requires an administrator to turn on S3-compatible object storage. |
| Google Cloud Storage (service account) | Google Cloud Storage authenticated with a service account JSON key. |
| Google Cloud Storage (HMAC) | Google Cloud Storage authenticated with S3-interoperability HMAC keys. |
| Google Cloud Storage with Application Default Credentials | Google Cloud Storage authenticated with Application Default Credentials (ADC). Restricted to administrators and to specific buckets, and not available on GitLab.com. For more information, see Application Default Credentials. |
The object storage credentials you provide must have the following permissions.
For AWS S3:
s3:PutObject and s3:ListBuckets3:GetObject and s3:ListBucketFor Google Cloud Storage with a service account:
storage.buckets.get, storage.objects.create, and storage.objects.liststorage.objects.getGoogle Cloud Storage with ADC needs the same permissions, held by the service account of the instance instead of by a key you supply.
Google Cloud Storage HMAC keys authenticate through the S3 interoperability API, so they require the
AWS S3 permissions listed above rather than the storage.* permissions.
Permissions for other S3-compatible providers vary by provider. Configure your provider with read and write permissions equivalent to the AWS S3 permissions listed above.
Google Cloud Storage with ADC authenticates as the service account of the instance that runs GitLab,
not as the user who starts the transfer. Because that service account is usually more privileged than
any individual user, GitLab restricts ADC transfers to administrators and to buckets whose name
starts with gitlab-offline-transfer-.
An administrator must also turn on ADC for the instance. For the security implications and the full list of restrictions, see Allow application default credentials for offline transfer.
Offline transfer imports the same group and project items as migration by direct transfer. For the full list, see migrated group items and migrated project items.
The following items are not imported by offline transfer:
When you import a group, its subgroups and projects are always imported if they are present in the export.
Offline transfer never creates real users on the destination instance. Instead, imported contributions are mapped to placeholder users. After the import finishes, reassign the placeholder users to users on the destination instance.
Because offline transfer does not import group and project memberships, you must add members to the imported groups and projects yourself.
Offline transfer applies the same visibility rules as migration by direct transfer. For more information, see visibility rules.
Prerequisites:
To migrate a group or project:
Offline transfer exports and imports are rate limited. For more information, see non-configurable rate limits.