Jenkins基础教程（56）Jenkins轮询SCM：Jenkins轮询SCM：你的代码有个“跟踪狂”，每分钟都在偷看它！

每次代码提交背后，都有一双眼睛在默默注视着——Jenkins的轮询SCM功能，就像是代码库的“专职跟踪狂”，只不过这个跟踪狂是你请来的，专门为了在代码变动时自动触发构建。

1. 什么是轮询SCM？为什么你的项目需要它？

想象一下，你刚刚完成了一段精彩的代码提交，然后……什么都不用做了。不需要手动触发构建，不需要通知测试人员，甚至不需要检查代码是否集成正确。

这就是轮询SCM的魅力所在。

轮询SCM（Poll Source Code Management）是Jenkins中一种常见的构建触发器方式，它能够定期检查你的源代码管理系统（如Git、SVN等）是否有新的提交或更改。一旦检测到更改，Jenkins就会自动触发相应的构建流程。

轮询SCM vs 定时构建：不一样的工作哲学

很多人容易混淆轮询SCM和定时构建，但它们有着本质区别：

定时构建：像是一个固执的闹钟，不管代码有没有更新，到点就执行构建。轮询SCM：则像是一个聪明的管家，只在检测到代码实际发生变化时，才启动构建过程。

假设你设置了一个每天下午6点的定时构建，即使你一整天都没有提交任何代码，它仍然会运行。而轮询SCM则只在你真正提交了代码后才工作，更加智能和高效。

为什么现代开发团队离不开轮询SCM？

在持续集成/持续部署（CI/CD）的实践中，轮询SCM扮演着至关重要的角色。它实现了“提交即构建”的理想工作流，让代码集成从被动的手动操作转变为自动化的响应过程。

开发人员提交代码后无需额外操作，系统会自动检测变更并启动构建，快速反馈集成结果。这种即时反馈机制可以迅速发现集成错误，提高软件交付质量。

2. 轮询SCM的工作原理：Jenkins如何知道你的代码变了？

轮询SCM的工作原理其实并不复杂，但十分精巧。本质上，它是一个主动检查机制——由Jenkins主动向源代码管理系统发起查询。

工作流程分解：

配置轮询间隔：你告诉Jenkins检查代码仓库的频率，比如每5分钟一次。发起查询：Jenkins按照你设定的时间表，向配置的源代码管理系统（Git、SVN等）发送请求。比较变更：Jenkins会比较远程仓库的当前状态与本地记录的上次状态，检查是否有新的提交、分支或其他更改。触发构建：如果检测到变化，Jenkins会自动触发构建流程；如果没有变化，它就安静地等待下一个检查周期。

轮询的底层机制：

当你配置轮询SCM时，Jenkins会记录当前代码库的状态（如Git的commit hash）。下次轮询时，它会检查这些状态是否发生了变化。对于Git，它可能会执行类似于 git ls-remote的命令来获取远程引用信息，而不必下载整个仓库内容，这样效率更高。

与Webhook（另一种常见的构建触发方式）不同，轮询SCM是Jenkins主动发起的检查，而Webhook是代码仓库在收到推送时通知Jenkins。轮询SCM适用于那些无法从外部访问Jenkins实例的情况，或者代码仓库不支持Webhook的场景。

3. 手把手配置：从零设置你的第一个轮询SCM任务

理论说了这么多，现在让我们动手实践一下。以下是配置轮询SCM的详细步骤：

3.1 基础环境准备

首先，你需要一个正常运行Jenkins的环境，并确保：

Jenkins已安装与你的代码仓库对应的插件（如Git插件、Subversion插件等）Jenkins有权限访问你的源代码仓库你有一个可用的Jenkins项目（自由风格或Pipeline）

3.2 配置自由风格项目的轮询SCM

对于自由风格项目，配置过程非常简单直观：

在Jenkins面板中，选择你要配置的项目，点击"配置"。找到"构建触发器"部分，勾选"轮询SCM"选项。在日程表输入框中，输入轮询间隔的cron表达式。

轮询SCM配置界面示意图

保存配置，这样就完成了！

3.3 轮询时间配置：理解cron表达式

轮询SCM使用与标准cron类似的语法来定义检查频率，但有一个小区别：Jenkins的cron表达式包含5个字段（分、时、日、月、周几），而不是传统的6个。

基本格式： 分钟 小时 日期 月份 星期

字段说明：

字段	取值范围	描述
分钟	0-59	一小时内的第几分钟
小时	0-23	一天内的第几小时
日期	1-31	一月内的第几天
月份	1-12	一年内的第几个月
星期	0-7	一周内的第几天（0和7都代表周日）

实用示例：

H/5 * * * * — 每5分钟检查一次 H H/2 * * * — 每两小时检查一次 H 9 * * 1-5 — 每个工作日（周一到周五）上午9点左右检查一次 H/30 8-20/4 * * 1,3,5 — 每周一、三、五，从8:30开始，截止19:30，每4小时30分检查一次

提示： 表中的"H"代表"hash"，是Jenkins的一个特殊符号，它会将任务分散执行，避免所有任务在同一时刻运行造成负载峰值。

3.4 验证配置

配置完成后，你可以通过以下方式验证轮询SCM是否正常工作：

在项目页面查看"轮询日志"，它记录了每次轮询的详细情况。向代码仓库提交一个小更改，观察是否在预定时间内自动触发构建。检查构建历史，确认构建是由SCM变更触发而非手动触发。

4. 进阶技巧：Pipeline中的轮询SCM配置

对于更现代、更灵活的Pipeline项目，轮询SCM的配置方式有所不同。Pipeline-as-Code的理念让我们可以将触发器定义在项目中，与代码一起版本控制。

4.1 声明式Pipeline中的配置

在声明式Pipeline中，你可以使用 triggers指令来定义轮询SCM：

pipeline {
    agent any
    triggers {
        pollSCM('H/10 * * * *')  // 每10分钟轮询一次
    }
    stages {
        stage('Checkout') {
            steps {
                checkout([
                    $class: 'SubversionSCM', 
                    locations: [[
                        credentialsId: 'mySvnCredentials',
                        local: '.', 
                        remote: 'http://example.com/svn/url/trunk'
                    ]]
                ])
            }
        }
        // 其他阶段...
    }
}

4.2 脚本式Pipeline中的配置

在脚本式Pipeline中，你可以使用properties步骤来配置触发器：

node {
    properties([
        pipelineTriggers([pollSCM('H/15 * * * *')])  // 每15分钟轮询一次
    ])
    
    stage('Checkout') {
        git url: 'https://github.com/your-username/your-repo.git'
    }
    // 其他阶段...
}

4.3 多分支Pipeline的特殊考虑

对于多分支Pipeline项目，通常不需要为每个分支单独配置轮询SCM。多分支项目有一个整体的分支索引轮询间隔，它会自动处理所有分支的变更检测。

你可以在多分支Pipeline配置中设置"扫描分支触发器"，或者使用Webhook来自动触发分支索引扫描。

4.4 处理多个SCM仓库的情况

当你的Pipeline需要从多个SCM仓库 checkout 代码时，默认情况下，任何一个仓库的变更都会触发构建。如果你希望只对特定仓库的变更做出响应，可以使用 poll: false参数禁用对某些仓库的轮询：

stage('Checkout Lib') {
    steps {
        checkout([
            $class: 'GitSCM',
            branches: [[name: '*/main']],
            extensions: [[$class: 'DisableChangelog']],
            userRemoteConfigs: [[
                url: 'https://github.com/your-username/library-repo.git',
                poll: false  // 禁用对此仓库的轮询
            ]]
        ])
    }
}

5. 实战示例：完整搭建一个带轮询SCM的CI流程

让我们通过一个具体示例，搭建一个完整的Java Web项目持续集成流程，它会在每次代码提交到Git仓库时自动构建。

5.1 项目概览

项目类型：Maven管理的Java Web应用代码仓库：Git（GitHub）构建工具：Maven特殊需求：运行单元测试、生成测试报告、构建Docker镜像

5.2 自由风格项目配置示例

创建新项目：选择"构建一个自由风格的软件项目"。源代码管理：选择Git，填写仓库URL和凭证。构建触发器：勾选"轮询SCM"，设置日程为 H/5 * * * *（每5分钟检查一次）。构建步骤：添加Invoke top-level Maven targets步骤，目标设置为 clean package。后期处理：添加Publish JUnit test result report步骤，配置测试结果XML路径。

5.3 Pipeline项目配置示例

以下是完整的Jenkinsfile示例：

pipeline {
    agent any
    triggers {
        pollSCM('H/5 * * * *')  // 每5分钟检查一次Git仓库
    }
    tools {
        maven 'M3'
        jdk 'JDK11'
    }
    stages {
        stage('Checkout') {
            steps {
                git branch: 'main',
                    url: 'https://github.com/your-username/your-java-webapp.git',
                    poll: true
            }
        }
        stage('Build') {
            steps {
                sh 'mvn clean compile'
            }
        }
        stage('Test') {
            steps {
                sh 'mvn test'
            }
            post {
                always {
                    junit 'target/surefire-reports/*.xml'
                }
            }
        }
        stage('Package') {
            steps {
                sh 'mvn package -DskipTests'
            }
        }
        stage('Build Docker Image') {
            when {
                expression { currentBuild.resultIsBetterOrEqualTo('SUCCESS') }
            }
            steps {
                script {
                    docker.build("my-webapp:${env.BUILD_ID}")
                }
            }
        }
    }
    post {
        success {
            emailext (
                subject: "构建成功: ${env.JOB_NAME} #${env.BUILD_NUMBER}",
                body: "检查地址: ${env.BUILD_URL}",
                to: "${env.DEVELOPER_EMAILS}"
            )
        }
        failure {
            emailext (
                subject: "构建失败: ${env.JOB_NAME} #${env.BUILD_NUMBER}",
                body: "检查地址: ${env.BUILD_URL}",
                to: "${env.DEVELOPER_EMAILS}"
            )
        }
    }
}

5.4 配置关键点说明

轮询间隔：根据团队提交频率设置合理的值，太频繁会增加仓库压力，太稀疏会延迟反馈。凭证管理：使用Jenkins的凭证管理功能安全地存储Git仓库访问令牌。条件执行：通过 when指令确保只有在前期阶段成功时才执行后续步骤。通知机制：配置构建成功/失败时的自动邮件通知，让团队及时了解集成状态。

6. 避坑指南：轮询SCM常见问题与解决方案

即使按照指南配置，你也可能遇到一些问题。以下是一些常见问题及其解决方法：

6.1 轮询不触发构建

问题：即使代码仓库有新的提交，轮询SCM也没有触发构建。

可能原因和解决方案：

轮询间隔设置过长：检查cron表达式是否正确，考虑缩短轮询间隔。权限问题：确保Jenkins用户有访问代码仓库的权限。仓库URL或分支配置错误：检查源代码管理部分的配置是否正确。首次运行需要手动触发：对于Pipeline项目，通常需要手动运行一次后，轮询SCM才会开始工作。

6.2 频繁轮询导致系统负载过高

问题：轮询过于频繁，导致Jenkins服务器和代码仓库服务器负载增加。

解决方案：

合理设置轮询间隔，考虑使用 H符号分散负载。对于多分支项目，使用分支索引轮询而非每个作业单独轮询。考虑使用Webhook替代轮询SCM，实现事件驱动的触发机制。

6.3 多个SCM仓库的意外触发

问题：当Pipeline中有多个SCM仓库时，任何一个仓库的变更都会触发构建，但这可能不是期望的行为。

解决方案：

使用 poll: false明确禁用不需要触发构建的仓库轮询。重新设计Pipeline，将不同仓库的检查分离到不同的Pipeline中。

6.4 轮询日志混乱

问题：轮询日志过于冗长或难以理解。

解决方案：

学习阅读轮询日志，区分正常轮询和检测到变更的轮询。使用"轮询日志"功能诊断问题，它会显示Jenkins检测到了什么变更以及何时检测到的。

6.5 与Webhook结合的混合方案

在某些场景下，单纯依赖轮询SCM可能不是最佳选择。考虑以下混合方案：

主要使用Webhook：实现即时触发。后备轮询机制：设置一个较长的轮询间隔（如每12小时）作为安全网，防止Webhook失效时错过构建。

这种混合方案结合了两者的优点：Webhook提供即时响应，轮询SCM作为故障保护机制。

7. 总结：让轮询SCM成为你的自动化助手

Jenkins的轮询SCM功能是一个强大而灵活的自动化工具，它让代码集成从手动操作转变为自动响应。通过正确配置，你可以实现"提交即构建"的理想工作流，快速发现集成问题，提高软件交付效率。

记住以下关键点：

选择合适的触发策略：根据项目需求和基础设施条件，决定使用轮询SCM、Webhook还是混合方案。合理设置轮询频率：平衡反馈速度和系统负载，使用 H符号分散任务执行。Pipeline优先：对于新项目，优先使用Pipeline-as-Code方式定义触发器，将配置与代码一起版本控制。监控和优化：定期检查轮询日志和系统性能，持续优化配置。