CI/CD / 系统课时
把 Jenkinsfile 放进代码仓库
把 Jenkinsfile 放进代码仓库
把流水线脚本留在 Jenkins 任务配置里,很容易出现代码已经回滚、构建流程却没有同步回滚的问题。本节把 Jenkinsfile 与应用代码一起提交到 Git,并让 Jenkins 每次构建都从 SCM 获取对应版本的流水线定义。
学习目标
- 理解 Jenkinsfile 纳入 Git 版本管理的价值
- 能在仓库中创建并提交可执行的 Jenkinsfile
- 能配置 Jenkins 从 SCM 加载指定路径的 Jenkinsfile
为什么 Jenkinsfile 应该跟着代码走
流水线定义本质上也是代码。它决定使用什么环境、执行哪些命令以及按照什么顺序构建。如果只在 Jenkins 页面里维护脚本,Git 提交记录无法回答“这个版本当时使用哪套构建流程”。
将 Jenkinsfile 放进同一个仓库后,一次提交可以同时修改业务代码和构建逻辑。代码审查能够看到流水线变化,Git 历史能够追踪修改者和修改原因,切换到旧提交时也能取得当时对应的 Jenkinsfile。

在仓库中创建 Jenkinsfile
通常把文件命名为 Jenkinsfile 并放在仓库根目录。下面是一条最小 Declarative Pipeline,它检出当前构建对应的 SCM 内容,并输出当前 Git 提交。
pipeline {
agent any
stages {
stage('Checkout') {
steps {
checkout scm
}
}
stage('Verify') {
steps {
sh 'git rev-parse --short HEAD'
}
}
}
}其中 scm 由 Jenkins 根据当前任务的 SCM 配置提供,不需要在 Jenkinsfile 中重复写仓库地址和凭据。sh 需要能够运行 Shell 的构建节点;Windows 节点应改用适合该环境的步骤。
提交文件时可以执行:
git add Jenkinsfile
git commit -m "ci: add Jenkins pipeline"
git push origin main预期输出
[main <ID>] ci: add Jenkins pipeline
<ID> file changed, <ID> insertions(+)
create mode 100644 Jenkinsfile<ID> 等提交相关动态值会因仓库实际状态而不同。推送成功后,远程仓库的 main 分支应能同时看到应用代码和 Jenkinsfile。
让 Jenkins 从 SCM 读取脚本
对于 Pipeline Job,可将 Pipeline 的 Definition 选择为 Pipeline script from SCM,SCM 选择 Git,然后配置仓库地址、所需凭据和分支。Script Path 填写 Jenkinsfile 相对于仓库根目录的路径;文件就在根目录时通常使用 Jenkinsfile。
如果团队把 CI 文件集中在子目录,例如 ci/Jenkinsfile,那么 Script Path 也必须填写 ci/Jenkinsfile。这里配置的是仓库内路径,不是 Jenkins 控制器或 Agent 的本地文件路径。
验证版本是否真正绑定
触发一次构建后,先确认 Jenkins 成功从 SCM 取得 Jenkinsfile,再观察 Checkout 与 Verify 阶段。日志中的短提交 ID 应对应本次构建使用的 Git revision,而不是某个工作目录残留版本。
还可以修改 Jenkinsfile,例如增加一个临时输出并提交到新分支,再让 Jenkins 构建该分支。只有新分支出现对应阶段或输出,而旧提交仍执行旧版流程,才能证明流水线定义已经真正进入版本控制。
当 Jenkins 报告找不到 Jenkinsfile 时,优先检查构建分支、文件大小写和 Script Path。当 Jenkinsfile 能读取但 checkout scm 失败时,再检查仓库 URL、凭据以及构建节点的 Git 环境。把“读取流水线定义”和“流水线执行期间检出代码”分开定位,通常能更快找到问题。