# Gitlab-Sync

**Repository Path**: alvin-1998/gitlab-sync

## Basic Information

- **Project Name**: Gitlab-Sync
- **Description**: Gitlab-Sync是一款专为解决Gitlab仓库迁移问题而设计的高效、灵活的工具，它可以帮助用户在不丢失数据，轻松的迁移Gitlab中的用户、组、和项目，支持用户根据自己的需求选择迁移指定的用户、组或项目，或者一次性迁移所有用户、组和项目。
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 42
- **Forks**: 13
- **Created**: 2023-12-22
- **Last Updated**: 2025-06-20

## Categories & Tags

**Categories**: vcs

**Tags**: None

## README

# Gitlab仓库迁移工具

# 1. 简介

Gitlab-Sync是一款专为解决Gitlab仓库迁移问题而设计的高效、灵活的工具，它可以帮助用户在不丢失数据，轻松的迁移Gitlab中的用户、组、和项目，支持用户根据自己的需求选择迁移指定的用户、组或项目，或者一次性迁移所有用户、组和项目。

## 1.1 主要功能

- **用户迁移**：支持迁移指定用户或所有用户，确保用户信息完整无损地迁移到到目标仓库。
- **组迁移：**支持迁移指定的组或所有组，包括组内成员和权限信息完整无损的迁移到目标仓库。
- **项目迁移：**支持迁移指定的项目或所有项目，包括项目中的代码、提交记录、问题和合并请求等信息完整无损的迁移到目标仓库。
- **灵活配置：**用户可以根据需要灵活配置迁移规则，如：一次只迁移10个项目、或迁移组时自动迁移组下的所有项目

# 2. 约束条件

Gitlab-Sync 基于 Goland 开发和构建, 运行时环境兼容Linux（包括RHEL和Ubuntu等）、 Mac、 Windows等操作系统。为保障更好的系统运行时兼容性，请务必使用同类型操作系统环境下编译构建的二进制版本。

## 2.1 环境要求

- Gitlab-Sync运行时环境需要连接配置的Gitlab仓库地址，确保Gitlab仓库地址可以被正确访问。
- **success_push_remove_local配置等于false** 时Gitlab-Sync会将旧仓库的项目拉取到指定的目录，确保该目录磁盘有足够的可用空间。

# 3. 使用指南

## 3.1 下载安装包

- 安装包文件：gitlab-sync.tar.gz
- 解压安装包

```shell
tar -zxvf gitlab-sync.tar.gz	
#设置权限
chmod +x gitlab-sync
```

- 解压目录结构说明：

```
├── gitlab-sync                           #gitlab-sync主程序二进制文件
├── gitlab-sync.exe                       #gitlab-sync主程序(windows环境)
├── config.json                           #配置文件
```

## 3.2 修改配置文件

- 加载方式： gitlab-sync服务启动时加载生效，若变更配置文件内容，需重启服务加载更新后的配置信息。
- 相关配置：

```json
{
  "gitlab": {
    "origin_remote_url": "源仓库地址",
    "target_remote_url": "目标仓库地址",
    "down_local_path": "仓库下载到本地的路径",
    "success_push_remove_local": 成功推送到目标仓库后是否删除本地文件 true/false,
    "skip_projects": "跳过项目（不做迁移），多个项目用逗号拼接",
    "auto_skip_size_mb": "自动跳过超过大小的项目(单位MB),并会在同级目录生成一个大文件清单",
    "project_default_pull_pre_page":"项目默认每次拉取数量，默认100 最大也是100"
  },
  "originGitlab": {
    "username": "用户名",
    "password": "密码",
    "private_token": "gitlab private token"
  },
  "targetGitlab": {
    "username": "用户名",
    "password": "密码",
    "private_token": "gitlab private token",
    "parent_group": "仓库的第一级分组"
  },
  "log": {
    "log_file_path": "日志路径，为空则控制台打印",
    "open_request_log": 打开接口请求的日志 true/false
  }
}
```

## 3.3 迁移操作

- 提供三种迁移方式【迁移用户】、【迁移组】和【迁移项目】，可根据以下的命令进行迁移你想要的数据；
- Windows环境和Linux环境命令唯一的区别就是多了一个.exe后缀，如果在Windows环境下执行使用 gitlab-sync.exe xxx。

### 3.3.1 迁移用户

- 指定用户

```shell
./gitlab-sync user -d=zhangsan
```

- 全部用户

```shell
./gitlab-sync user -d=all
```

### 3.3.2 迁移组

- 指定组

```shell
./gitlab-sync group -d=test
#组下的项目一起迁移
./gitlab-sync group -d=test -p=Y
```

- 全部组

```shell
./gitlab-sync group -d=all
#组下的项目一起迁移
./gitlab-sync group -d=all -p=Y
```

### 3.3.3 迁移项目

- 指定项目

```shell
./gitlab-sync project -d=test
```

- 全部项目

```shell
./gitlab-sync group -d=all
```

- 按分页模式迁移（如：一次只迁移第一页的20个项目，或一次迁移第二页的20个项目）

```shell
#迁移0-20条
./gitlab-sync project -d=all -p=1 -s=20
#迁移20-40条
./gitlab-sync project -d=all -p=2 -s=20
```

| 命令 | 说明   |
| ---- | ------ |
| -p   | 第几页 |
| -s   | 条数   |

# 4. 注意事项

- **手动激活用户：**迁移到目标仓库的用户默认是未激活状态，管理员需要登录gitlab系统，手动激活用户。

![Snipaste_2023-12-22_10-59-32](docs/images/Snipaste_2023-12-22_10-59-32.png)

![Snipaste_2023-12-22_11-03-54](docs/images/Snipaste_2023-12-22_11-03-54.png)

- **用户密码：**因密码无法同步，所以迁移到目标仓库的用户，使用用户名作为密码（用户名长度大于8位：登录密码同用户名一致，若用户名长度小于8位：用户名+123456  ）如下表格所示：

| 用户名   | 密码       |
| -------- | ---------- |
| zhangsan | zhangsan   |
| lisi     | lisi123456 |

- 如果目标仓库中已存在相同的用户、组或者项目，迁移时不会覆盖，需要先删除目标仓库中的用户、组和项目然后再迁移。

## Gitlab工具集

- [Gitlab-Helper](https://gitee.com/alvin-1998/gitlab-helper)  Java语言-导出gitlab仓库内大项目的清单输出到Excel文件。