Jenkins-pipeline语法

Pipeline概念

Pipeline是将一个命令/程序/进程的输出发送到另一个命令/程序/进程，进行进一步处理
Pipeline的代码定义了整个构建过程

基本的Pipeline语法格式

声明式的pipeline语法格式
所有的声明都必须包含在pipeline{}中
块只能有节段，指令，步骤或者赋值语句组成
节段：agent，stages，post，steps
指令：environment，options，parameters，triggers，stage，input，tool，when

pipeline{
    agent any
    stages {
        stage("build"){
           steps{
           //TODO
               }
            }
        stage("Test"){
           steps{
             // TODO
               }
             }
         stage("deploy"){
                 steps{
                   //TODO
                      } 
               }
          }
       }

创建一个简单的pipeline项目

新建一个item，选择“Pipeline”-》选择“Pipeline script”
输入脚本

pipeline{
    agent any
    stages{
        stage("build"){
            steps{
                echo "Build"
            }
        }
        stage("Test"){
            steps{
                echo "Test"
            }
        }
        stage("Deployment"){
            steps{
                echo "Deployment"
            }
        }
    }  
}

手动点击“build Now”，可以看到这个pipeline的每个阶段的视图

rerun pipeline

当pipeline执行完成后，需要执行某一个stage，可以进入到这次build，选择“从指定阶段重新运行”

agent

指定了整个pipeline或者特定的部分在jenkins中执行的位置比如在哪一个node上执行，agent可以是node，也可以是docker
必须在pipeline的顶层被定义，stage中可选
在pipeline块的顶层被定义，是全局的agent，当全局的agent为none时每个stage可以定义自己的agent

agent参数介绍

agent有以下参数
any-----在任何可用的代理上执行流水线或阶段，agent any
none-----pipeline的顶层没有设置全局的agent，那么每个stage需要设置自己的agent ，agent none
label-----在提供了标签的代理上执行pipeline或者阶段。 agent {label ‘my-defined-label’}
node—在提供的node上执行pipeline或者阶段，agent {node {label ‘my-defined-label’}}
docker----使用指定的容器执行pipeline或者阶段，容器在node或者label上，可以包含args参数，直接传递到docker run，已经alwayspull， 该选项强制docker pull
比如：在名字为“my-defined-label“上使用image “maven:3-alpine”来执行pipeline流水线或者阶段

agent {

     docker{
        image 'maven:3-alpine'
        label 'my-defined-label'
        agrs '-v /tmp:/tmp'
     }
}

dockerfile------使用从代码中包含的 Dockerfile 构建的容器来执行pipeline或者阶段

agent {
    // Equivalent to "docker build -f Dockerfile.build --build-arg version=1.0.2 ./build/
    dockerfile {
        filename 'Dockerfile.build'
        dir 'build'
        label 'my-defined-label'
        additionalBuildArgs  '--build-arg version=1.0.2'
    }
}

kubernetes

例子，下面的例子是定义阶段级别的，使用docker来运行阶段

pipeline{
   agent none
   stages{
       stage('build Test'){
              agent {docker 'maven:3-alpine'}
              steps{
                   echo "Build Test"
                   }     
                }
       stage('Example Test'){
              agent {docker 'openjdk:8-jre'}
              steps{
                  echo "Exmaple Test"
                }
             }
         }
}

post

定义一个或多个steps，根据流水线或者阶段的完成情况来执行
post-condition有：always，changed，failure，unstable，aborted，success
always—不管流水线或阶段的完成状态，都会执行这个post
changed—当流水线或者阶段build的状态与之前的build状态不同时，才会执行这个post
failure，unstable，aborted，success----当流水线或者阶段的build状态为这些时，才会执行post
一个简单的post：

pipeline{
    
    agent any
    stages{
        stage("Build Test"){
            steps{
                echo "Hello world"
            }
        }
        
        
    }
    post{
        always{
            echo "always run this post"
        }
    }
    
    
}

build：

stages

包含一个或者多个stage指令

steps

包含一个或者多个步骤

environment

定义环境变量，可以是所有步骤的环境变量也可以是特定阶段的环境变量，取决于environment定义在什么位置
定义在顶层的environment适用于流水线的所有steps，定义在阶段中的environment只适用于该阶段的steps中

pipeline{
    agent any
    environment{
        Test='oneone'
    }
    stages{
        stage("Build Test"){
            environment{
                TestTwo="twotwo"
            }
            steps{
                sh 'printenv'
            }
        }
        stage("Example Test"){
            steps{
                sh 'printenv'
            }
        }
    }    
}

该pipeline定义了两个阶段“Build Test”和“Example Test”，在每个阶段分别打印出env
build之后可以看到全局变量Test在每个stage都打印出来了，而定义在stage“Build Test”的TestTwo只在该stage打印出来

options

流水线的特定配置
以下是定义在pipeline块的参数：
buildDiscarder：为最近的流水线运行的特定数量保存组件和控制台输出。例如: options { buildDiscarder(logRotator(numToKeepStr: ‘1’)) }
disableConcurrentBuilds：不允许同时执行流水线。 可被用来防止同时访问共享资源等。 例如: options { disableConcurrentBuilds() }
overrideIndexTriggers：允许覆盖分支索引触发器的默认处理。 如果分支索引触发器在多分支或组织标签中禁用, options { overrideIndexTriggers(true) } 将只允许它们用于促工作。否则, options { overrideIndexTriggers(false) } 只会禁用改作业的分支索引触发器。
skipDefaultCheckout：在agent 指令中，跳过从源代码控制中检出代码的默认情况。例如: options { skipDefaultCheckout() }
skipStagesAfterUnstable：一旦构建状态变得UNSTABLE，跳过该阶段。例如: options { skipStagesAfterUnstable() }
checkoutToSubdirectory：在工作空间的子目录中自动地执行源代码控制检出。例如: options { checkoutToSubdirectory(‘foo’) }
timeout：设置流水线运行的超时时间, 在此之后，Jenkins将中止流水线。例如: options { timeout(time: 1, unit: ‘HOURS’) }
retry：在失败时, 重新尝试整个流水线的指定次数。 For example: options { retry(3) }
timestamps：预谋所有由流水线生成的控制台输出，与该流水线发出的时间一致。 例如: options { timestamps() }

pipeline{
    agent any
    options{
        timestamps() 
    }
    stages{
        stage("Build Test"){
            steps{
                echo "hell world!"
            }
        }
    }
}

build后能在控制台的输出中看到timestamps

在stage中定义的option可选用的参数只有：skipDefaultCheckout，timeout，retry，timestamps

parameters

构建时用户需要提供的参数
这些参数可以通过params提供给流水线的steps使用
有字符串类型和boolean类型
string：字符串类型，parameters { string(name: ‘DEPLOY_ENV’, defaultValue: ‘staging’, description: ‘’) }
booleanParam：布尔参数，parameters { booleanParam(name: ‘DEBUG_BUILD’, defaultValue: true, description: ‘’) }
text：文本参数，包含多行 parameters { text(name: ‘DEPLOY_TEXT’, defaultValue: ‘One\nTwo\nThree\n’, description: ‘’) }
choice：选择类型的参数，parameters { choice(name: ‘CHOICES’, choices: [‘one’, ‘two’, ‘three’], description: ‘’) }
password：password参数，parameters { password(name: ‘PASSWORD’, defaultValue: ‘SECRET’, description: ‘A secret password’) }

在steps中引用

在steps如果要引用这些参数，需要使用$params.key，比如${params.DEPLOY_ENV}

使用parameters创建参数化的pipeline，并在steps中引用

创建一个pipeline，语法如下

pipeline{
    agent any
    parameters{
        string(name:"deploy_env",defaultValue:"staging",description:"")
    }
    stages{
        stage("Build Test"){
            steps{
                echo "${params.deploy_env}"
            }
        }
    }
}

点击build，完成一次build之后，就会出现“build with parameters”

triggers

triggers指令定义了如何触发流水线
有以下三种触发器：
cron：接收 cron 样式的字符串来定义要重新触发流水线的常规间隔 ,比如: triggers { cron(‘H */4 * * 1-5’) }
pollSCM：接收 cron 样式的字符串来定义一个固定的间隔，在这个间隔中，Jenkins 会检查新的源代码更新。如果存在更改, 流水线就会被重新触发。例如: triggers { pollSCM(‘H */4 * * 1-5’) }
upstream：接受逗号分隔的工作字符串和阈值。 当字符串中的任何作业以最小阈值结束时，流水线被重新触发。例如: triggers { upstream(upstreamProjects: ‘job1,job2’, threshold: hudson.model.Result.SUCCESS) }

练习，在pipeline中定义一个triggers

tools

定义自动安装tool，放在PATH中
工具的名字需要预先配置在Manage Jenkins → Global Tool Configuration.
支持的工具有maven，jdk，gradle

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

input

input指令用于stage中，使用input步骤来提示用户输入
当执行了options之后，再进入agent或者when之前，这个stage会暂停，如果这个input被approved，这个stage才会继续
放在input步骤里的parameters也可以用于余下的stage

配置项

message：给用户的提示信息
id：input的可选标示符，默认是stage的名字
ok：input表单上ok按钮的文本
submitter：允许提交这个input的用户或者group的名字，使用逗号分隔，默认是任何用户
submitterParameter：用来设置submitter的环境变量
parameters：需要submitter提供的变量
创建一个pipeline

pipeline{
    agent any
    stages{
       stage("Build Test"){
           input {
               message "Should we continue?"
               ok "yes,continue"
               parameters{
                   string(name:"person",defaultValue:"test",description:'')
               }
           }
           steps{
               echo "the envrioment is ${person}"
           }
       }
    }
}

build时就会弹出来这个input框

when

when指令：根据给定的条件，决定pipeline是否执行这个该阶段
一个when指令至少包含一个条件，当有多个条件时，所有的子条件必须返回true，这个stage才会运行
branch：当正在构建的分支与模式给定的分支匹配时，执行这个阶段, 例如: when { branch ‘master’ }。注意，这只适用于多分支流水线。
environment：当指定的环境变量是给定的值时，执行这个步骤, 例如: when { environment name: ‘DEPLOY_TO’, value: ‘production’ }
expression：当指定的Groovy表达式评估为true时，执行这个阶段, 例如: when { expression { return params.DEBUG_BUILD } }
not：当嵌套条件是错误时，执行这个阶段,必须包含一个条件，例如: when { not { branch ‘master’ } }
allOf：当所有的嵌套条件都正确时，执行这个阶段,必须包含至少一个条件，例如: when { allOf { branch ‘master’; environment name: ‘DEPLOY_TO’, value: ‘production’ } }
anyOf：当至少有一个嵌套条件为真时，执行这个阶段,必须包含至少一个条件，例如: when { anyOf { branch ‘master’; branch ‘staging’ } }

当when只包含一个条件时

pipeline{
    agent any
    parameters{
        string(name:"deploy_env",defaultValue:"test",description:"")
    }
    stages{
        stage("Build Test"){
         when{
            environment name:"deploy_env",value:"prod"
              }
        steps{
            echo "hello wrold"
        }
            
        }
       
    }
}

build结果，第一次build时，deploy_env的值是test，stage “Build Test”被skipped
第二次build时，参数deploy_env设置为prod，执行stage“Build Test”

当when包含多个条件时

pipeline{
    agent any
    parameters{
        string(name:"deploy_env",defaultValue:"test",description:"")
    }
    stages{
        stage("Build Test"){
            when{
                branch "master"
                environment name:"deploy_env",value:"prod"
            }
            steps{
                echo "Hello world"
            }
        }
    }
}