docs: clarify private git dependency handling

This commit is contained in:
xiaobing.wang 2026-04-15 18:35:55 +08:00
parent 695ee1a763
commit 65c19212e8

View File

@ -48,7 +48,7 @@ GitLab CI 默认依赖这些变量:
- 对外暴露方式 - 对外暴露方式
- 运行时配置结构 - 运行时配置结构
- 平台共享依赖与应用私有依赖 - 平台共享依赖与应用私有依赖
- 是否实际依赖 `git.in.chaitin.net/ai/baizhiyun/opensdk` - 是否检测到私有 Git 依赖(例如 `git.in.chaitin.net/ai/baizhiyun/opensdk`
应用仓库自己的 `README.md` 是应用运行架构的真相来源;本 skill 只定义平台接入规则。 应用仓库自己的 `README.md` 是应用运行架构的真相来源;本 skill 只定义平台接入规则。
@ -94,6 +94,12 @@ CI 导出结果固定为:
## GitLab CI 规则 ## GitLab CI 规则
### 私有 Git 依赖判定口径
下文中的“检测到私有 Git 依赖”统一指:仓库在 `go.mod`、`go.sum`、源码 import、构建脚本或 Dockerfile 构建流程中,实际引用了需要认证访问的私有 Git 仓库(例如 `git.in.chaitin.net/ai/baizhiyun/opensdk`)。
只有在检测到这类依赖时,才启用 `.netrc`、私有仓库认证,以及 `GOPRIVATE`、`GONOSUMDB`、`GONOPROXY`、`GOINSECURE`、`GIT_SSL_NO_VERIFY` 这一组私有 Go 变量;否则不要添加这些配置。
### stages ### stages
固定使用: 固定使用:
@ -117,13 +123,16 @@ CI 导出结果固定为:
- 运行在分支和 MR 上 - 运行在分支和 MR 上
- 安装当前语言栈的最小依赖 - 安装当前语言栈的最小依赖
- 如依赖私有仓库,补齐认证 - 只有检测到私有 Git 依赖时才补齐认证;否则不要引入 `.netrc`
- 使用项目原生测试入口 - 使用项目原生测试入口
Go 项目默认变量写在 `.gitlab-ci.yml``variables:` Go 项目默认变量写在 `.gitlab-ci.yml``variables:`
- `GOPROXY=https://goproxy.cn,direct` - `GOPROXY=https://goproxy.cn,direct`
- `GOSUMDB=sum.golang.google.cn` - `GOSUMDB=sum.golang.google.cn`
只有检测到私有 Git 依赖时,才额外设置这些变量:
- `GOPRIVATE=git.in.chaitin.net` - `GOPRIVATE=git.in.chaitin.net`
- `GONOSUMDB=git.in.chaitin.net` - `GONOSUMDB=git.in.chaitin.net`
- `GONOPROXY=git.in.chaitin.net` - `GONOPROXY=git.in.chaitin.net`
@ -144,11 +153,11 @@ Go 项目默认变量写在 `.gitlab-ci.yml` 的 `variables:`
- 登录 `registry.baizhi.cloud` - 登录 `registry.baizhi.cloud`
- 优先使用 `docker buildx` - 优先使用 `docker buildx`
- 私有 Git 依赖通过 `.netrc` 和 build secret 传入 - 只有检测到私有 Git 依赖时,才通过 `.netrc` 和 build secret 传入;否则不要生成 `.netrc` 相关步骤
- 如需额外 CA也通过 build secret 传入 - 如需额外 CA也通过 build secret 传入
- 如果 Dockerfile 内会执行 `go mod download`、`go build` 等 Go 构建命令,必须通过 `--build-arg` 透传 Go 构建变量,不要只写在 `.gitlab-ci.yml``variables:` - 如果 Dockerfile 内会执行 `go mod download`、`go build` 等 Go 构建命令,必须通过 `--build-arg` 透传 Go 构建变量,不要只写在 `.gitlab-ci.yml``variables:`
- 至少透传:`GOPROXY`、`GOSUMDB`、`GOINSECURE` - 无论是否检测到私有 Git 依赖,至少透传:`GOPROXY`、`GOSUMDB`
- 如果 Dockerfile 用到了 `GOPRIVATE`、`GONOSUMDB`、`GONOPROXY`,也一并透传 - 只有检测到私有 Git 依赖时,才额外透传:`GOPRIVATE`、`GONOSUMDB`、`GONOPROXY`、`GOINSECURE`
- Dockerfile 中对应变量必须有 `ARG`,并让构建命令实际使用传入值,而不是退回默认值 - Dockerfile 中对应变量必须有 `ARG`,并让构建命令实际使用传入值,而不是退回默认值
禁止: 禁止:
@ -352,12 +361,12 @@ Chart 必须反映应用的真实运行架构。
## 百智云用户鉴权接入 ## 百智云用户鉴权接入
只有在仓库里实际依赖 `git.in.chaitin.net/ai/baizhiyun/opensdk` 时才需要接入。 只有在检测到私有 Git 依赖,且该依赖就是 `git.in.chaitin.net/ai/baizhiyun/opensdk` 时才需要接入。
识别规则: 识别规则:
- 先检查 `go.mod`、`go.sum`、源码 import以及构建脚本里是否实际引用 `git.in.chaitin.net/ai/baizhiyun/opensdk` - 先按上文“私有 Git 依赖判定口径”检查仓库,再确认私有依赖中是否实际包含 `git.in.chaitin.net/ai/baizhiyun/opensdk`
- 只有确认存在这个依赖或导入时,才进入本节并索取百智云相关材料 - 只有确认包含这个依赖或导入时,才进入本节并索取百智云相关材料
- 如果仓库里没有这个包,就跳过整段,不要要求接入百智云,也不要生成对应配置 - 如果仓库里没有这个包,就跳过整段,不要要求接入百智云,也不要生成对应配置
固定规则: 固定规则:
@ -415,7 +424,7 @@ Chart 必须反映应用的真实运行架构。
- 如果 `Application` 仍引用 `releases/<app>/manifests/`,该 path 在发布结果中实际存在 - 如果 `Application` 仍引用 `releases/<app>/manifests/`,该 path 在发布结果中实际存在
- 如果镜像内包含固定 upstream 配置upstream service 名与 Chart 渲染结果一致 - 如果镜像内包含固定 upstream 配置upstream service 名与 Chart 渲染结果一致
- Neo4j 一类自带依赖的启动环境变量不依赖 `$(OTHER_ENV)` 展开 - Neo4j 一类自带依赖的启动环境变量不依赖 `$(OTHER_ENV)` 展开
- 如果检测到 `git.in.chaitin.net/ai/baizhiyun/opensdk`,缺少必填百智云私有配置时交互停在当前项继续索取 - 如果检测到的私有 Git 依赖中包含 `git.in.chaitin.net/ai/baizhiyun/opensdk`,缺少必填百智云私有配置时交互停在当前项继续索取
## 最终输出 ## 最终输出
@ -434,5 +443,5 @@ Chart 必须反映应用的真实运行架构。
- Chart 与应用真实组件不匹配 - Chart 与应用真实组件不匹配
- 在生产 release values 中写示例地址 - 在生产 release values 中写示例地址
- 擅自发明新的公网 host - 擅自发明新的公网 host
- 在未检测到 `git.in.chaitin.net/ai/baizhiyun/opensdk` 时仍强行接入百智云 - 在未检测到私有 Git 依赖中的 `git.in.chaitin.net/ai/baizhiyun/opensdk` 时仍强行接入百智云
- 用户未提供必填值时伪造占位内容 - 用户未提供必填值时伪造占位内容