从零到一搭建 **多仓库项目（Repo Manager 架构）** 完整步骤

这套架构 = Git 子模块 + Manifest 版本管理 + Gitee CI 自动更新 + 自动提交推送

一、整体架构说明

你最终会得到：

主仓库（父项目）：管理所有子模块、版本、CI
子模块仓库 N 个：公共库、业务模块、工具库等
manifest.json：统一锁定所有子模块的版本（Tag/Commit/分支）
Gitee CI：自动更新子模块 → 自动提交 → 自动推送
一键脚本：本地同步、更新、提交

二、第 1 步：创建主仓库（父项目）

在 Gitee 新建一个空仓库，例如：
my-multi-repo-project

本地初始化

bash 复制代码

mkdir my-multi-repo-project
cd my-multi-repo-project
git init

创建基础文件

bash 复制代码

touch README.md
touch .gitignore

提交并推送到 Gitee

bash 复制代码

git add .
git commit -m "init: 多仓库主项目初始化"
git remote add origin 你的主仓库Gitee地址
git push -u origin main

三、第 2 步：添加子模块（业务库/公共库）

假设你有 3 个子模块：

common-lib（公共组件）
biz-module（业务模块）
tool-kit（工具库）

添加命令（每条执行一次）

bash 复制代码

git submodule add https://gitee.com/xxx/common-lib modules/common-lib
git submodule add https://gitee.com/xxx/biz-module modules/biz-module
git submodule add https://gitee.com/xxx/tool-kit modules/tool-kit

执行后会自动生成：

.gitmodules：子模块地址、路径配置
所有子模块会被克隆到 modules/ 目录

提交子模块

bash 复制代码

git add .gitmodules modules/
git commit -m "submodule: 添加所有子模块"
git push

四、第 3 步：创建 manifest.json（版本锁定核心）

在主仓库根目录创建：manifest.json

json 复制代码

{
  "submodules": [
    {
      "name": "common-lib",
      "path": "modules/common-lib",
      "url": "https://gitee.com/xxx/common-lib",
      "version": "v1.0.0",
      "type": "tag"
    },
    {
      "name": "biz-module",
      "path": "modules/biz-module",
      "url": "https://gitee.com/xxx/biz-module",
      "version": "main",
      "type": "branch"
    },
    {
      "name": "tool-kit",
      "path": "modules/tool-kit",
      "version": "a1b2c3d",
      "type": "commit"
    }
  ],
  "baseBranch": "main",
  "updatePolicy": "auto"
}

作用：

统一管理所有子模块版本
CI/脚本根据它自动更新
团队协作不会乱版本

提交：

bash 复制代码

git add manifest.json
git commit -m "manifest: 版本锁定配置"
git push

五、第 4 步：编写自动更新脚本（核心！）

创建脚本：scripts/update-submodules.sh

bash 复制代码

#!/bin/bash
set -e

# 读取 manifest.json
echo "== 开始根据 manifest 更新子模块 =="

# 遍历子模块
cat manifest.json | jq -r '.submodules[] | .path + "|" + .version + "|" + .type' | while IFS="|" read -r path ver type; do
  echo "
====================================
更新模块: $path"
  cd $path

  git fetch --all

  if [ "$type" = "tag" ]; then
    git checkout tags/$ver
  elif [ "$type" = "branch" ]; then
    git checkout $ver && git pull
  elif [ "$type" = "commit" ]; then
    git checkout $ver
  fi

  cd - > /dev/null
done

echo "== 子模块全部更新完成 =="

# 自动提交到主仓库
echo "== 提交子模块新版本 =="
git add .gitmodules modules/ manifest.json
git commit -m "submodule: auto update to latest version [CI]"
git push

安装依赖（仅第一次）

bash 复制代码

sudo apt install jq -y

赋予执行权限

bash 复制代码

chmod +x scripts/update-submodules.sh

本地测试

bash 复制代码

./scripts/update-submodules.sh

✅ 成功后：

所有子模块自动更新到 manifest 指定版本
自动提交、自动推送

六、第 5 步：接入 Gitee CI/CD（自动更新）

创建文件：.gitee-ci.yml

yaml 复制代码

# Gitee CI 自动更新子模块
name: SubModule Auto Updater

on:
  push:
    branches: [main]
  schedule:
    - cron: '0 0 * * *'  # 每天凌晨自动更新
  workflow_dispatch:     # 支持手动触发

jobs:
  update-submodules:
    runs-on: ubuntu-latest
    steps:
      - name: 拉取代码
        uses: actions/checkout@v4
        with:
          submodules: true
          token: ${{ secrets.GITEE_TOKEN }}

      - name: 安装依赖
        run: sudo apt install jq -y

      - name: 执行更新脚本
        run: chmod +x scripts/update-submodules.sh && ./scripts/update-submodules.sh

      - name: 推送更新
        uses: ad-m/github-push-action@master
        with:
          branch: main
          github_url: https://gitee.com
          token: ${{ secrets.GITEE_TOKEN }}

配置 GITEE_TOKEN

Gitee → 设置 → 安全设置 → 私人令牌
生成令牌（勾选 repo、projects、workflow）
主仓库 → 管理 → 密钥与变量 → 新增密钥
- 名称：GITEE_TOKEN
- 值：你的令牌

提交 CI 文件：

bash 复制代码

git add .gitee-ci.yml
git commit -m "ci: 子模块自动更新流水线"
git push

✅ 现在你的项目具备：

每天自动更新子模块
手动一键更新
自动提交、自动推送
版本完全由 manifest 控制

七、第 6 步：团队协作规范（Repo Manager 模式）

给你一套最稳定的使用规则：

1. 新成员克隆项目

bash 复制代码

git clone 主仓库地址 --recursive

2. 日常同步

bash 复制代码

git pull
git submodule update --init --recursive

3. 升级子模块版本

只需要修改 manifest.json

然后执行：

bash 复制代码

./scripts/update-submodules.sh

4. CI 自动更新

每天自动跑，无需人工操作

八、最终项目目录结构（标准）

复制代码

my-multi-repo-project/
├── modules/                # 所有子模块
│   ├── common-lib/
│   ├── biz-module/
│   └── tool-kit/
├── scripts/
│   └── update-submodules.sh  # 自动更新脚本
├── manifest.json           # 版本锁定（核心）
├── .gitmodules
├── .gitee-ci.yml           # Gitee 自动构建
└── README.md

九、你获得的能力

✅ Git 子模块管理多仓库

✅ Manifest 统一锁定版本

✅ 按 Tag / Branch / Commit 更新

✅ 本地一键更新

✅ Gitee CI 自动更新、自动提交、自动推送

✅ 类 AOSP Repo 管理模式

✅ 团队协作不乱版本