通用 Webhook 触发器插件

这是一个 Jenkins 插件，可以：

接收任何 HTTP 请求，JENKINS_URL/generic-webhook-trigger/invoke
提取值
- 使用 JSONPath 或 XPath 从 POST 内容中提取
- 从 查询 参数中提取
- 从 头部 中提取
使用这些值作为变量触发构建

该插件还有一个可选功能，只有当提供的正则表达式匹配提取的变量时才触发作业。这里有一个例子，假设 POST 内容如下：

{
  "before": "1848f1236ae15769e6b31e9c4477d8150b018453",
  "after": "5cab18338eaa83240ab86c7b775a9b27b51ef11d",
  "ref": "refs/heads/develop"
}

然后你可以有一个从 POST 内容解析的变量，名为 ref，类型为 JSONPath，表达式为 $.ref。可选的过滤器文本可以设置为 $ref，过滤器正则表达式设置为 [^(refs/heads/develop|refs/heads/feature/.+)$](https://github.com/jenkinsci/generic-webhook-trigger-plugin/blob/master/https://jex.im/regulex/#!embed=false&flags=&re=%5E(refs%2Fheads%2Fdevelop%7Crefs%2Fheads%2Ffeature%2F.%2B%24)，这样只会为 develop 和 feature 分支触发构建。

这里有更多使用案例的示例。

展示使用示例的视频：

它可以触发任何 webhook，例如：

最初的用例是构建合并/拉取请求。你可以使用 Git 插件，如这篇博客文章所述来实现。在 Violation Comments to GitLab Plugin 页面上也有这方面的示例。

你可能想要向调用系统报告。HTTP Request Plugin 是一个非常方便的插件。

如果选择了一个节点，那么该节点中的所有叶子都将被贡献。如果选择了一个叶子，那么只有该叶子会被贡献。

只触发特定作业

当在多个作业中使用该插件时，同一个 URL 会触发所有作业。如果你只想触发某个特定作业，你可以：

使用 token 参数为不同的作业设置不同的令牌。只使用令牌意味着只有具有该确切令牌的作业对该请求可见。这将提高性能并减少每次调用的响应。
或者，添加一些请求参数（或头部，或 POST 内容）并使用正则表达式过滤器，只在该参数具有特定值时触发。

Token 参数

有一个特殊的 token 参数。提供后，调用只会触发具有该确切令牌的作业。令牌还允许在没有任何其他身份验证凭据的情况下进行调用。

在插件的 2.x 版本中，不再支持在 BuildAuthorizationToken 中在插件外部指定令牌。

令牌可以作为以下方式提供：

请求参数：

curl -vs "http://localhost:8080/jenkins/generic-webhook-trigger/invoke?token=abc123" 2>&1
Token 头部：

curl -vs -H "token: abc123" "http://localhost:8080/jenkins/generic-webhook-trigger/invoke" 2>&1
- 它还会检测 X-Gitlab-Token。
Bearer 类型的 Authorization 头部：

curl -vs -H "Authorization: Bearer abc123" "http://localhost:8080/jenkins/generic-webhook-trigger/invoke" 2>&1

干运行

干运行功能使用户能够测试插件而不实际触发任何作业。

通过提供 gwt-dry-run: true 头部来启用干运行。

curl -v -H "gwt-dry-run: true"\
  "http://localhost:8080/jenkins/generic-webhook-trigger/invoke?token=abc123"

缓存作业

在大型安装中，检索所有配置的作业可能需要一些时间。该插件通过使用 ItemListener 来跟踪配置的作业来解决这个问题。这只会在提供了 token 的调用中使用，因此为了性能考虑，建议使用 token。

精确触发一次构建

在此插件的 1.85.2 版本之前，它会批量处理具有相同参数的构建。1.86.0 版本添加了一个选项 allowSeveralTriggersPerBuild，如果勾选，将保持这种行为。如果不勾选，插件在被调用时将只触发一个作业。

白名单主机

可以在 Jenkins 全局配置页面中配置白名单。白名单将阻止任何未在此列表中配置的对插件的请求。主机可以是空以允许任何主机，静态 IP，CIDR 或范围：

1.2.3.4
2.2.3.0/24
3.2.1.1-3.2.1.10
2001:0db8:85a3:0000:0000:8a2e:0370:7334
2002:0db8:85a3:0000:0000:8a2e:0370:7334/127
2001:0db8:85a3:0000:0000:8a2e:0370:7334-2001:0db8:85a3:0000:0000:8a2e:0370:7335

主机也可以选择使用HMAC进行验证。

白名单

故障排除

如果你想调试插件，可以使用这个仓库：https://github.com/tomasbjerre/jenkins-configuration-as-code-sandbox

如果你在调试表达式，可能会想查看以下资源：

使用curl可能是最简单的方法。假设你已经配置了一个Jenkins作业以通用Webhook触发，以下是一些启动作业的示例。

curl -vs "http://localhost:8080/jenkins/generic-webhook-trigger/invoke" 2>&1

如果作业没有配置token且没有启用安全设置，这应该能启动你的作业。如果启用了安全设置，你可能需要进行身份验证：

curl -vs "http://用户名:密码@localhost:8080/jenkins/generic-webhook-trigger/invoke" 2>&1

如果你的作业有token，你就不需要提供其他凭据。你可以这样指定token：

curl -vs "http://localhost:8080/jenkins/generic-webhook-trigger/invoke?token=在此填写TOKEN" 2>&1

请注意，使用token总是以SYSTEM权限运行触发的作业。

如果你想使用token触发并提供一些post内容，curl可以这样做：

curl -v -H "Content-Type: application/json" -X POST -d '{ "app":{ "name":"some value" }}' "http://localhost:8080/jenkins/generic-webhook-trigger/invoke?token=在此填写TOKEN"

截图

通用触发器

默认值

插件可以配置默认值。如下所示：

默认值

但是，如果你手动执行作业（或重放流水线），这个默认值将不会被使用。因为插件根本不会被调用。你可以通过勾选"This job is parameterized"并添加一个与你在插件中配置的同名参数来解决这个问题。像这样：

默认值

现在，无论是手动触发作业、重放流水线，还是使用插件触发，这个默认值都会被使用！

预构建步骤

如果你需要在预构建步骤中使用解析后的值，比如git克隆，你需要添加一个与变量同名的参数。

Job DSL 插件

这个插件可以与Job DSL插件一起使用。在Violation Comments to GitLab Plugin的wiki页面中也有一个示例。

Job DSL支持在处理DSL时注入凭据。如果你想从凭据中设置token，可以使用这个功能。

pipelineJob('通用作业示例') {
 parameters {
  stringParam('VARIABLE_FROM_POST', '')
 }

 triggers {
  genericTrigger {
   genericVariables {
    genericVariable {
     key("VARIABLE_FROM_POST")
     value("\$.something")
     expressionType("JSONPath") //可选，默认为JSONPath
     regexpFilter("") //可选，默认为空字符串
     defaultValue("") //可选，默认为空字符串
    }
   }
   genericRequestVariables {
    genericRequestVariable {
     key("requestParameterName")
     regexpFilter("")
    }
   }
   genericHeaderVariables {
    genericHeaderVariable {
     key("requestHeaderName")
     regexpFilter("")
    }
   }
   token('abc123')
   tokenCredentialId('')
   printContributedVariables(true)
   printPostContent(true)
   silentResponse(false)
   shouldNotFlatten(false)
   regexpFilterText("\$VARIABLE_FROM_POST")
   regexpFilterExpression("aRegExp")
  }
 }

 definition {
  cps {
   // 或者直接引用包含流水线的Jenkinsfile
   script('''
    node {
     stage('某个阶段') {
      println "VARIABLE_FROM_POST: " + VARIABLE_FROM_POST
     }
    }
   ''')
   sandbox()
  }
 }
}

流水线

当从流水线配置时（不是多分支流水线），该流水线需要运行一次以应用插件触发器配置，之后这个插件才能触发作业。这是Jenkins的工作方式，不是这个插件实现的。

这意味着如果你创建一个像这样的流水线：

你需要运行一次以应用属性。你可以通过打开作业的配置视图（或者如果使用多分支流水线，则查看配置）来验证属性是否已应用。你会看到"Generic Webhook Trigger"已被选中，并且现在有来自你流水线的值。像这样：

你可以通过使用Job DSL并让Job DSL创建配置了插件的流水线作业来避免需要运行两次。此插件可用于由Pipeline Multibranch 插件创建的任务中。如果您正在寻找触发Pipeline Multibranch 插件扫描的方法，可以使用Multibranch Scan Webhook Trigger 插件。

您可以使用凭据插件从凭据中提供token。

withCredentials([string(credentialsId: 'mycredentialsid', variable: 'credentialsVariable')]) {
 properties([
  pipelineTriggers([
   [$class: 'GenericTrigger',
    ...
    token: credentialsVariable,
    ...
   ]
  ])
 ])
}

也许您想为每个任务使用不同的token。

 properties([
  pipelineTriggers([
   [$class: 'GenericTrigger',
    ...
    token: env.JOB_NAME,
    ...
   ]
  ])
 ])

或者在凭据字符串前加上任务名称。

withCredentials([string(credentialsId: 'mycredentialsid', variable: 'credentialsVariable')]) {
 properties([
  pipelineTriggers([
   [$class: 'GenericTrigger',
    ...
    token: env.JOB_NAME + credentialsVariable,
    ...
   ]
  ])
 ])
}

使用这样的脚本化Jenkinsfile：

node {
 properties([
  pipelineTriggers([
   [$class: 'GenericTrigger',
    genericVariables: [
     [key: 'ref', value: '$.ref'],
     [
      key: 'before',
      value: '$.before',
      expressionType: 'JSONPath', //可选，默认为JSONPath
      regexpFilter: '', //可选，默认为空字符串
      defaultValue: '' //可选，默认为空字符串
     ]
    ],
    genericRequestVariables: [
     [key: 'requestWithNumber', regexpFilter: '[^0-9]'],
     [key: 'requestWithString', regexpFilter: '']
    ],
    genericHeaderVariables: [
     [key: 'headerWithNumber', regexpFilter: '[^0-9]'],
     [key: 'headerWithString', regexpFilter: '']
    ],

    causeString: '在$ref上触发',

    token: 'abc123',
    tokenCredentialId: '',

    printContributedVariables: true,
    printPostContent: true,

    silentResponse: false,
    
    shouldNotFlatten: false,

    regexpFilterText: '$ref',
    regexpFilterExpression: 'refs/heads/' + BRANCH_NAME
   ]
  ])
 ])

 stage("build") {
  sh '''
  echo 来自shell的变量：
  echo ref $ref
  echo before $before
  echo requestWithNumber $requestWithNumber
  echo requestWithString $requestWithString
  echo headerWithNumber $headerWithNumber
  echo headerWithString $headerWithString
  '''
 }
}

使用这样的声明式Jenkinsfile：

pipeline {
  agent any
  triggers {
    GenericTrigger(
     genericVariables: [
      [key: 'ref', value: '$.ref']
     ],

     causeString: '在$ref上触发',

     token: 'abc123',
     tokenCredentialId: '',

     printContributedVariables: true,
     printPostContent: true,

     silentResponse: false,
     
     shouldNotFlatten: false,

     regexpFilterText: '$ref',
     regexpFilterExpression: 'refs/heads/' + BRANCH_NAME
    )
  }
  stages {
    stage('Some step') {
      steps {
        sh "echo $ref"
      }
    }
  }
}

可以使用以下命令触发：

curl -X POST -H "Content-Type: application/json" -H "headerWithNumber: nbr123" -H "headerWithString: a b c" -d '{ "before": "1848f12", "after": "5cab1", "ref": "refs/heads/develop" }' -vs "http://admin:admin@localhost:8080/jenkins/generic-webhook-trigger/invoke?requestWithNumber=nbr%20123&requestWithString=a%20string"

任务日志中将包含以下内容：

贡献变量：

    headerWithString_0 = a b c
    requestWithNumber_0 = 123
    ref = refs/heads/develop
    headerWithNumber = 123
    requestWithNumber = 123
    before = 1848f12
    requestWithString_0 = a string
    headerWithNumber_0 = 123
    headerWithString = a b c
    requestWithString = a string