八、流水线语法之Directives

一、environment

environment指令指定了一系列键值对，这些键值对将被定义为所有步骤或阶段特定步骤的环境变量，具体取决于环境指令在管道中的位置。该指令支持一个特殊的助手方法credentials（），该方法可用于通过Jenkins环境中的标识符访问预定义的credentials。

支持的凭据类型

Secret Text:指定的环境变量将设置为“机密文本”内容
 
Secret File:指定的环境变量将设置为临时创建的文件文件的位置
 
Username and password:指定的环境变量将设置为username:password，并且将自动定义另外两个环境变量：MYVARNAME_USR和MYVARNNAME_PSW。
 
SSH with Private Key:指定的环境变量将被设置为临时创建的SSH密钥文件的位置，并且将自动定义两个附加的环境变量：MYVARNAME_USR和MYVARNNAME_PSW（保存密码短语）。

 

例如：

pipeline {
    agent any
    environment { 
        CC = 'clang'
    }
    stages {
        stage('Example') {
            environment { 
                AN_ACCESS_KEY = credentials('my-predefined-secret-text') 
            }
            steps {
                sh 'printenv'
            }
        }
    }
}

二、options

options指令允许从管道本身中配置管道特定的选项。Pipeline提供了许多这样的选项，例如buildDiscarder，但它们也可以由插件提供，例如时间戳。
 
可用选项如下：

buildDiscarder
为特定数量的最近管道运行持久化工件和控制台输出。例如：options｛buildDiscarder（logRotator（numToKeepStr:“1”））｝
 
checkoutToSubdirectory
在工作区的子目录中执行自动源代码管理签出。例如：options｛checkoutToSubdirectory（'fo'）｝
 
disableConcurrentBuilds
不允许同时执行管道。对于防止同时访问共享资源等可能很有用。例如：选项｛disableConcurrentBuilds（）｝用于在已经有正在执行的管道生成时对生成进行排队，或者选项｛disableConcurrentBuilds（abortPrevious:true）｝可用于中止正在运行的生成并启动新生成。
 
disableResume
如果控制器重新启动，则不允许恢复管道。例如：选项｛disableResume（）｝
 
newContainerPerStage
与docker或dockerfile顶级代理一起使用。指定后，每个阶段将在同一节点上的新容器实例中运行，而不是所有阶段都在同一容器实例中执行。
 
overrideIndexTriggers
允许覆盖分支索引触发器的默认处理方式。如果在多分支或组织标签上禁用了分支索引触发器，则选项｛overrideIndexTriggers（true）｝将仅为此作业启用它们。否则，选项｛overrideIndexTriggers（false）｝将仅对此作业禁用分支索引触发器。
 
preserveStashes
保留已完成构建的存储，以便与阶段重新启动一起使用。例如：选项｛preserveStashes（）｝以保留最近完成的构建中的存储，或选项｛PreserveStahes（buildCount:5）｝来保留最近五个完成的构建的存储。
 
quietPeriod
设置管道的静默期（以秒为单位），覆盖全局默认值。例如：选项｛quietPeriod（30）｝
 
retry
失败时，按指定次数重试整个管道。例如：选项｛重试（3）｝
 
skipDefaultCheckout
在代理指令中，默认情况下跳过从源代码管理签出代码。例如：选项｛skipDefaultCheckout（）｝
 
skipStagesAfterUnstable
一旦生成状态变为不稳定，就跳过阶段。例如：选项｛skipStagesAfterUnstable（）｝
 
timeout
设置管道运行的超时时间，在此之后Jenkins应中止管道。例如：选项｛timeout（时间：1，单位：“HOURS”）｝
 
timestamps
使用行发出的时间来准备管道运行生成的所有控制台输出。例如：options｛timestamps（）｝
 
parallelsAlwaysFailFast
为管道中的所有后续并行阶段设置failfast true。例如：选项｛parallelsAlwaysFailFast（）｝

 
例如：

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

stage选项
阶段的options指令类似于管道根目录下的options。但是，stage级选项只能包含重试、超时或时间戳等步骤，或与阶段相关的声明性选项，如skipDefaultCheckout。
 
可用选项如下：

skipDefaultCheckout
在代理指令中，默认情况下跳过从源代码管理签出代码。例如：选项｛skipDefaultCheckout（）｝

 

timeout
为这个阶段设置一个超时时间，在此之后Jenkins应该中止这个阶段。例如：选项｛timeout（时间：1，单位：“HOURS”）｝

 

retry
如果失败，请按指定次数重试此阶段。例如：选项｛重试（3）｝

 

timestamps
在此阶段中生成的所有控制台输出都要使用行发出的时间进行预处理。例如：options｛timestamps（）｝

三、parameters

parameters指令提供了用户在触发管道时应提供的参数列表。这些用户指定参数的值通过params对象提供给管道步骤。每个参数都有一个名称和值，具体取决于参数类型。当构建开始时，这些信息将作为环境变量导出，从而允许构建配置的后续部分访问这些值。

 

可用参数：

string
string类型的参数，比如：parameters { string(name: 'DEPLOY_ENV', defaultValue: 'staging', description: '') }
 

text
可以包含多行的text类型的参数，比如：parameters { text(name: 'DEPLOY_TEXT', defaultValue: 'One\nTwo\nThree\n', description: '') }

 

booleanParam
boolean类型的参数，比如：parameters { booleanParam(name: 'DEBUG_BUILD', defaultValue: true, description: '') }

 

choice
选择类型的参数，比如：parameters { choice(name: 'CHOICES', choices: ['one', 'two', 'three'], description: '') }
 
password
密码类型的参数，比如：parameters { password(name: 'PASSWORD', defaultValue: 'SECRET', description: 'A secret password') }

 

例如：

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

触发器指令定义了重新触发管道的自动方式。对于与GitHub或BitBucket等源集成的管道，触发器可能不是必要的，因为基于webhook的集成可能已经存在。当前可用的触发器有cron、pollSCM和upstream。

 

1. cron：接受一个cron样式的字符串来定义重新触发管道的规则间隔，例如：triggers｛cron（'H*/4**1-5'）｝
2. pollSCM:接受一个cron样式的字符串，以定义Jenkins检查新的源更改的定期间隔。如果存在新的更改，将重新触发管道。例如：triggers { pollSCM('H */4 * * 1-5') }
3. upstream:接受以逗号分隔的作业字符串和阈值。当字符串中的任何作业以最小阈值结束时，将重新触发管道。例如：triggers { upstream(upstreamProjects: 'job1,job2', threshold: hudson.model.Result.SUCCESS) }

 

例如：

pipeline {
    agent any
    triggers {
        cron('H */4 * * 1-5')
    }
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

Jenkins cron语法

Jenkins-cron语法遵循cron实用程序的语法（略有不同）。具体来说，每行由5个字段组成，这些字段由TAB或空格分隔：

分钟	小时	月中第几天	月份	周
0-59	0-23	1-31	1-12	星期几（0-7），其中0和7是星期天。

要为一个字段指定多个值，可以使用以下运算符。按照优先顺序，

• *指定所有有效值
• M-N指定一个值范围
• M-N/X或*/X在指定范围或整个有效范围内以X的间隔递增
• A、 B，…​,Z枚举多个值

 

H符号可以与范围一起使用。例如，H H（0-7）***表示上午12:00（午夜）至上午7:59之间的某个时间。您也可以使用带H的步长间隔，带或不带范围。H符号可以被认为是一个范围内的随机值，但它实际上是作业名称的散列，而不是随机函数，因此对于任何给定的项目，该值都保持稳定。

例如

triggers{ cron('H/15 * * * *') }

每隔15分钟触发。

五、stage

stage指令位于stages部分，应包含一个steps部分、一个可选代理部分或其他特定于stage的指令。实际上，管道所做的所有实际工作都将封装在一个或多个阶段指令中。例如：

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

六、tools

定义要自动安装并放到PATH上的工具的部分。如果配置 agent none，则会忽略tools。例如：

pipeline {
    agent any
    tools {
        maven 'my_maven' 
    }
    stages {
        stage('Example') {
            steps {
                sh 'mvn --version'
            }
        }
    }
}

工具名称必须在管理Jenkins下的Jenkins中预先配置。tools将对应的工具加入到PATH中，之后可以在命令中使用。在这里：
 

 

 

七、input

stage中的input指令允许您使用input步骤提示输入。

配置选项

• message：提示消息，必须
• id：input的可选标识符。默认值是stage的名称。
• ok：确定按钮的文本
• submitter：允许哪些用户可以提交
• submitterParameter：要使用提交者名称设置的环境变量的可选名称（如果存在）。
• parameters：提示提交者提供的可选参数列表。

 

例子：

pipeline {
    agent any
    stages {
        stage('Example') {
            input {
                message "Should we continue?"
                ok "Yes, we should."
                parameters {
                    string(name: 'PERSON', defaultValue: 'Mr Jenkins', description: 'Who should I say hello to?')
                }
            }
            steps {
                echo "Hello, ${PERSON}, nice to meet you."
            }
        }
    }
}

构建时发现卡住了，查看后发现：
 

 

必须要输入才能往下构建。同时确定按钮的文本是配置的ok属性。

八、when

when指令允许管道根据给定条件确定是否应执行阶段。when指令必须至少包含一个条件。如果when指令包含多个条件，则所有子条件都必须返回true才能执行阶段。这与子条件嵌套在allOf条件中的情况相同。如果使用anyOf条件，请注意，一旦找到第一个“true”条件，该条件就会跳过剩余的测试。

内建条件

branch
当正在构建的分支与给定的分支模式匹配时，执行阶段，例如：when｛branch‘master’｝。请注意，这仅适用于多分支管道。可选的参数比较器可以添加在属性之后，以指定如何为匹配评估任何模式：EQUALS用于简单的字符串比较，GLOB（默认值）用于ANT样式的路径GLOB，或REGEXP用于正则表达式匹配。例如：when { branch pattern: "release-\\d+", comparator: "REGEXP"}

buildingTag
当生成正在生成标记时，执行阶段。示例：when { buildingTag() }

equals
当期望值等于实际值时执行阶段，例如：when { equals expected: 2, actual: currentBuild.number }

expression
当指定的Groovy表达式计算结果为true时执行阶段，例如：when｛expression｛return params.DEBUG_BUILD｝｝

tag
如果TAG_NAME变量与给定模式匹配，则执行阶段。示例：when { tag "release-*" }。如果提供了空模式，则如果TAG_NAME变量存在（与buildingTag（）相同），则阶段将执行。

not
当嵌套条件为false时，执行阶段。必须包含一个条件。例如：when { not { branch 'master' } }

allOf
当所有嵌套条件都为true时，执行阶段。必须至少包含一个条件。例如:when { allOf { branch 'master'; environment name: 'DEPLOY_TO', value: 'production' } }

anyOf
当至少有一个嵌套条件为true时，执行阶段。必须至少包含一个条件。例如：when { anyOf { branch 'master'; branch 'staging' } }

triggeredBy
当给定的参数触发当前生成时，执行阶段。例如：when { triggeredBy 'SCMTrigger' }

 

例子：

pipeline {
    agent any
    stages {
        stage('Example Build') {
            steps {
                echo 'Hello World'
            }
        }
        stage('Example Deploy') {
            when {
                branch 'production'
            }
            steps {
                echo 'Deploying'
            }
        }
    }
}

当分支时production才输出Deploying。