Jenkins中如何配置构建触发器

Jenkins 构建触发器配置指南

一 前置准备

• 安装必要插件：如 Git plugin、GitLab Plugin、Generic Webhook Trigger Plugin（用于代码托管平台的事件通知与通用 Webhook 触发）。
• 确保 Jenkins URL 可被代码托管平台访问（公网或内网可达），并为触发器准备 Token（可选，用于身份校验）。

二 在自由风格项目中配置

• 进入项目 → Configure → Build Triggers，按需勾选：
  • 触发远程构建（Trigger builds remotely）：设置一个 Token，通过 URL 触发，例如：JENKINS_URL/job/JobName/build?token=TOKEN。适合脚本、外部系统调用。
  • 在其他项目构建完成后触发（Build after other projects are built）：填写上游 Projects to watch，可设置仅在 Stable/Unstable 等条件下触发，用于构建链编排。
  • 定时触发构建（Build periodically）：填写 Cron 表达式，按固定时间执行（见第四节语法）。
  • 轮询 SCM（Poll SCM）：定时扫描仓库变更并触发；注意其会扫描工作区，开销较大，优先使用 Webhook。
  • GitHub 钩子触发 GITScm 轮询（GitHub hook trigger for GITScm polling）：配合 GitHub Webhook 使用，由 GitHub 主动通知 Jenkins，减少轮询成本。

三 在 Pipeline 项目中配置

• 在 Jenkinsfile 的 pipeline { triggers { … } } 中使用声明式触发器；注意：使用代码方式定义触发器后，界面中的 Build periodically 将被忽略，以代码为准。
• 常用触发器示例：
  • 定时构建

    pipeline {
      agent any
      triggers { cron('H 0 * * *') }  // 每天 00:00–00:59 间某刻执行
      stages { stage('Build') { steps { echo 'nightly build' } } }
    }
    

  • 轮询 SCM

    pipeline {
      agent any
      triggers { pollSCM('H/5 * * * *') }  // 每 5 分钟检查一次变更
      stages { stage('Build') { steps { sh 'make test' } } }
    }
    

  • 上游任务触发

    pipeline {
      agent any
      triggers {
        upstream(
          upstreamProjects: 'job1,job2',
          threshold: hudson.model.Result.SUCCESS
        )
      }
      stages { stage('Build') { steps { echo 'triggered by upstream' } } }
    }
    

  • GitLab 事件触发（需安装 GitLab 插件）

    pipeline {
      agent any
      triggers {
        gitlab(
          triggerOnPush: true,
          triggerOnMergeRequest: true,
          branchFilterType: 'All',
          secretToken: 'YOUR_SECRET_TOKEN'
        )
      }
      stages { stage('Build') { steps { echo 'gitlab event' } } }
    }
    

  • 通用 Webhook 触发（需安装 Generic Webhook Trigger 插件）

    pipeline {
      agent any
      triggers {
        genericTrigger(
          token: 'WEBHOOK_TOKEN',
          genericVariables: [
            [key: 'ref', value: '$.ref']
          ]
        )
      }
      stages { stage('Build') { steps { echo 'webhook received' } } }
    }
    

  提示：使用 GitLab 或 Generic Webhook 时，需在代码托管平台配置 Webhook 指向 Jenkins 的对应接口，并携带 Token（Generic Webhook 可用查询参数 token=TOKEN）。

四 Cron 语法与示例

• 字段顺序：MINUTE HOUR DOM MONTH DOW（5 个字段，空格或 Tab 分隔）；支持 H（Hash） 用于打散负载，如 **H H * * *** 表示每天在 0:00–23:59 间某刻执行；常用别名 @hourly、@daily、@midnight、@weekly、@monthly、@yearly。
• 常用示例
  • 每 15 分钟：H/15 * * * *
  • 工作日 9:45–16:45 每 2 小时：45 9-16/2 * * 1-5
  • 工作日 9–17 点 每 2 小时（时间不固定）：H H(9-16)/2 * * 1-5
  • 每月 1 日与 15 日（除 12 月）：H H 1,15 1-11 *
• 建议：在可能聚集的任务上使用 H，避免同一时刻大量任务同时启动。

五 GitLab 与通用 Webhook 实战要点

• GitLab 触发
  • Jenkins 任务中勾选 Build when a change is pushed to GitLab，保存生成的 GitLab webhook URL 与 Secret token；在 GitLab 项目 Settings → Webhooks 中填写 URL 与 Token，必要时可暂时关闭 SSL verification 用于自签名证书场景（生产不建议）。
• 通用 Webhook 触发
  • 安装 Generic Webhook Trigger Plugin，在任务中启用并配置 Token 与 请求参数映射（如从 JSON 请求体中提取 $.ref）；代码托管平台 Webhook URL 使用：http://JENKINS/generic-webhook-trigger/invoke?token=TOKEN。若不使用 Token，可用 http://user:password@JENKINS/… 进行身份认证（不推荐）。