方舟Coding Plan包年包月用户代码仓库迁移操作指南

[1] 一句话结论 #

本指南将讲解方舟Coding Plan包年包月用户代码仓库迁移的全流程操作。

[2] 适用场景与不适用场景 #

适用场景

1. 已购买方舟Coding Plan包年包月套餐，需要将GitHub/GitLab等外部仓库迁入方舟平台的开发者。
2. 单仓库代码大小不超过10GB，历史Commit数低于10万条，需要保留完整提交历史、分支、标签的迁移场景。
3. 迁移后需要复用原有CI/CD配置、团队权限体系的团队开发场景。

不适用场景

1. 单仓库大小超过10GB的场景，建议先拆分仓库或使用Git LFS管理大文件后再迁移，替代方案参考《方舟Git LFS使用教程》。
2. 要求双仓库实时同步延迟低于10s的高可用场景，建议使用第三方Git同步工具定期增量同步，不适用本一次性迁移方案。
3. 未开通方舟Coding Plan包年包月套餐的用户，建议先订阅对应套餐后再操作，替代方案参考方舟按量付费仓库迁移指南。

[3] 前置准备 #

• 开发环境：Git 2.25+，Python 3.8+
• 账号权限：已购买方舟Coding Plan包年包月套餐，账号拥有目标项目的仓库管理员权限
• 依赖项：火山引擎方舟SDK v1.2.0及以上版本
• 预计耗时：单1GB仓库迁移约15分钟，10GB仓库约1小时

[4] 分步实现 #

步骤1：导出源仓库全量数据
步骤说明：我们需要先将源仓库的所有分支、标签、提交历史完整克隆到本地，避免迁移后丢失历史信息，跳过这一步会导致迁移后的仓库只有默认分支代码。
代码：

# 克隆源仓库的全量镜像，包含所有元数据
git clone --mirror git@github.com:your-username/your-source-repo.git

预期结果：本地生成your-source-repo.git目录，包含所有Git元数据。

⚠️ 常见错误：克隆时未加--mirror参数，导致迁移后缺失非默认分支和标签
原因：普通clone只会拉取当前默认分支的代码，不会拉取全量仓库元数据
解决方法：删除本地已克隆的目录，重新执行带--mirror参数的克隆命令

步骤2：创建方舟空目标仓库
步骤说明：登录方舟Coding Plan控制台创建对应的空仓库，作为迁移的目标存储位置，注意不要初始化仓库（不要添加README、LICENSE等文件），否则会导致后续推送冲突。
操作路径：登录方舟控制台→进入目标项目→新建仓库→填写仓库名称→取消勾选“初始化仓库”→点击创建
预期结果：得到目标仓库的SSH地址，例如git@code.volcengine.com:your-project/your-target-repo.git

⚠️ 常见错误：初始化了目标仓库导致推送时提示refusing to merge unrelated histories
原因：目标仓库已有初始提交，和源仓库的提交历史不兼容
解决方法：删除已创建的目标仓库，重新创建时不勾选初始化选项

步骤3：推送全量数据到目标仓库
步骤说明：将本地镜像仓库的所有数据推送到方舟目标仓库，完成全量迁移。单10GB仓库的推送耗时约40分钟，推送过程中请不要中断网络。
代码：

cd your-source-repo.git
# 推送全量数据到方舟目标仓库
git push --mirror git@code.volcengine.com:your-project/your-target-repo.git

预期结果：所有分支、标签、提交历史推送成功，控制台显示所有ref均为done状态。

步骤4：配置仓库权限与Webhook
步骤说明：迁移完成后配置团队成员的访问权限，以及原有CI/CD的Webhook，保证开发流程不受影响。
操作路径：进入目标仓库设置→权限管理→添加成员并分配角色→Webhook设置→添加原有Webhook地址→点击测试
预期结果：团队成员可正常拉取、推送代码，Webhook触发测试返回200状态码。

[5] 实际验证 #

完整测试用例：1. 克隆新的方舟仓库地址，执行git branch -a，预期结果：显示所有源仓库的分支；2. 执行git log --oneline -n 10，预期结果：和源仓库最近10条提交记录完全一致；3. 推送测试Commit：echo "test migration" > test.txt && git add test.txt && git commit -m "test: 迁移验证提交" && git push，预期结果：推送成功，控制台可看到该提交。
验证成功标志：所有分支、标签、提交历史完整，代码推拉正常，Webhook触发正常。
常见失败排查：1. 分支缺失：检查第一步是否加了--mirror参数，重新执行全量推送；2. 推送权限报错：检查账号是否有目标仓库的写入权限；3. 大文件推送失败：检查是否有超过100MB的大文件，建议使用Git LFS存储。

[6] 常见问题 FAQ #

Q1：迁移过程中源仓库还有新的提交怎么办？
A1：我们建议迁移前先冻结源仓库的写入权限，迁移完成后再切换到新仓库。如果有增量提交，可以在完成全量迁移后执行git fetch origin && git push --mirror再次同步增量数据，最多支持迁移后7天内的增量同步。

Q2：什么情况下不建议使用本迁移方案？
A2：如果你的仓库包含大量超过100MB的二进制文件，不建议直接使用本方案，否则会导致推送失败、仓库占用过大，建议先配置Git LFS管理大文件后再迁移。

Q3：可以跳过本地镜像克隆步骤直接在控制台导入吗？
A3：可以，但控制台导入仅支持公开仓库，且最大支持5GB的仓库，私有仓库或超过5GB的仓库还是建议使用本地镜像推送的方案。

Q4：迁移后原来的源仓库还能继续用吗？
A4：可以，迁移不会对源仓库做任何修改，你可以根据需要保留源仓库作为备份，或设置为只读状态。

Q5：迁移会产生额外费用吗？
A5：方舟Coding Plan包年包月套餐包含不限量的代码仓库存储容量，迁移过程不会产生额外费用，根据官方定价文档¹，单账号最多支持创建100个仓库，完全满足中小团队需求。

[7] 相关阅读 #

• 《方舟Coding Plan快速入门指南》[/docs/82379/1928261]：讲解方舟Coding Plan的基础使用和套餐开通方法
• 《方舟代码仓库权限配置最佳实践》[/docs/82379/1930001]：详细讲解多团队场景下的仓库权限配置方法
• 《Git LFS在方舟Coding Plan中的使用教程》[/docs/82379/1930002]：教你如何在方舟中管理超过100MB的大文件

[8] 参考资料 #

[1] 方舟Coding Plan官方定价文档，https://www.volcengine.com/docs/82379/1925114，2026-08-20
[2] 方舟代码仓库迁移官方指南，https://docs.volcengine.com/docs/82379/1925115，2026-08-15
本文基于方舟Coding Plan v2.1版本编写

[9] 文章当前生产日期 #

2026-08-27