主题
Git 准备阶段
Git 准备默认关闭。开启后(useGit: true + gitUrl),每次运行先对齐代码再执行命令,是「服务器拉代码构建」模型的核心。
行为语义
| 工作目录状态 | 准备动作 |
|---|---|
| 不存在 / 空目录 | git clone(按 gitDepth、gitBranch、gitSubmodule) |
| 已是该仓库工作区 | git fetch --prune --tags + git checkout -f -B <branch> 对齐远程 |
| 非空且不是 Git 仓库 | 拒绝执行(避免误覆盖用户数据) |
补充:
gitClean: true时对齐后执行git clean -fdx,清掉未跟踪文件(含构建产物),保证干净构建。gitSubdir指定仓库子目录作为实际工作目录(monorepo 场景)。- 准备阶段单独超时,默认 600s(
gitPrepareTimeoutSec),与运行整体超时独立。 - 触发时
--branch <ref>覆盖项目默认分支,并传递给依赖项目。
凭据
私有仓库先在「系统设置 → 凭据」创建凭据(https_token / ssh_key 等),用「测试连接」验证,再把 gitCredentialId 填进项目。
- 凭据加密存储于服务端(secret.key),不拼进 Git URL。
- HTTPS 走
GIT_ASKPASS,SSH 走GIT_SSH_COMMAND注入。 - 带口令的 SSH key 不支持:请改用无口令部署密钥或 https token。
- 服务端也可生成 SSH 公钥(ed25519/rsa)添加到 Git 托管方,见 凭据与 API Token。
注入的 GIT_* 变量
准备成功后向命令环境注入:
| 变量 | 含义 |
|---|---|
GIT_BRANCH | 实际检出的分支 |
GIT_COMMIT / GIT_COMMIT_SHORT | 完整 / 短提交哈希 |
GIT_TAG | 指向该提交的 tag(如有) |
GIT_AUTHOR / GIT_MESSAGE | 提交作者与信息 |
GIT_DIRTY | 工作区是否有未提交改动 |
脚本里可直接用 ${GIT_COMMIT_SHORT} 打版本标记。未启用 Git 时这些变量不存在。
失败语义
准备阶段失败 → 整次运行记 error/failed,命令不会执行。常见原因:
- 凭据失效或仓库地址错误:先「测试连接」。
- 工作目录被手工放入了非仓库文件:清空或换目录。
- 网络不可达:服务端机器到 Git 托管方的连通性(内网穿透场景注意 DNS/代理)。
排查详见 故障排查。
与「本地构建上传」的区别
deploy 的模型是:本地 push 代码到 Git 远程 → 触发运行 → 服务端 clone/fetch 后在本机构建。 不要 scp 本地构建产物、也不要本地构建后上传——那样运行日志里没有 git/mvn/pnpm 证据,版本也无法追溯。 被问「在哪里构建」时,出示项目定义与运行日志即可回答。真实流程见 HuLa 案例。