Import / export

Move projects and groups in and out of GitLab. Two related but distinct mechanisms: file-based "import/export" and live "bulk imports" (Direct Transfer).

File-based import/export

The classic mechanism: export a project or group to a tarball, import it elsewhere.

Concern	Location
Project export	app/services/projects/import_export/, lib/gitlab/import_export/
Project import	same, plus app/services/projects/create_service.rb
Group export	app/services/groups/import_export/, lib/bulk_imports/
Reset / cleanup	app/services/import_export_clean_up_service.rb
Schemas	lib/gitlab/import_export/project/import_export.yml, group/import_export.yml
Workers	app/workers/import_export/

The export tarball has:

• tree/ — JSON dumps of relations.
• repositories/ — git bundles.
• wiki/ — wiki repo bundle.
• uploads/ — attachments.
• LFS objects.
• Hashed-storage paths.

The schema YAMLs (lib/gitlab/import_export/project/import_export.yml) describe which relations are exportable and how. They are the source of truth for both export and import.

Bulk imports (Direct Transfer)

Live, API-to-API import without intermediate files. The source instance exposes lib/api/bulk_imports.rb and the destination pulls. This is the recommended path for migrating between GitLab instances.

Concern	Location
Service entry	app/services/bulk_imports/
Models	app/models/bulk_imports/
Workers	app/workers/bulk_imports/, lib/bulk_imports/workers/
Pipelines	lib/bulk_imports/pipelines/
Common API	lib/api/bulk_imports.rb
Internal API for source	lib/api/internal/bulk_imports/

Bulk imports run as a tree of "pipelines", each handling one entity type. They can resume after failure.

Importing from external systems

GitLab can also import from foreign forges:

• GitHub (lib/gitlab/github_import/, app/services/import/github/).
• Bitbucket Cloud (lib/bitbucket/, lib/gitlab/bitbucket_import/).
• Bitbucket Server (lib/bitbucket_server/, lib/gitlab/bitbucket_server_import/).
• Fogbugz (lib/gitlab/fogbugz_import/).
• Manifest XML (lib/gitlab/manifest_import/).
• Plain git clone URL (basic).
• GitHub Gists (lib/gitlab/github_gists_import/).
• Legacy GitHub importer (lib/gitlab/legacy_github_import/).

Each importer has its own pipeline of steps (users, repos, issues, MRs, comments, pipelines, etc.).

State

bulk_imports, bulk_import_entities, bulk_import_trackers track progress across restarts and pipeline retries.

Failure handling

Import runs are designed to be idempotent and partially resumable. On failure, the user can retry the failed entities without redoing successful work.

Related

• Source code management — what gets imported.
• Sidekiq jobs — import workers.