Jenkins Pipeline 参数详解

Pipeline 是什么

Jenkins Pipeline 实际上是基于 Groovy 实现的 CI/CD 领域特定语言（DSL），主要分为两类，一类叫做 Declarative Pipeline，一类叫做 Scripted Pipeline。

Declarative Pipeline 体验上更接近于我们熟知的 travis CI 的 travis.yml，通过声明自己要做的事情来规范流程，形如：

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                //
            }
        }
        stage('Test') {
            steps {
                //
            }
        }
        stage('Deploy') {
            steps {
                //
            }
        }
    }
}

而 Scripted Pipeline 则是旧版本中 Jenkins 支持的 Pipeline 模式，主要是写一些 groovy 的代码来制定流程：

node {  
    stage('Build') {
        //
    }
    stage('Test') {
        //
    }
    stage('Deploy') {
        //
    }
}

一般情况下声明式的流水线已经可以满足我们的需要，只有在复杂的情况下才会需要脚本式流水线的参与。

过去大家经常在 Jenkins 的界面上直接写脚本来实现自动化，但是现在更鼓励大家通过在项目中增加 Jenkinsfile 的方式把流水线固定下来，实现 Pipeline As Code，Jenkins 的 Pipeline 插件将会自动发现并执行它。

语法

Declarative Pipeline 最外层有个 pipeline 表明它是一个声明式流水线，下面会有 4 个主要的部分： agent，post，stages，steps，我会逐一介绍一下。

Agent

agent 主要用于描述整个 Pipeline 或者指定的 Stage 由什么规则来选择节点执行。Pipeline 级别的 agent 可以视为 Stage 级别的默认值，如果 stage 中没有指定，将会使用与 Pipeline 一致的规则。在最新的 Jenkins 版本中，可以支持指定任意节点(any)，不指定(none)，标签(label)，节点(node)，docker，dockerfile 和 kubernetes 等，具体的配置细节可以查看文档，下面是一个使用 docker 的样例：

agent {
    docker {
        image 'myregistry.com/node'
        label 'my-defined-label'
        registryUrl 'https://myregistry.com/'
        registryCredentialsId 'myPredefinedCredentialsInJenkins'
        args '-v /tmp:/tmp'
    }
}

Tips:

• 如果 Pipeline 选择了 none，那么 stage 必须要指定一个有效的 agent，否则无法执行
• Jenkins 总是会使用 master 来执行 scan multibranch 之类的操作，即使 master 配置了 0 executors
• agent 指定的是规则而不是具体的节点，如果 stage 各自配置了自己的 agent，需要注意是不是在同一个节点执行的

Stages && Stage

Stages 是 Pipeline 中最主要的组成部分，Jenkins 将会按照 Stages 中描述的顺序从上往下的执行。Stages 中可以包括任意多个 Stage，而 Stage 与 Stages 又能互相嵌套，除此以外还有 parallel 指令可以让内部的 Stage 并行运行。实际上可以把 Stage 当作最小单元，Stages 指定的是顺序运行，而 parallel 指定的是并行运行。

接下来的这个 case 很好的说明了这一点：

pipeline {
    agent none
    stages {
        stage('Sequential') {
            stages {
                stage('In Sequential 1') {
                    steps {
                        echo "In Sequential 1"
                    }
                }
                stage('In Sequential 2') {
                    steps {
                        echo "In Sequential 2"
                    }
                }
                stage('Parallel In Sequential') {
                    parallel {
                        stage('In Parallel 1') {
                            steps {
                                echo "In Parallel 1"
                            }
                        }
                        stage('In Parallel 2') {
                            steps {
                                echo "In Parallel 2"
                            }
                        }
                    }
                }
            }
        }
    }
}

除了指定 Stage 之间的顺序关系之外，我们还可以通过 when 来指定某个 Stage 指定与否：比如要配置只有在 Master 分支上才执行 push，其他分支上都只运行 build

stages {
  stage('Build') {
    when {
      not { branch 'master' }
    }
    steps {
      sh './scripts/run.py build'
    }
  }
  stage('Run') {
    when {
      branch 'master'
    }
    steps {
      sh './scripts/run.py push'
    }
  }
}

还能在 Stage 的级别设置 environment，这些就不展开了，文档里有更详细的描述。

Steps

steps 是 Pipeline 中最核心的部分，每个 Stage 都需要指定 Steps。Steps 内部可以执行一系列的操作，任意操作执行出错都会返回错误。完整的 Steps 操作列表可以参考 Pipeline Steps Reference，这里只说一些使用时需要注意的点。

• groovy 语法中有不同的字符串类型，其中 'abc' 是 Plain 字符串，不会转义 ${WROKSPACE} 这样的变量，而 "abc" 会做这样的转换。此外还有 ''' xxx ''' 支持跨行字符串，""" 同理。
• 调用函数的 () 可以省略，使得函数调用形如 updateGitlabCommitStatus name: 'build', state: 'success'，通过 , 来分割不同的参数，支持换行。
• 可以在声明式流水线中通过 script 来插入一段 groovy 脚本

Post

post 部分将会在 pipeline 的最后执行，经常用于一些测试完毕后的清理和通知操作。文档中给出了一系列的情况，比较常用的是 always，success 和 failure。

比如说下面的脚本将会在成功和失败的时候更新 gitlab 的状态，在失败的时候发送通知邮件：

post {
  failure {
    updateGitlabCommitStatus name: 'build', state: 'failed'
    emailext body: '$DEFAULT_CONTENT', recipientProviders: [culprits()], subject: '$DEFAULT_SUBJECT'
  }
  success {
    updateGitlabCommitStatus name: 'build', state: 'success'
  }
}

每个状态其实都相当于于一个 steps，都能够执行一系列的操作，不同状态的执行顺序是事先规定好的，就是文档中列出的顺序。

Shared Libraries

同一个 Team 产出的不同项目往往会有着相似的流程，比如 golang 的大部分项目都会执行同样的命令。这就导致了人们经常需要在不同的项目间复制同样的流程，而 Shared Libraries 就解决了这个问题。通过在 Pipeline 中引入共享库，把常用的流程抽象出来变成一个的指令，简化了大量重复的操作。

在配置好 lib 之后，Jenkins 会在每个 Pipeline 启动前去检查 lib 是否更新并 pull 到本地，根据配置决定是否直接加载。

所有的 Shared Libraries 都要遵循相同的项目结构：

(root)
+- src                     # Groovy source files
|   +- org
|       +- foo
|           +- Bar.groovy  # for org.foo.Bar class
+- vars
|   +- foo.groovy          # for global 'foo' variable
|   +- foo.txt             # help for 'foo' variable
+- resources               # resource files (external libraries only)
|   +- org
|       +- foo
|           +- bar.json    # static helper data for org.foo.Bar

目前我们的使用比较低级，所以只用到了 vars 来存储全局的变量。

vars 下的每一个 foo.groovy 文件都是一个独立的 namespace，在 Pipeline 中可以以 foo.XXX 的形式来导入。比如我们有 vars/log.groovy：

def info(message) {
    echo "INFO: ${message}"
}

def warning(message) {
    echo "WARNING: ${message}"
}

那么 Jenkinsfile 中就可以这样调用：

// Jenkinsfile
steps {
  log.info 'Starting'
  log.warning 'Nothing to do!'
}

大家可能已经注意到了，在 groovy 文件中，我们可以直接像在 steps 中一样调用已有的方法，比如 echo 和 sh 等。

我们也能在 groovy 文件中去引用 Java 的库并返回一个变量，比如：

#!/usr/bin/env groovy
import java.util.Random;

def String name() {
  def rand = new Random()
  def t = rand.nextInt(1000)
  return String.valueOf(t)
}

这样就能够在 JenkinsFile 中去设置一个环境变量：

// Jenkinsfile
environment {
  NAME = random.name()
}

除了定义方法之外，我们还能让这个文件本身就能被调用，只需要定义一个 call 方法：

#!/usr/bin/env groovy

def call() {
  sh "hello, world"
}

还能够定义一个新的 section，接受一个 Block：

def call(Closure body) {
    node('windows') {
        body()
    }
}

这样可以让指定的 Body 在 windows 节点上调用：

// Jenkinsfile
windows {
    bat "cmd /?"
}

常用技巧

发送邮件通知

主要使用 emailext，需要在 Jenkins 的配置界面事先配置好，可用的环境变量和参数可以参考文档 Email-ext plugin

emailext body: '$DEFAULT_CONTENT',  recipientProviders: [culprits(),developers()], subject: '$DEFAULT_SUBJECT'

结果同步到 gitlab

同样需要配置好 gitlab 插件，在 Pipeline 中指定 options：

// Jenkisfile
options {
  gitLabConnection('gitlab')
}

然后就可以在 post 中根据不同的状态来更新 gitlab 了：

// Jenkisfile
failure {
  updateGitlabCommitStatus name: 'build', state: 'failed'
}
success {
  updateGitlabCommitStatus name: 'build', state: 'success'
}

文档参考：Build status configuration

构建过程中可用的环境变量列表

Jenkins 会提供一个完整的列表，只需要访问 <your-jenkins-url>/env-vars.html/ 即可，别忘了需要使用 "${WORKSPACE}"

在 checkout 前执行自定义操作

在 Multibranch Pipeline 的默认流程中会在 checkout 之前和之后执行 git clean -fdx，如果在测试中以 root 权限创建了文件，那么 jenkins 会因为这个命令执行失败而报错。所以我们需要在 checkout 之前执行自定义的任务：

#!/usr/bin/env groovy

// var/pre.groovy
def call(Closure body) {
  body()
  checkout scm
}

在 Jenkinsfile 中配置以跳过默认的 checkout 行为：

// Jenkisfile
options {
  skipDefaultCheckout true
}

在每个 stage 中执行自定义的任务即可：

// Jenkisfile
stage('Compile') {
  agent any
  steps {
    pre {
      sh 'pre compile'
    }
    sh 'real compile'
  }
}

总结

Jenkins 作为使用最为广泛的 CI/CD 平台，网上流传着无数的脚本和攻略，在学习和开发的时候一定要从基本出发，了解内部原理，多看官方的文档，不要拿到一段代码就开始用，这样才能不会迷失在各式各样的脚本之中。

更重要的是要结合自己的业务需求，开发和定制属于自己的流程，不要被 Jenkins 的框架限制住。比如我们是否可以定义一个自己的 YAML 配置文件，然后根据 YAML 来生成 Pipeline，不需要业务自己写 Pipeline 脚本，规范使用，提前检查不合法的脚本，核心的模块共同升级，避免了一个流程小改动需要所有项目组同步更新。这是我现在正在做的事情，有机会再跟大家分享～