Skip to content

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 案例。