私有化部署项目管理系统把程序、数据和运维责任放在企业自己的服务器上，代码仓库和 CI/CD 通常也在同一张内网。麻烦出在三者各管一段：开发往 Git 提交，流水线在 Jenkins 上跑，管理平台里的需求状态还得人工回填。对接要解决的就是这一段——让提交记录自动关联到需求、任务和 Bug，让构建结果回到对应的迭代。做完之后，打开一条需求，下面挂着哪些提交、跑过哪些构建，都能直接看到。
下面以禅道为例说明操作方法，内容依据禅道官网文档整理。不同版本的菜单名称和配置入口有差异，动手前先确认自己的版本号。
对接前要确认的四个前提
配置之前先把边界想清楚，能省掉后面大半的排障时间。
要达成的结果：提交记录与构建结果能双向追溯到需求、任务和 Bug，而不是只做一个代码浏览器。目标定得越具体，后面判断"接没接上"就越容易。
环境约束：私有化部署的典型限制是内网隔离和统一出口，这会影响仓库与平台之间的连通性。按官方文档要求，客户端软件需要和平台部署在同一台服务器上，客户端路径里不能有空格和中文。用 HTTPS 协议时证书必须合法，地址后面不能直接跟 IP。
账号与权限：需要管理后台里集成配置的权限、代码仓库的只读账号，以及流水线侧的访问 Token。这三样缺一个，配置页面就会卡住。
选型分支：先看两件事——仓库是 Git 还是 SVN、是自建还是 GitLab/Gitea 这类托管平台；再看流水线是用 Jenkins、GitLab CI，还是用平台自带的内置流水线。这两组选择决定了后面走哪条配置路径。
代码仓库对接：从关联机制到仓库配置
关联机制：提交注释怎么变成平台里的关联记录
官方文档给出两种实现思路。一种是用 Git 自带的钩子，有提交时触发脚本解析注释，再调用平台 API 把记录写进数据库；另一种是用 git log 读取全部提交记录后解析入库。禅道选了第二种，原因是调试和部署更省事，还能把历史提交一起解析进来。
机制本身不复杂：解析提交注释里的 story、task、bug 编号，再写进平台数据库。所以对接能不能生效，一半取决于提交注释写得规不规范。
Git 与 SVN 仓库的两种配置路径
从禅道开源版 12.1 起，管理员可以直接在集成或 DevOps 下的代码库页面创建版本库，不必再手改配置文件。
- 进入代码库页面，点击创建；
- 选择仓库类型，Git 或 SVN，填写名称；
- 填仓库地址，Git 仓库与平台同机时直接填文件目录，SVN 填访问路径且可以是下级路径；
- 填客户端软件地址，例如 /usr/bin/git，SVN 客户端需 1.9 以上；
- 需要认证就填用户名密码，不需要则留空。
保存后系统会自动初始化，拉取历次修改记录。用旧版本或需要更细控制的团队可以走配置文件：改 zentao/module/git/config.php，并建议把改动放到 git/ext/config/git.php，这样升级时不会被覆盖。
GitLab、Gitea 等托管平台怎么接
禅道 15rc3 版本起支持 GitLab 类型版本库，后续版本也支持 Gitea。操作入口在 DevOps—版本库右上角的创建按钮，类型选 GitLab，然后填两样东西：GitLab 地址填项目所在服务器地址，Token 在 GitLab 的 Settings 里通过 Access Tokens 生成。填完保存，平台会自动同步出该账号下可见的项目，选中项目保存后即开始同步代码。
接上之后可以做目录浏览、代码查看、追溯和差异对比。GitLab 集成还支持把 GitLab 用户关联到平台用户，把 issue 关联到需求、任务和 Bug，并提交合并请求。
远程仓库同步与提交注释规范
只集成本机仓库通常不够用。官方文档明确，平台只能集成自己所在机器上的 Git 仓库；如果是远程仓库，需要在平台所在机器上克隆一份，再定时同步。
同步有两种做法：在后台的系统—定时里启用计划任务，模块名填 git；或者用操作系统的计划任务，Linux 用 crontab，Windows 用任务计划程序。官方文档建议 5 分钟同步一次，代码库本身的更新还需要另写同步脚本，定时执行 git pull。
提交注释是关联的入口，格式要固定下来：
- bug#123,234 或 bug:123；
- story#123；
- task#123。
编号之间用逗号或空格都行，bug、story、task 这几个前缀必须写，否则解析不到对应的需求、任务或缺陷，提交就等于没接进来。
CI/CD 对接：让构建结果回到管理平台
这类对接通常归在 DevOps 或 CI/CD 集成的范畴里，核心是把构建的触发条件和结果都收进平台。
Jenkins 集成的完整链路
禅道开源版 12.1 起支持集成 Jenkins 并调用它执行构建，链路分四步。
- 安装并配置 Jenkins，装好构建所需的插件；
- 在平台里创建代码库，步骤与上一节一致；
- 集成 Jenkins，推荐用 Token 方式，在平台侧填入 Jenkins 服务器和 Token；
- 添加构建任务，选择 Jenkins 服务器和对应任务，设置触发方式。
需要留意的是，如果 Jenkins 用匿名只读权限，任务列表才能被平台读取。
内置流水线与 GitLab CI 的替代路径
不想再单独维护一套 Jenkins 的团队，可以直接用平台的内置流水线。禅道 22.6 版本的一键安装包已内置 DevOps，研发团队可以在内置 Git 服务的代码库下新建并编排流水线：先选分支，再编排 Stages 和 Steps，触发器支持提交注释包含关键字、定时计划和分支/标签/合并请求等动作。
已有 Jenkins 或 GitLab 流水线的团队，可以在流水线列表点导入，选择对应引擎。导入 Jenkins 流水线时选服务器地址和应用里的对应任务，导入 GitLab 流水线时选项目关联的代码库即可。
触发方式与构建参数
四种触发方式分别对应不同的交付节奏：
| 触发方式 | 适用对象 | 触发条件 |
|---|---|---|
| 打标签 | Git、GitLab | 代码库新建 tag 时执行 |
| SVN 目录监控 | SVN | 监控目录发生变动时执行 |
| 提交注释包含关键字 | Git、SVN、GitLab | 注释命中设定关键字时执行 |
| 定时计划 | 通用 | 到达设定的日期和时间时执行 |
构建任务还支持自定义构建参数向流水线传参，常用于指定分支、版本号或目标环境。
触发不生效时，先看计划任务。官方文档提示，要让流水线按设定触发，必须保证计划任务已开启，并且相关定时任务状态正常。
私有化环境下常见的四类故障
流水线或任务下拉列表为空
多数是 Jenkins 侧的可见性设置问题。到 Jenkins 全局设置里勾选"匿名用户具有可读权限"，刷新后任务列表就会出来。
高版本 Jenkins 被 CSRF 拦截
高版本 Jenkins 会拦截平台发来的构建请求，需要在 Jenkins 启动前加上参数 -Dhudson.security.csrf.GlobalCrumbIssuerConfiguration=false。Tomcat 部署的改启动脚本，jar 包部署的加到启动命令里，Docker 部署的通过 JAVA_OPTS 环境变量设置。
构建不触发或同步不生效
按顺序排查三处：后台的定时功能是否开启、相关计划任务状态是否正常、远程仓库的同步脚本有没有在按周期执行。远程仓库如果没做定时 git pull，平台看到的永远是旧记录。
证书、路径与编码问题
HTTPS 证书不合法、地址栏直接写 IP，都会导致连接失败；客户端路径里出现空格或中文会直接报错；SVN 客户端版本低于 1.9 时部分命令不可用；仓库编码填错则注释解析会乱码。这几项都属于配置阶段就该核对的内容。
对接完成后怎么验证和运维
配置完成不等于接好了，按下面几步做一次完整验证。
- 提交一次带 story# 或 bug# 注释的代码，等一个同步周期；
- 打开对应需求或任务，确认代码提交记录出现在关联列表中，任务管理页面也能看到对应提交；
- 进入版本库，确认目录浏览、代码查看和差异对比正常；
- 触发一次构建，打标签或改注释关键字都可以，确认构建历史有记录、构建日志可查看；
- 确认构建结果能回到对应的任务或版本，而不是只停在 Jenkins 上。
日常运维有两件事要固定下来。一是配置的备份与回退，配置文件方式把改动放在 ext 目录，升级不覆盖；配置出错时删除代码库重新配置即可，不会影响已有数据。二是权限控制，仓库账号和 Token 按最小权限发放，定期轮换，集成配置的修改权限也要收紧——数据在内网不等于可以省掉权限管理。
内网环境把这条链路接上之后，需求、代码和构建才算真正对齐。对正在做私有化部署项目管理系统落地的团队来说，先跑通一条最小链路，再逐步扩大仓库和流水线的覆盖范围，比一次性全量接入更稳。
参考来源
- 禅道使用手册《集成禅道和 git》：https://www.zentao.net/book/zentaopmshelp/207.html
- 禅道使用手册《集成版本库、集成 Jenkins，并进行构建》：https://www.zentao.net/book/zentaopmshelp/393.html
- 禅道《DevOps 解决方案》：https://www.zentao.net/page/80231.html
- 禅道使用手册《管理流水线》：https://www.zentao.net/book/devops/jenkins-1076.html
文章标题 ：私有化部署项目管理系统如何对接代码仓库与CI/CD ，发布者 ：项目管理研究院
