一、Directives¶

Directives可用于一些执行stage时的条件判断或预处理一些数据，和Sections一致，Directives 不是一个关键字或指令，而是包含了 environment、options、parameters、triggers、stage、tools、 input、when 等配置。

二、Environment¶

Environment 主要用于在流水线中配置的一些环境变量，根据配置的位置决定环境变量的作用域。可以定义在 pipeline 中作为全局变量，也可以配置在 stage 中作为该 stage 的环境变量。

该指令支持一个特殊的方法 credentials()，该方法可用于在 Jenkins 环境中通过标识符访问预定义的凭证。对于类型为 Secret Text 的凭证，credentials()可以将该 Secret 中的文本内容赋值给环境变量。对于类型为标准的账号密码型的凭证，指定的环境变量为 username 和 password，并且也会定义两个额外的环境变量，分别为 MYVARNAME_USR 和 MYVARNAME_PSW。

假如需要定义个变量名为 CC 的全局变量和一个名为 AN_ACCESS_KEY 的局部变量，并且用 credentials 读取一个 Secret 文本，可以通过以下方式定义：

// Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any

    environment { // Pipeline 中定义，属于全局变量
        CC = 'clang'
    }

    stages {
        stage('Example') {
            environment { // 定义在 stage 中，属于局部变量
                AN_ACCESS_KEY = credentials('my-prefined-secret-text')
            }
            steps {
                sh 'printenv'
            }
        }
    }
}

三、Options¶

Jenkins 流水线支持很多内置指令，比如 retry 可以对失败的步骤进行重复执行 n 次，可以根据不同的指令实现不同的效果。比较常用的指令如下：

buildDiscarder ：保留多少个流水线的构建记录。比如： options { buildDiscarder(logRotator(numToKeepStr: '1')) }；
disableConcurrentBuilds：禁止流水线并行执行，防止并行流水线同时访问共享资源导致流水线失败。比如：options { disableConcurrentBuilds() }；
disableResume ：如果控制器重启，禁止流水线自动恢复。比如： options { disableResume() }；
newContainerPerStage：agent 为 docker 或 dockerfile 时，每个阶段将在同一个节点的新容器中运行，而不是所有的阶段都在同一个容器中运行。比如： options { newContainerPerStage () }；
quietPeriod：流水线静默期，也就是触发流水线后等待一会在执行。比如：options { quietPeriod(30) }；
retry：流水线失败后重试次数。比如：options { retry(3) }；
timeout：设置流水线的超时时间，超过流水线时间，job 会自动终止。比如：options { timeout(time: 1, unit: 'HOURS') }；
timestamps：为控制台输出时间戳。比如：options { timestamps() }。

配置示例如下，只需要添加 options 字段即可：

pipeline {
    agent any

    options {
        timeout(time: 1, unit: 'HOURS')
        timestamps()
    }

    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

Option 除了写在 Pipeline 顶层，还可以写在 stage 中，但是写在 stage 中的 option 仅支持 retry、 timeout、timestamps，或者是和 stage 相关的声明式选项，比如 skipDefaultCheckout。处于 stage 级别的 options 写法如下：

pipeline {
    agent any

    stages {
        stage('Example') {
            options {
                timeout(time: 1, unit: 'HOURS')
            }
            steps {
                echo 'Hello World'
            }
        }
    }
}

四、Parameters¶

Parameters 提供了一个用户在触发流水线时应该提供的参数列表，这些用户指定参数的值可以通过 params 对象提供给流水线的 step（步骤）。

目前支持的参数类型如下：

string：字符串类型的参数，例如：parameters { string(name: 'DEPLOY_ENV', defaultValue:'staging', description: '') }，表示定义一个名为 DEPLOY_ENV 的字符型变量，默认值为 staging；
text：文本型参数，一般用于定义多行文本内容的变量。例如 parameters { text(name: 'DEPLOY_TEXT', defaultValue: 'One\nTwo\nThree\n', description: '') }，表示定义一个名为 DEPLOY_TEXT 的变量，默认值是'One\nTwo\nThree\n'；
booleanParam：布尔型参数，例如: parameters { booleanParam(name: 'DEBUG_BUILD', defaultValue: true, description: '') }；
choice：选择型参数，一般用于给定几个可选的值，然后选择其中一个进行赋值，例如： parameters { choice(name: 'CHOICES', choices: ['one', 'two', 'three'], description: '') }，表示定义一个名为 CHOICES 的变量，可选的值为 one、two、three；
password：密码型变量，一般用于定义敏感型变量，在 Jenkins 控制台会输出为星号。例如：parameters { password(name: 'PASSWORD', defaultValue: 'SECRET', description: 'A secret password') }，表示定义一个名为 PASSWORD 的变量，其默认值为 SECRET。

Parameters 用法如下：

pipeline {
    agent any

    parameters {
        string(name: 'PERSON', defaultValue: 'Mr Jenkins', description: 'Who should I say hello to?')
        text(name: 'BIOGRAPHY', defaultValue: '', description: 'Enter some information about the person')
        booleanParam(name: 'TOGGLE', defaultValue: true, description: 'Toggle this value')
        choice(name: 'CHOICE', choices: ['One', 'Two', 'Three'], description: 'Pick something')
        password(name: 'PASSWORD', defaultValue: 'SECRET', description: 'Enter a password')
    }

    stages {
        stage('Example') {
            steps {
                echo "Hello ${params.PERSON}"
                echo "Biography: ${params.BIOGRAPHY}"
                echo "Toggle: ${params.TOGGLE}"
                echo "Choice: ${params.CHOICE}"
                echo "Password: ${params.PASSWORD}"
            }
        }
    }
}

五、Triggers¶

在 Pipeline 中可以用 triggers 实现自动触发流水线执行任务，可以通过 Webhook、Cron、 pollSCM 和 upstream 等方式触发流水线。

假如某个流水线构建的时间比较长，或者某个流水线需要定期在某个时间段执行构建，可以使用 cron 配置触发器，比如周一到周五每隔四个小时执行一次：

pipeline {
    agent any

    triggers {
        cron('H */4 * * 1-5')
    }

    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

注意:H的意思不是HOURS的意思，而是Hash的缩写。主要为了解决多个流水线在同一时间同时运行带来的系统负载压力。

使用cron字段可以定期执行流水线，如果代码更新想要重新触发流水线，可以使用pollSCM字段：

pipeline {
    agent any

    triggers {
        pollSCM('H */4 * * 1-5')
    }

    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

除了上述触发器外，也支持upstream型的触发器。upstream可以根据上游job的执行结果决定是否触发该流水线。比如当job1或job2执行成功时触发该流水线：

pipeline {
    agent any

    triggers {
        upstream(upstreamProjects: 'job1,job2', threshold: hudson.model.Result.SUCCESS)
    }

    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

目前支持的状态有 SUCCESS、UNSTABLE、FAILURE、NOT_BUILT、ABORTED 等。

Jenkins声明式流水线：Environment、Options、Parameters与Triggers

一、Directives¶

二、Environment¶

三、Options¶

四、Parameters¶

五、Triggers¶

评论区