GitLab CI 驱动禅道自动化部署从零构建企业级 CI/CD 流水线1. 引言禅道ZenTao作为国内领先的开源项目管理软件已在无数研发团队中扮演着“枢纽”角色——产品经理提需求开发团队领任务测试人员报 Bug所有角色的信息汇聚于此。然而传统模式下代码提交、构建、测试、部署这一整套 CI/CD 流程与禅道是割裂的开发者将代码推送到 GitLab在终端手动执行部署脚本再回到禅道更新任务状态整个链路充满了重复劳动和人为失误。本文致力于消除这一隔阂通过 GitLab CI即 GitLab 内置的 CI/CD 工具与禅道的深度集成搭建一条完全自动化的交付流水线。当你提交代码的那一刻后续的构建、测试、部署乃至禅道中的任务状态更新都将自动完成。你将掌握以下技能✅ 禅道与 GitLab 的双向关联配置✅ 基于 Docker 的 GitLab Runner 部署与注册✅ 编写生产级.gitlab-ci.yml流水线覆盖构建、测试、部署各环节✅ 集成 ZTF 自动化测试框架打通测试闭环✅ 配置 Webhook 触发、构建产物存储、回滚等生产特性完成本文后你将亲手打造一条从“代码提交”直通“禅道任务”的自动化高速公路彻底拥抱 DevOps 效率革命。2. 核心架构禅道如何与 GitLab CI 双向对话先看图理解整体的数据流向部署服务器禅道服务器GitLab开发者工作区git push触发拉取执行构建/测试调用 ZTF 执行测试提交测试结果通过 Webhook 通知同步任务状态关联 GitLab 提交开发者代码仓库GitLab RunnerCI/CD PipelineWebhook 触发器禅道项目管理ZTF 自动化测试框架容器化部署环境这张图描述的是一个双向闭环开发者提交代码后GitLab CI 自动构建、部署、执行测试同时将测试结果和任务状态同步回禅道实现真正的“项目管理”与“持续交付”一体化。3. 环境准备在开始集成之前需要先确保以下组件均已部署就绪组件推荐配置说明GitLab自托管Self-hosted版本 15.0需具备管理员权限禅道开源版 18.5建议最新需开启 DevOps 模块GitLab Runnerv15.0推荐 Docker 执行器Docker20.10Runner 主机需安装禅道服务器Ubuntu 20.04 / CentOS 7用于部署禅道容器⚠️ 如果禅道版本过低低于 18.5Docker 镜像可能不支持通过环境变量选择是否启用内置 MySQL建议升级至新版以获得更好的 DevOps 集成体验。此外当禅道与 GitLab 部署在不同服务器上时请确保两者之间网络互通特别是 Webhook 通信端口和 API 访问端口不会被防火墙阻断。4. 配置禅道与 GitLab 的集成4.1 生成 GitLab Access Token集成之前禅道需要一个 Token 来访问 GitLab API。登录 GitLab 后点击右上角头像 →Edit profile。选择左侧导航Access Tokens。输入 Token 名称如zentao-integration过期时间建议设置为Never。在Select scopes中勾选api允许完整 API 访问和read_repository允许读取仓库。点击Create personal access token然后立即复制生成的 Token离开页面后将无法再次查看。4.2 在禅道中关联 GitLab 代码库登录禅道切换到DevOps视图顶部导航栏选择GitLab标签页然后点击「添加 GitLab」。填写以下信息配置项说明示例名称自定义标识内部 GitLab服务地址GitLab 的访问地址https://gitlab.yourcompany.comToken上一步生成的 Access Tokenglpat-xxxxxxxxxxxxAPI 版本固定选择v4—点击保存后禅道会验证 Token 的有效性验证通过后即可在下拉菜单中选择需要关联的 GitLab 项目。4.3 关联禅道任务与 GitLab 提交建立了项目关联后开发者可以在一线实现“任务—代码”的双向链接。提交代码时在 Commit Message 中包含Story #123或Task #456该提交记录将自动显示在禅道对应需求/任务页面的“代码”标签页中。反之禅道中需求、任务、Bug 等页面上也会直接显示关联的 GitLab 合并请求和分支。4.4 配置禅道 Webhook 触发 GitLab 流水线进阶此配置可以实现双向联动——在禅道中更新任务状态时自动触发 GitLab 流水线。在 GitLab 中配置 Webhook进入项目 →Settings→Webhooks添加禅道 Webhook 地址可勾选Push events和Merge request events作为触发条件。在禅道中添加 GitLab 流水线在 DevOps 视图中通过引擎下拉菜单选择 GitLab 流水线关联对应代码库即可让流水线执行结果同步回禅道。5. 安装与注册 GitLab RunnerDocker 模式Runner 是 CI/CD 的执行引擎负责拉取并执行.gitlab-ci.yml中定义的任务。本节将搭建 Docker 执行器获得干净、隔离的作业执行环境。5.1 在 Runner 主机安装 Docker若 Runner 主机尚未安装 Docker按以下步骤安装# Ubuntu/Debiansudoaptupdatesudoaptinstall-ydocker.iodocker-composesudosystemctlenabledocker--now# CentOS 7sudoyuminstall-yyum-utilssudoyum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.reposudoyuminstall-ydocker-ce docker-ce-cli containerd.iosudosystemctlenabledocker--now5.2 使用 Docker 容器运行 GitLab Runner这是官方推荐的部署方式能以容器形式运行 Runner 而不影响宿主机环境。dockerrun-d--namegitlab-runner\--restartalways\-v/var/run/docker.sock:/var/run/docker.sock\-v/srv/gitlab-runner/config:/etc/gitlab-runner\gitlab/gitlab-runner:latest关键挂载说明/var/run/docker.sock让容器内的 Runner 可以调用宿主机 Docker 守护进程从而执行 DinDDocker-in-Docker等操作。/srv/gitlab-runner/configRunner 配置文件持久化防止容器删除后配置丢失。5.3 注册 Runner注册 Runner 的目的是将它绑定到你的 GitLab 项目或群组。dockerexec-itgitlab-runner gitlab-runner register根据提示依次输入GitLab instance URL自托管实例地址如https://gitlab.yourcompany.comRegistration token进入 GitLab 项目 →Settings→CI/CD→Runners可获取Runner description如zentao-deploy-runnerTags可选建议指定为dockerExecutor输入docker⚠️ 若需要使用docker-in-dockerDinD模式在容器内再启动子容器请在 Runner 的config.toml中添加privileged true并将执行器设为dockerimage 指定为docker:dind。6. 编写 .gitlab-ci.yml全功能流水线现在进入核心环节——编写.gitlab-ci.yml存放于项目根目录。以下模板集成了版本锁定、构建、测试、部署、产物归档覆盖禅道部署流水线的完整生命周期。# 流水线阶段定义按顺序执行stages:-build-test-deploy# 全局缓存加速依赖安装cache:paths:-vendor/# 变量集中管理关键信息不要明文暴露应使用 CI/CD 变量variables:MYSQL_ROOT_PASSWORD:${ZENTAO_MYSQL_PASSWORD}IMAGE_TAG:${CI_COMMIT_SHORT_SHA}DEPLOY_SERVER:useryour-deploy-server### 构建阶段 ###build_job:stage:buildimage:docker:latestservices:-docker:dindbefore_script:-docker login-u $CI_REGISTRY_USER-p $CI_REGISTRY_PASSWORD $CI_REGISTRYscript:# 构建禅道定制化镜像-docker build-t $CI_REGISTRY_IMAGE:${IMAGE_TAG}.-docker push $CI_REGISTRY_IMAGE:${IMAGE_TAG}only:-main-developtags:-docker### 测试阶段 ###test_job:stage:testimage:hub.zentao.net/app/zentao:latestservices:-mysql:5.7script:# 调用 ZTF 执行自动化测试详见 7.1 节-./ztf--exec-file ./test_suites/zentao_suite.xml--report-url ${CI_API_V4_URL}# 可选执行单元测试-composer testonly:-merge_requests-developartifacts:when:alwayspaths:-test-reports/reports:junit:test-reports/*.xml### 部署阶段 ###deploy_production:stage:deployimage:alpine:latestbefore_script:-apk add--no-cache openssh-client docker-eval $(ssh-agent-s)-echo $SSH_PRIVATE_KEY|tr-d \r|ssh-add--mkdir-p ~/.sshchmod 700 ~/.sshscript:# 通过 SSH 在部署服务器上执行远程部署命令-ssh ${DEPLOY_SERVER} docker pull $CI_REGISTRY_IMAGE:${IMAGE_TAG}docker stop zentao||truedocker rm zentao||truedocker run-d--name zentao \-p 80:80 \-v /data/zentao:/data \-e MYSQL_INTERNALtrue \ $CI_REGISTRY_IMAGE:${IMAGE_TAG}only:-mainenvironment:name:productionurl:https://zentao.yourcompany.comtags:-deploy7. 扩展与高级特性基础流水线已经能够覆盖常规部署场景但若你的团队对代码质量、流程安全有更高要求可以继续接入以下能力。7.1 集成 ZTF 自动化测试框架ZTF 是禅道团队自研的开源自动化测试框架与禅道平台原生集成能将禅道中的测试用例和测试脚本进行双向同步执行结果自动提交到禅道并生成测试报告。在 GitLab CI 中集成 ZTF 的典型方式# 1. 在流水线的测试阶段下载 ZTF 二进制wgethttps://ztf.zentao.net/download/ztf-linux-amd64.tar.gztar-xzfztf-linux-amd64.tar.gzchmodx ztf# 2. 执行测试脚本需事先配置好禅道 API Token./ztf --exec-file ./test_cases/zentao_tests.xml\--report-url${CI_API_V4_URL}\--user${ZENTAO_USER}\--token${ZENTAO_TOKEN}执行成功后测试结果将自动提交到禅道相应用例失败的用例甚至可以在禅道中直接创建 Bug 记录形成“代码提交 → 自动测试 → 测试报告回流 → 用例失败自动创建 Bug”的完整闭环。7.2 多环境部署Dev → Staging → Production生产级的流水线通常不会直接部署到线上而是采用渐进式部署策略。推荐采用多阶段部署模式环境触发分支部署场景devdevelop自动部署至开发环境供团队日常联调stagingrelease/*或手动触发准生产验收环境用于回归测试和业务验收productionmain需审批正式线上发布通常结合手动审批实现这种模式需要在.gitlab-ci.yml中定义多个 deploy 任务并为每个任务指定不同的environment字段同时通过only和when精确控制触发条件。7.3 手动审批与受保护环境生产环境部署前加入人工审批是许多企业安全合规的基本要求。在 GitLab CI 中可以通过受保护环境Protected Environments结合审批规则Approval Rules实现在 GitLab 项目 →Settings→CI/CD→Protected Environments中将production设为受保护环境。设置部署策略为「需要来自至少一名审批人的批准Require approval from at least one member of a group」。在.gitlab-ci.yml的deploy_production任务中添加needs: []避免受之前任务的影响使其在部署阶段等待人工按钮点击。8. 生产最佳实践与监控8.1 配置运行监控为了确保流水线的健康度和部署成功率建议配置以下监控指标Runner 健康检查定期探测 Runner 主机的 Docker 服务状态确保可用。构建耗时监控记录每个 Stage 的执行时长及时发现性能退化。失败率告警利用 Prometheus Alertmanager 对流水线失败率进行阈值告警。部署回滚计时器监控从镜像构建完成到部署成功的时间窗口。8.2 减少流水线噪声only/except 策略精调将流水线配置为仅在必要的分支和场景下触发可有效节省计算资源并降低日志干扰。常规优化策略only:-main-develop-merge_requestsexcept:-tags-/^wip-/8.3 变更原子性与回滚预案每个部署动作都应该是可逆的。在流水线中增加以下回滚能力保留前 N 个版本镜像在构建阶段保留最近 5 个成功的镜像 Tag为回滚储备靶点。蓝绿部署部署时同时运行新旧两个集群验证完成后才切换流量。回滚 Job定义一个rollbackStage一键将环境回退到上一个稳定版本rollback_production:stage:deployscript:-ssh ${DEPLOY_SERVER} docker pull $CI_REGISTRY_IMAGE:${PREVIOUS_TAG}docker stop zentaodocker rm zentaodocker run-d--name zentao...$CI_REGISTRY_IMAGE:${PREVIOUS_TAG}9. 部署流程全景图集成版developmain开发者提交代码GitLab 触发 CI 流水线Runner 执行 .gitlab-ci.yml构建阶段生成 Docker 镜像并推送到仓库测试阶段执行 ZTF 自动化测试测试结果回流禅道环境判定自动部署到 dev 环境等待人工审批生产环境部署部署后健康检查完成上线10. 常见问题与排查问题排查方向解决方案Runner 执行器报错Cannot connect to the Docker daemonRunner 容器未挂载 Docker Socket添加-v /var/run/docker.sock:/var/run/docker.sock并重启 Runner禅道 DevOps 模块找不到 GitLab 项目Token 权限不足或项目未公开确认 Token 包含apiScope禅道和 GitLab 部署在互联的网络中ZTF 测试结果无法回传禅道禅道 API Token 配置错误或网络不通在流水线变量中正确配置ZENTAO_URL、ZENTAO_TOKEN并允许 Runner 主机访问禅道 API 端口流水线触发后没有日志输出Runner Tag 与 job 不匹配检查 job 中的tags字段和 Runner 注册时设置的 tag 是否一致容器内执行docker命令提示权限不足DinD 容器未以 privileged 模式运行在 Runner 的config.toml中添加privileged true并重启 Runner11. 总结与最佳实践通过 GitLab CI 对禅道进行自动化部署本质上是将 DevOps 最佳实践与项目管理工具进行了深度融合。回顾整个流水线的设计有几个关键原则值得持续遵守✅配置版本化.gitlab-ci.yml是 CI/CD 的设计蓝图必须纳入 Git 版本管理。✅测试左移将测试阶段尽可能前置到构建与合并之前提前发现缺陷从源头提升禅道中用例的质量。✅最小化权限GitLab Access Token 只授予禅道必要的api和read_repository权限生产环境的 SSH 密钥妥善保管以环境变量的形式注入流水线绝不可明文提交。✅可观测性利用 GitLab 内置的 Metrics、Prometheus 集成配合禅道 DevOps 报表实时掌握发布质量与团队效率。✅持续优化触发策略避免不必要的流水线运行节省计算资源的同时减少日志噪声。GitLab CI 与禅道的集成远不止自动部署这一个应用场景。它是研发管理中“代码变更”与“项目管理”两大核心系统的粘合剂——每一次提交、每一次部署、每一个失败的测试用例都能在禅道中留下完整的痕迹。