GitLab 导入/导出仓库

这是一篇可直接落地的实操手册，覆盖管理员开启导入/导出、按 URL 导入、Manifest 批量导入、命令行镜像迁移、项目/群组导出等常见场景。适用于自建 GitLab（Self‑Managed）或 GitLab.com。

一、何时需要「导入 / 导出」？

把 Gitblit / Gitea / GitHub / 其他 Git 服务器的仓库迁到 GitLab。
跨实例迁移（A GitLab → B GitLab）。
批量搬家（几十上百个仓库）。
归档/备份（导出项目或整个组）。

二、术语速览

Repository by URL（按 URL 导入） ：在建项目时给出源仓库的 Git URL ，GitLab 自动把 Git 历史（commit/branch/tag） 拉进来。
Manifest file（清单文件导入） ：上传一个 Android repo manifest 兼容的 XML，批量导入多个仓库。
Mirror（镜像）迁移 ：用原生 Git 命令 --mirror 完整推送全部 refs，最稳妥、可控。
项目/组导出 ：把项目（或组）的 代码+元数据 打成一个归档，以便导入到另一个 GitLab。
Direct transfer（直接传输）：在两个 GitLab 之间直接迁移项目/组（新版本提供）。

三、管理员：先开启导入 / 导出能力

只有管理员（Admin）能改系统级设置，普通用户按本文后文"导入/导出"步骤操作即可。

登录 Admin / 管理员后台。
进入：Settings → General → Import and export settings。
在该区域：
- 打开你需要的 Import sources （例如 Repository by URL 、Manifest file 等）。
- 需要跨实例直连迁移时，启用 Allow migrating GitLab groups and projects by direct transfer。
保存设置。

不同版本菜单名称/位置略有差异，关键词是 "Import and export settings / Import sources / Direct transfer"。

四、导入到 GitLab 的三种常用方式

方式 A：按 URL 导入（最省事）

适用：少量仓库，从任意 Git 服务器拷贝 Git 历史 到 GitLab。

步骤：

顶部/侧边栏：New project / 新建项目。
切换到 Import project 选项卡。
选择 Repository by URL。
填写：
- Git repository URL（源仓库地址，HTTP(S)/SSH 均可）。
- 目标 项目名称 & 路径 、目标 Group（群组）。
- 如需认证，填能拉取该仓库的 账户/密码 或 访问令牌。
创建项目，等待导入完成。

特点与注意：

导入的是 Git 历史（分支/标签） ；不包含 源平台的 Issue/MR 等（若需要迁元数据，见下文"项目/组导出"或"Direct transfer"）。
超大仓库可能超时，可优先用 镜像迁移（方式 C）。

方式 B：Manifest 文件批量导入（批量仓库推荐）

适用：一次性把 很多仓库 从同一源拉进一个 Group。

步骤：

New project → Import project → Manifest file。
上传 manifest XML ，选择要导入到的 目标 Group。
点击 List available repositories ，在列表页 Import all repositories 或逐个导入。

Manifest 样例（按需修改路径/分支）：

xml 复制代码

<?xml version="1.0" encoding="UTF-8"?>
<manifest>
  <!-- 指向源 Git 服务器根地址（示例为 Gitblit/Gitea 等） -->
  <remote name="origin" fetch="https://git.example.com/" />
  <default remote="origin" revision="master" />

  <!-- name 为相对路径（根据你的服务器路径填写），path 为导入到 GitLab 后的子目录（可选） -->
  <project name="r/project1.git" path="project1" />
  <project name="r/libs/libA.git" path="libs/libA" />
  <project name="groupX/repoB.git" path="repoB" />
</manifest>

优点：一次性导入清单中的多个仓库，结构清晰。

方式 C：命令行镜像迁移（最稳妥，强烈推荐）

适用：想 100% 保留 所有 refs （所有分支、标签、notes 等），或需要 可控/可复现 的迁移流程。

单仓库示例：

bash 复制代码

# 1) 从源服务器做「裸克隆镜像」
git clone --mirror https://git.source.com/group/repo.git
cd repo.git

# 2) 推送到 GitLab 新建的空项目（先在 GitLab 创建空仓库拿目标URL）
git push --mirror https://gitlab.example.com/group/repo.git
cd ..

批量迁移脚本（repos.txt 每行：源URL 空格目标URL）：

bash 复制代码

#!/usr/bin/env bash
set -euo pipefail

while read -r src dst; do
  name=$(basename "$src" .git)
  echo "[MIGRATE] $name"
  rm -rf "$name".git
  git clone --mirror "$src" "$name".git
  git -C "$name".git remote set-url --push origin "$dst"
  git -C "$name".git push --mirror
  echo "[DONE] $name"
done < repos.txt

优点：

全量、完整、可重复。
对超大仓库更稳（可在你可控的机器上执行，与 GitLab UI 超时无关）。

导入来源一览

下图页面里常见的导入入口及适用场景汇总如下：

导入来源	迁移内容（概括）	适用场景	备注
GitLab 导出	从另一个 GitLab 导出的归档包；可带代码与大部分元数据（Issue/MR/Wiki 等，视版本而定）	GitLab ↔ GitLab 迁移、备份/恢复	需要源端先执行项目/组导出；也可用 Direct transfer 直迁
GitHub	仓库代码历史，且可迁部分元数据（Issue/PR/标签等，取决于权限与版本）	从 GitHub 搬到 GitLab	需在 Admin 启用对应 Importer，并配置 OAuth/Token
Bitbucket Cloud	仓库与部分元数据	从 Bitbucket Cloud 迁移	需配置凭证
Bitbucket Server	仓库与部分元数据	从 Bitbucket Server/Data Center 迁移	需配置凭证
FogBugz	主要是工单相关数据映射（代码需单独迁）	老系统工单迁移	使用频率低，按官方映射字段为准
Gitea	仓库代码历史（部分版本也支持 issues）	从 Gitea 搬到 GitLab	需在 Admin 启用并配置访问令牌
仓库（URL）	仅 Git 历史（分支/标签）	从任意 Git 服务器快速导入少量仓库	不含 Issue/MR 等元数据；最通用、最省事
Manifest 文件	按清单批量导入多个仓库的 Git 历史	大批量迁移；按目录结构导入	使用 Android repo manifest 兼容 XML，仅迁代码

另：Direct transfer（直接传输） 在 Admin → Import and export settings 启用后，会在 GitLab↔GitLab 之间提供"直迁"入口，适合带元数据的同产品迁移。

五、从 GitLab 导出（备份/跨实例迁移）

5.1 导出「单个项目」

路径：进入项目 → Settings → General → Advanced → 点击 Export project。

导出完成后，可在页面 下载导出包 ，或通过 邮件链接 下载。
在另一个 GitLab 实例：New project → Import project → GitLab export 进行导入。

5.2 导出/导入「群组」

群组可用 UI（视版本而定）或 Group Import/Export API 导出结构并导入到新位置。
与 项目级导入/导出 配合，可最大限度保留组‑项目关系（如组级配置、epic 关联等）。

5.3 直接传输（Direct transfer）

新版本支持 GitLab ↔ GitLab 之间 直接迁移 项目或组。需要管理员在 Import and export settings 中启用。

六、迁移方案选型速查表

需求	推荐方式
少量仓库，尽快迁，主要要代码历史	方式 A：Repo by URL
批量很多仓库，从同一源批量拷贝	方式 B：Manifest
最严格：必须保留全部 refs、可控可重试	方式 C：Git --mirror
需要连同元数据（Issue/MR/Wiki 等）从 GitLab→GitLab	项目/组导出或 Direct transfer
需要 API/流水线自动化	方式 D：API 或方式 C + 脚本

七、常见问题与避坑

Repo by URL 不包含 Issue/MR ：如需带元数据迁移，用 项目导出/导入 或 Direct transfer；非 GitLab 源平台通常无法一键迁元数据。
大仓库 UI 导入超时 ：请用 镜像迁移（方式 C），或在服务器本机执行（网络带宽更高、不中断）。
证书与认证 ：源站若是 自签名证书 ，请在执行迁移的机器上把 CA 加入信任，或临时用 http:// 验证流程（仅内网）。
LFS 文件 ：确认源仓库是否使用 Git LFS 。--mirror 会同步 LFS 指针；若源没有 LFS 服务器，建议迁移后在 GitLab 开启 LFS（必要时做历史重写）。
权限与成员 ：迁移后需要在 GitLab 重新配置成员/权限/保护分支。
URL 变更与重定向：Group/项目路径改名会影响克隆地址。若老地址仍被其他系统引用，建议在旧平台保留只读期或发布通知。

八、附录：可直接用的模板

A. `repos.txt` 示例

复制代码

https://gitblit.example.com/r/core/app.git  https://gitlab.example.com/software_dev/app.git
https://gitblit.example.com/r/libs/utils.git https://gitlab.example.com/software_dev/utils.git

B. 批量镜像脚本（Linux/macOS，Windows 可用 Git Bash）

bash 复制代码

#!/usr/bin/env bash
set -euo pipefail

: "${REPOS_FILE:=repos.txt}"  # 可通过环境变量指定清单文件

while read -r src dst; do
  [[ -z "$src" || "$src" =~ ^# ]] && continue
  name=$(basename "$src" .git)
  echo "==== Migrating $name ===="
  rm -rf "$name".git
  git clone --mirror "$src" "$name".git
  git -C "$name".git remote set-url --push origin "$dst"
  git -C "$name".git push --mirror
  echo "==== Done $name ====\n"
done < "$REPOS_FILE"

C. Manifest XML 模板

xml 复制代码

<?xml version="1.0" encoding="UTF-8"?>
<manifest>
  <remote name="origin" fetch="https://git.example.com/" />
  <default remote="origin" revision="master" />

  <!-- 每个要导入的仓库一条 -->
  <project name="r/project1.git" path="project1" />
  <project name="groupX/repoB.git" path="services/repoB" />
</manifest>

结语

少量仓库，URL 导入最快；
批量就用 Manifest；
要求稳妥可控，Git --mirror 永远是王道；
同是 GitLab 之间，优先考虑 导出/导入 或 Direct transfer。

GitLab 导入/导出仓库

GitLab 导入/导出仓库

一、何时需要「导入 / 导出」？

二、术语速览

三、管理员：先开启导入 / 导出能力

四、导入到 GitLab 的三种常用方式

方式 A：按 URL 导入（最省事）

方式 B：Manifest 文件批量导入（批量仓库推荐）

方式 C：命令行镜像迁移（最稳妥，强烈推荐）

导入来源一览

五、从 GitLab 导出（备份/跨实例迁移）

5.1 导出「单个项目」

5.2 导出/导入「群组」

5.3 直接传输（Direct transfer）

六、迁移方案选型速查表

七、常见问题与避坑

八、附录：可直接用的模板

A. repos.txt 示例

B. 批量镜像脚本（Linux/macOS，Windows 可用 Git Bash）

C. Manifest XML 模板

结语

A. `repos.txt` 示例