Jenkins Pipeline语法(中)

指令 Directives

环境 environment

environment指令指定一系列键值对,这些键值对将被定义为所有step或特定stage的step的环境变量,具体取决于environment指令位于Pipeline中的位置。

该指令支持一种特殊的助手方法credentials(),可以通过Jenkins环境中的标识符来访问预定义的凭据。对于类型为“Secret Text”的凭据,该 credentials()方法将确保环境变量中包含该Secret Text内容。对于“标准用户名和密码”类型的凭证,指定的环境变量将被设置为username:password并且将自动定义两个附加的环境变量:MYVARNAME_USRMYVARNAME_PSW

是否必填
参数没有
允许出现在pipeline块内或stage
例如:
Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    environment { 
        CC = 'clang'
    }
    stages {
        stage('Example') {
            environment { 
                AN_ACCESS_KEY = credentials('my-prefined-secret-text') 
            }
            steps {
                sh 'printenv'
            }
        }
    }
}
  1. environment顶级pipeline块中使用的指令将适用于Pipeline中的所有步骤
  2. 在一个stage中定义的environment指令只将给定的环境变量应用于该stage中的步骤
  3. environment具有一个帮助方法credentials(),可用于在Jenkins环境中通过其标识符访问预定义的凭据

选项 options

options指令允许在Pipeline内配置Pipeline专用选项。Pipeline提供了许多这些选项,例如buildDiscarder,但它们也可能由插件提供,例如 timestamps

是否必填
参数没有
允许出现在pipeline块内,只有一次

可用选项

  • buildDiscarder

    持久化工件和控制台输出,用于保存Pipeline最近几次运行的数据。例如:options { buildDiscarder(logRotator(numToKeepStr: '1')) }

  • checkoutToSubdirectory

    在工作区的子目录中执行源代码检出。例如:options { checkoutToSubdirectory('foo') }

  • disableConcurrentBuilds

    不允许并行执行Pipeline。可用于防止同时访问共享资源等。例如:options { disableConcurrentBuilds() }

  • preserveStashes

    保留已完成构建的存储,用于stage重新启动。例如:options { preserveStashes() }保存最近完成的构建中的stash,或者options { preserveStashes(5) }保留最近五个完成的构建中的stash。

  • quietPeriod

    设置管道的静默期(以秒为单位),覆盖全局默认值。例如:options { quietPeriod(30) }

  • retry

    如果失败,请按指定的次数重试整个管道。例如:options { retry(3) }

  • skipDefaultCheckout

    agent指令中默认跳过源代码检出。例如:options { skipDefaultCheckout() }

  • skipStagesAfterUnstable

    一旦构建状态进入了“不稳定”状态,就跳过stage。例如:options { skipStagesAfterUnstable() }

  • timeout

    设置Pipeline运行的超时时间,之后Jenkins应该中止Pipeline。例如:options { timeout(time: 1, unit: 'HOURS') }

  • timestamps

    当执行时,预处理由Pipeline生成的所有控制台输出运行时间。例如:options { timestamps() }

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

指定一个小时的全局执行超时,之后Jenkins将中止Pipeline运行。

stage选项

stageoptions指令类似于Pipeline根目录中的options指令。但是,stageoptions只能包含与stage相关的步骤,如retrytimeouttimestamps,或声明性选项,如skipDefaultCheckout

stage内,options在进入agent或检查任何when条件之前调用指令中的步骤。

可用的stage选项
  • skipDefaultCheckout

    默认情况下,在agent指令中跳过检查源代码管理中的代码。例如:options { skipDefaultCheckout() }

  • timeout

    设置此stage的超时时间,之后Jenkins应该中止该stage。例如:options { timeout(time: 1, unit: 'HOURS') }

  • retry

    如果失败,请重试此stage指定次数。例如:options { retry(3) }

  • timestamps

    当执行时,预处理由Pipeline生成的所有控制台输出运行时间。例如:options { timestamps() }

Jenkinsfile(声明性管道)

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

为stageExample指定一小时的执行超时,之后Jenkins将中止Pipeline运行。

参数 parameters

parameters指令提供用户在触发Pipeline时应提供的参数列表。这些用户指定的参数的值通过该params对象可用于Pipeline步骤,具体用法见示例

是否必填
参数没有
允许出现在pipeline块内,只有一次
可用参数
  • string

    字符串类型的参数,例如: parameters { string(name: 'DEPLOY_ENV', defaultValue: 'staging', description: '') }

  • 文本

    一个text参数,可以包含多行,例如: parameters { text(name: 'DEPLOY_TEXT', defaultValue: 'One\nTwo\nThree\n', description: '') }

  • booleanParam

    一个布尔参数,例如: parameters { booleanParam(name: 'DEBUG_BUILD', defaultValue: true, description: '') }

  • choice

    选择参数,例如: parameters { choice(name: 'CHOICES', choices: ['one', 'two', 'three'], description: '') }

  • file

    一个文件参数,指定用户在计划构建时要提交的文件,例如: parameters { file(name: 'FILE', description: 'Some file to upload') }

  • password

    密码参数,例如: parameters { password(name: 'PASSWORD', defaultValue: 'SECRET', description: 'A secret password') }

例如:
Jenkinsfile (Declarative Pipeline)
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')

        file(name: "FILE", description: "Choose a file to upload")
    }
    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

triggers指令定义了Pipeline应重新触发的自动化方式。对于与源代码集成的Pipeline,如GitHub或BitBucket,triggers可能不需要基于webhook的集成可能已经存在。目前只有两个可用的触发器是cron和pollSCM。

需要没有
参数没有
允许只有一次,在pipeline块内。
  • cron

    接受一个cron风格的字符串来定义Pipeline应重新触发的常规间隔,例如: triggers { cron('H 4/* 0 0 1-5') }

  • pollSCM

    接受一个cron风格的字符串来定义Jenkins应该检查新的源更改的常规间隔。如果存在新的更改,则Pipeline将被重新触发。例如:triggers { pollSCM('H 4/* 0 0 1-5') }

该pollSCM触发器仅在Jenkins 2.22或更高版本可用

例如:

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

Jenkins cron 语法

Jenkins cron语法遵循cron实用程序的语法 (略有不同)。具体来说,每行包含由TAB或空格分隔的5个字段:

分钟小时DOMDOW
一小时内的分钟数(0-59)一天中的小时(0-23)每月的某一天(1-31)</ td>月(1-12)星期几(0-7),其中0和7是星期日。

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

  • * 指定所有有效值
  • M-N 指定一系列值
  • M-N/X或者按照指定范围或整个有效范围的*/X间隔步长X
  • A,B,…,Z 枚举多个值

为了允许定期计划的任务在系统上产生均匀负载,应尽可能使用符号H(“哈希”)。例如,使用0 0 * * *十几个日常工作将导致午夜大量飙升。相比之下,使用H H * * *仍然会每天执行一次,但不能同时执行,更好地使用有限的资源。

所述H符号可以与范围内使用。例如,H H(0-7) * * * 表示从凌晨12:00(午夜)到早上7:59之间的某个时间段。您也可以使用H带有或不带范围的步长间隔。

H符号可以被认为是在一定范围内的随机值,但它实际上是作业名称的hash值,而不是随机函数的哈希值,所以对于给定的项目该值仍然是稳定的。

请注意,对于月份日期字段,由于月份长度可变,短期周期(例如/3H/3)将不会在大多数月份结束时始终如一地工作)。例如,/3 将在第1st, 4th, …31st 天运行, 然后在下个月的第一天运行。 哈希总是在1-28的范围内运行, 所以 H/3在一个月末将产生3到6天的空隙。(更长的周期也会有不一致的长度,但效果可能相对不太明显。)

#开头的行和空行将被当做注释忽略。

此外,还有如下方便的别名:@yearly@annually@monthly@weekly@daily@midnight,和@hourly。这些使用哈希系统进行自动平衡。例如,@hourlyH * * * *都意味着在一小时内的任何时间。 @midnight实际上意味着在凌晨12:00到凌晨2:59之间的某个时间。

每十五分钟(也许在:07,:22,:37,:52)

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

每小时上半场每十分钟一次(三次,也许在:04,:14,:24)

triggers{ H(0-29)/10 * * * *) }

从上午9:45开始每小时45分钟一次,每个工作日下午3:45结束。

triggers{ 45 9-16/2 * * 1-5) }

每个工作日上午9点到下午5点之间每两小时一次(可能在上午10:38,下午12点38分,下午2点38分,下午4点38分)

triggers{ H H(9-16)/2 * * 1-5) }

除了12月之外,每个月的1日和15日每天一次

triggers{ H H 1,15 1-11 *) }

阶段 stage

stage指令在stages部分中,应包含步骤部分,可选agent部分或其他特定于stage的指令。实际上,Pipeline完成的所有实际工作都将包含在一个或多个stage指令中。

是否必填至少一个
参数一个必填参数,一个用于stage名称的字符串
允许出现在stages
例如:
Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

工具 tools

定义自动安装和放置工具的部分PATH。如果指定agent none,这将被忽略。

是否必填
参数没有
允许出现在pipeline块或stage块内
支持的工具
  • maven
  • jdk
  • gradle

例如:

Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    tools {
        maven 'apache-maven-3.0.1' 
    }
    stages {
        stage('Example') {
            steps {
                sh 'mvn --version'
            }
        }
    }
}

工具名称必须在Jenkins 管理Jenkins → 全局工具配置中预置。

输入 input

stageinput指令允许您使用input步骤提示输入 。在进入stageagent或评估其when状态之前,stage将处于暂停状态。如果input 获得批准,stage则将继续。作为input提供的任何参数将在stage的剩下部分的环境中可用 。

配置选项
  • message

    必填。这将在用户提交input时呈现给用户。

  • id

    这是一个可选的标识符input。默认为stage名称。

  • ok

    input表单上“ok”按钮的可选文本。

  • submitter

    允许提交此input选项的用户或外部组名列表,用逗号分隔。默认允许任何用户。

  • submitterParameter

    要使用submitter名称设置的环境变量的名称,可选(如果存在)。

  • parameters

    用于提示提供的可选参数列表。有关更多信息,请参阅参数

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

条件 when

when指令允许Pipeline根据给定的条件确定是否执行该stagewhen指令必须至少包含一个条件。如果when指令包含多个条件,则所有子条件必须都返回true,stage将会执行。这与子条件嵌套在一个allOf条件中相同(见下面的例子)。

更复杂的条件结构可使用嵌套条件建:notallOfanyOf。嵌套条件可以嵌套到任意深度。

是否必填
参数没有
允许出现在stage指令内
内置条件
  • branch

    当正在构建的分支与给出的分支模式匹配时执行stage,例如:when { branch 'master' }。请注意,这仅适用于多分支Pipeline。

  • environment

    当指定的环境变量设置为给定值时执行stage,例如: when { environment name: 'DEPLOY_TO', value: 'production' }

  • expression

    当指定的Groovy表达式求值为true时执行stage,例如: when { expression { return params.DEBUG_BUILD } }

  • not

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

  • allOf

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

  • anyOf

    当至少一个嵌套条件为真时执行舞台。必须至少包含一个条件。例如:when { anyOf { branch 'master'; branch 'staging' } }

例如:
Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    stages {
        stage('Example Build') {
            steps {
                echo 'Hello World'
            }
        }
        stage('Example Deploy') {
            when {
                branch 'production'
            }
            steps {
                echo 'Deploying'
            }
        }
    }
}
Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    stages {
        stage('Example Build') {
            steps {
                echo 'Hello World'
            }
        }
        stage('Example Deploy') {
            when {
                branch 'production'
                environment name: 'DEPLOY_TO', value: 'production'
            }
            steps {
                echo 'Deploying'
            }
        }
    }
}
Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    stages {
        stage('Example Build') {
            steps {
                echo 'Hello World'
            }
        }
        stage('Example Deploy') {
            when {
                allOf {
                    branch 'production'
                    environment name: 'DEPLOY_TO', value: 'production'
                }
            }
            steps {
                echo 'Deploying'
            }
        }
    }
}
Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    stages {
        stage('Example Build') {
            steps {
                echo 'Hello World'
            }
        }
        stage('Example Deploy') {
            when {
                branch 'production'
                anyOf {
                    environment name: 'DEPLOY_TO', value: 'production'
                    environment name: 'DEPLOY_TO', value: 'staging'
                }
            }
            steps {
                echo 'Deploying'
            }
        }
    }
}
Jenkinsfile (Declarative Pipeline)
pipeline {
    agent any
    stages {
        stage('Example Build') {
            steps {
                echo 'Hello World'
            }
        }
        stage('Example Deploy') {
            when {
                expression { BRANCH_NAME ==~ /(production|staging)/ }
                anyOf {
                    environment name: 'DEPLOY_TO', value: 'production'
                    environment name: 'DEPLOY_TO', value: 'staging'
                }
            }
            steps {
                echo 'Deploying'
            }
        }
    }
}
    原文作者:程序员文集
    原文地址: https://www.jianshu.com/p/7a852d58d9a9
    本文转自网络文章,转载此文章仅为分享知识,如有侵权,请联系博主进行删除。
点赞