从混乱到完美流程：我在 GitLab 上自动化一次巨大的真实迁移（4000 个仓库）的经验

Source: Dev.to

为什么必须进行这次迁移

GitLab Community Edition 在开始时运行良好。但当团队规模扩大、仓库增多、流水线数量激增时，会出现明显的限制：

• 缺乏治理
• 配置不一致
• 运行器多样化
• 流水线不稳定
• 缺少关键企业资源

迁移到 GitLab Enterprise Edition 不仅是技术上的改进，更是组织成熟度提升的一步。

挑战

没有官方迁移方案能够完整保留所有内容。

在别无选择的情况下，创建了自研方案。

是什么让这次迁移如此复杂？

迁移 4000 个项目 并不是简单的搬文件夹，而是要保留整个生态系统，包括以下要素：

• 完整的提交历史
• 受保护的分支
• 发布标签
• 变量和密钥
• 含有分散 includes 的流水线
• 议题和评论
• 归档状态
• 运行器和权限

GitLab 原生的导入/导出工具在此过程中会丢失大部分信息。我需要构建一个可靠的自动化工具来完整迁移所有内容。

构建桥梁的工具包

已开发一套基于 Bash 的模块化脚本，以确保对迁移的每个环节都拥有绝对控制。它已在此发布：

👉

两层架构

Git 层 – 负责：

• 克隆所有仓库
• 重建分支
• 确保 DAG 的完整性
• 完全保留标签（与 CE 完全一致）
• 重新配置 remote
• 重新应用归档状态

API 层 – 负责：

• 变量和密钥
• Issues 与评论
• 组层级结构
• 权限
• 在目标端重新创建项目

每个脚本只做一件事，但做到精准。脚本包括：

• clone-projects.sh
• replace_gitlab-ci.sh
• push_projects.sh
• migrar-variaveis.sh
• migrate-issues.sh
• 用于子组的递归脚本
• 完整的 runner 清单

这是一种有目的的自动化，而非魔法。

隐藏出现的混乱

官方文档有帮助，但仅限于部分。许多部分不一致、不完整，或者在大规模应用时根本不按描述工作。

此外，我发现了以下问题：

• includes 的 pipeline 使用绝对路径，迁移后会中断
• 重复的变量，缺乏作用域或组织混乱
• 旧的 runner 配置不可预测
• 已归档的项目在官方导入时重新出现为活跃状态
• 标签被错误地重新创建

采用标准流程可能会在整个组织内造成严重的运营影响。

试点测试…以及拯救迁移的错误

为了确保一切正常，我在隔离环境中运行了多个试点测试。所有测试，毫无例外，在开始时都出现了错误。

发现的故障示例

include: /old-group/subgroup/template.yml

• 因旧的 includes 导致流水线破裂
• 缺失的变量导致作业失败
• runner 拒绝执行
• 由于不可见的细节导致 YAML 无效
• 标签消失或被错误地重新创建
• 层级顺序错乱

这些错误正是最终成功的原因。

[Image: Erro de pipeline]

我如何缓解这些问题

为了解决因旧的 includes 导致的流水线破裂，我编写了一个脚本，递归分析本地克隆的文件夹中的每个 include，并在新 GitLab 中创建新路径时自动添加新路径。

每一次故障都揭示了 GitLab 的真实行为。错误教会的东西比任何文档都多。每次测试时：

• 添加新的验证
• 创建过滤器
• 加强日志记录
• 修复特殊情况
• 添加幂等性检查

当测试最终全部通过且没有错误时，自动化证明了其真正的可靠性。

实际迁移日

当完整的迁移流水线执行时，结果完全符合成功工程场景的预期：

• 没有历史丢失
• 没有标签损坏
• 流水线正常运行
• 变量以正确的作用域重新创建
• 层级结构保持不变
• 代码正确到达目标
• 已归档的仓库保持归档状态
• Runner 均匀运行

这就像把一个混乱的系统转变为可预测、标准化且受治理的环境。

这对团队的影响

即使在开始时没有正式的 DORA 测量，迁移后的行为也很明显。

[Image: Métricas DORA]

观察到的结果

• 部署 更加频繁
• 交付时间 大幅下降
• 流水线 更加稳定
• 变更失败率 降低
• 标准化的 Runner 减少了奇怪的错误
• 由于完整的历史记录，恢复速度更快

本报告展示了模块化、测试驱动和日志导向的方法如何将大规模迁移转变为可靠且可重复的过程。

[Image: Migrating GitLab Projects]

整个组织开始加速运转

这次经验教会了我

• 官方文档永远不可能覆盖 100 % 的情况
• 标准化是可靠性的基础
• 流水线深度依赖变量
• Runner 决定 CI/CD 的隐形健康状态
• 错误在工程中扮演关键角色
• 做好自动化能建立信任

最重要的一课：
当你重构基础设施时，整个开发流程都会得到提升。

结论

迁移成千上万的项目不仅仅是技术挑战。
这是一场对纪律、工程和韧性的考验。

通过确定性自动化、真实的试点测试以及从错误中学习，成功安全地迁移了约 4 000 个仓库，保持了代码、流水线、历史和治理的完整性。

值得强调的是项目未来的演进可能性。用 Python 进行重写被视为自然的阶段，能够提供更大的灵活性和代码流畅性，同时不忽视当前在 Bash 中实现的解决方案的效率和稳健性。

该解决方案已公开，可作为面临类似挑战的其他人的基础：

⭐ 如果你喜欢这个项目，请在 GitHub 上给它点一个 ⭐ 星 ⭐——这对加强和提升工作价值有很大帮助。

👉

如果你正在计划一次大型迁移，请记住：

错误不是敌人。
它们是指引。

而做好自动化可以将恐惧转化为信心。

📚 参考文献

• GitLab 文档 –
• GitLab 导入/导出指南 –
• GitLab API 参考 –
• Google Cloud – DORA 研究与四大关键指标 –
• Accelerate：DevOps 状态报告（DORA） –
• Martin Fowler – 持续交付与基础设施即代码 –
• Google SRE 书籍 – 消除重复工作与可靠性工程 –
• Pro Git 书籍 – Git 内部原理 –
• 高级 Bash 脚本指南 –
• GitHub Engineering – 迁移与自动化洞察