GitLab Import and Export

Teams move projects for many reasons: a new company server, a merger, a backup copy, or a switch from another platform. GitLab includes tools to export a project as a file, import it elsewhere, and bring projects in from other services.

Think of moving house. You pack boxes (export), carry them to the new address, and unpack (import). Some items travel in the boxes, and some need a separate trip.

Movement Paths

  ┌────────────────┐   export file   ┌────────────────┐
  │ GitLab project │ ──────────────► │ Another GitLab │
  └────────────────┘                 │ instance       │
                                     └────────────────┘
  ┌────────────────┐   import tool   ┌────────────────┐
  │ GitHub,        │ ──────────────► │ GitLab project │
  │ Bitbucket,     │                 └────────────────┘
  │ Gitea          │
  └────────────────┘
  ┌────────────────┐   repository URL ┌───────────────┐
  │ Any Git server │ ───────────────► │ GitLab project│
  └────────────────┘                  └───────────────┘

Export a Project

1. Open the project and select Settings → General.
2. Expand Advanced.
3. Select Export project.
4. Wait for the email that says the export is ready.
5. Download the archive from the email link or from the same settings page.

The archive is a compressed file that holds the project in a structured format.

What the Export Contains

Included	Left Out
Git repository and branches	CI/CD variables
Issues and comments	Container registry images
Merge requests and discussions	Job logs and artifacts
Labels and milestones	Webhooks and pipeline triggers
Wiki pages	Encrypted tokens
Snippets and releases	Merge request approvers

Recreate the left-out items by hand at the new location. Copy variable names from the old project before you leave.

Import a GitLab Export

1. Select New project from the top bar.
2. Choose Import project.
3. Select GitLab export.
4. Type a project name and slug.
5. Upload the archive file.
6. Select Import project.

The page shows progress. Large projects take several minutes.

Import from Other Services

Source	Method	What Moves
GitHub	Connect with a personal access token	Repository, issues, pull requests, and comments
Bitbucket Cloud	Connect through an authorization prompt	Repository, issues, and pull requests
Gitea	Personal access token	Repository, issues, and pull requests
Any Git server	Repository by URL	Git history only

Create the token with read-only repository access at the source service. Delete the token after the import finishes.

Import by URL

1. Select New project → Import project → Repository by URL.
2. Paste the Git address, such as https://example.com/team/app.git.
3. Add credentials if the repository is private.
4. Pick a name and visibility level.
5. Select Create project.

Move a Repository with Git Only

Two commands copy every branch and tag when no other data needs to travel.

git clone --mirror https://old-server.example.com/team/app.git
cd app.git
git push --mirror git@gitlab.com:my-group/app.git

Create an empty project on GitLab before the push. A mirror push overwrites everything in the target.

Migrate Whole Groups

Group migration by direct transfer copies a group with its subgroups and projects from one GitLab instance to another.

1. Create an access token on the source instance with the api scope.
2. Open the destination instance and select New group → Import group.
3. Enter the source address and the token.
4. Choose the groups and projects to bring.
5. Start the import and watch the status table.

Plan the Migration

  1. List projects and owners
        ↓
  2. Announce a freeze on changes
        ↓
  3. Export or import a test project
        ↓
  4. Check issues, branches, and wikis
        ↓
  5. Move the remaining projects
        ↓
  6. Recreate variables, runners, and webhooks
        ↓
  7. Update remote URLs on developer computers
        ↓
  8. Archive the old projects

Update Developer Remotes

After a move, every developer points the local copy to the new address.

git remote set-url origin git@new-gitlab.example.com:my-group/app.git
git remote -v

Check the Result

• Compare issue counts and merge request counts between old and new projects.
• Run the pipeline once and confirm that it passes.
• Confirm members and their roles.
• Test a clone, a push, and a merge request.
• Keep the old project read-only for a few weeks as a safety net.

Common Problems

Problem	Fix
Export file exceeds the upload limit	Ask the administrator to raise the import size limit
Users appear as the importer	Match source users to destination accounts before the import
Import fails with a version error	Move to a destination at the same version or newer
Pipeline fails after import	Add the missing variables and register runners