Jenkins-pipeline语法说明

一. 简述：

   Jenkins Pipeline 是一种持续集成和持续交付（CI/CD）工具，它允许用户通过代码定义构建、测试和部署流程。

二. 关于jenkinsfile：

 1. Sections部分：

   Pipeline里的Sections通常包含一个或多个Directives或 Steps：

a). agent：

      指定整个Pipeline或特定阶段将在Jenkins环境中执行的节点位置，具体取决于该agent 部分的配置。该部分必须在pipeline块内的顶层定义 ，但在stage中是可以使用的。

#agent可选项： 
 1). any:任何可用agent上执行。
 2). none:不会为整个Pipeline运行分配全局agent ，每个stage部分将需要包含其自己的agent部分
  3).  label: 使用提供的label标签，在Jenkins环境中可用的代理上执行Pipeline或stage(agent { label 'my-defined-label' })
  4).  node: agent { node { label 'labelName' } }，等同于 agent { label 'labelName' }，但node允许其他选项
  5). docker：执行Pipeline或stage时会动态供应一个docker节点去接受Docker-based的Pipelines。
  6). dockerfile: 使用从Dockerfile源存储库中包含的容器来构建执行Pipeline或stage 


eg：

pipeline {
    agent none 
    stages {
        stage('Example Build') {
            agent { docker 'maven:3-alpine' } 
            steps {
                echo 'Hello, Maven'
                sh 'mvn --version'
            }
        }
        stage('Example Test') {
            agent { docker 'openjdk:8-jre' } 
            steps {
                echo 'Hello, JDK'
                sh 'java -version'
            }
        }
    }
}
 
常用选项： 
#label ： 标签，适用于node,dockr anddockerfile时，并且node是必须的 
#customWorkspace: 自定workspace路径
#reuseNode：一个布尔值，默认为false。如果为true，则在同一工作空间中，。只适用于docker和dockerfile，并且仅在 individual stage中使用agent才有效
 
eg:
agent {
    node {
        label 'my-defined-label'
        customWorkspace '/some/other/path'
    }
}

b).  POST:

     定义将在Pipeline运行或阶段结束时运行的操作。部分 always，changed，failure，success，unstable，和aborted。这些块允许在Pipeline运行或stage结束时执行，具体取决于Pipeline的状态。

#post 可选项：

#always：无论Pipeline运行的完成状态如何。
#changed：当前Pipeline运行的状态与先前完成的Pipeline的状态不同时。
#failure：当前Pipeline处于“失败”状态时。
#success：当前Pipeline具有“成功”状态时
#unstable：当前Pipeline具有“不稳定”状态，如由测试失败，代码违例等引起。
#aborted：当前Pipeline处于“中止”状态时，通常是由于Pipeline被手动中止。

eg：
pipeline {
    agent any
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
    post { 
        always { 
            echo 'I will always say Hello again!'
        }
    }
}

通常情况下，post定义在pipeline的末端。

c). stages ：包含一个或多个stage的序列，Pipeline的大部分工作在此执行。建议stages至少包含至少一个stage指令，用于连接各个交付过程，如构建，测试和部署等。

d). steps ：

   包含一个或多个在stage块中执行的step序列。

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

2.  Directives(指令) 部分：

a).  environment:

     指定一系列键值对，这些键值对将被定义为所有step或stage-specific step的环境变量，具体取决于environment指令在Pipeline中的位置。该指令支持一种特殊的方法credentials()，可以通过其在Jenkins环境中的标识符来访问预定义的凭据。

pipeline {
    agent any
    environment { 
        CC = 'clang'   # 顶级pipeline中定义的env适用于所有steps
    }
    stages {
        stage('Example') {
            environment {    #只能适用于该过程的steps
                AN_ACCESS_KEY = credentials('my-prefined-secret-text')  #可在jenkins环境中通过其标示访问定义的凭据。
            }
            steps {
                sh 'printenv'
            }
        }
    }
}

b). options ：

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

#可用选项：
buildDiscarder：  pipeline保持构建的最大个数。
disableConcurrentBuilds： 不允许并行执行Pipeline,可用于防止同时访问共享资源等。
skipDefaultCheckout： 默认跳过来自源代码控制的代码。
skipStagesAfterUnstable： 一旦构建状态进入了“Unstable”状态，就跳过此stage。
timeout： 设置Pipeline运行的超时时间。
retry： 失败后，重试整个Pipeline的次数。
timestamps： 预定义由Pipeline生成的所有控制台输出时间。 


eg：
pipeline {
    agent any
    options {
        timeout(time: 1, unit: 'HOURS')  #指定一个小时的全局执行超时，超出后中止运行
    }
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

c). parameters :

     提供用户在触发Pipeline时的参数列表。这些参数值通过该params对象可用于Pipeline步骤。

#string：  字符串类型
#booleanparam： 布尔参数

eg： 
pipeline {
    agent any
    parameters {
        string(name: 'PERSON', defaultValue: 'Mr Jenkins', description: 'Who should I say hello to?')
    }
    stages {
        stage('Example') {
            steps {
                echo "Hello ${params.PERSON}"
            }
        }
    }
}

d). triggers（触发器）：

     定义了Pipeline自动化触发的方式。对于与源代码集成的Pipeline，如GitHub或BitBucket，triggers可能不需要基于webhook的集成也已经存在。目前只有三个个可用的触发器：cron，pollSCM，upstream。

cron：接受一个cron风格的字符串来定义Pipeline触发的常规间隔，例如： triggers { cron('H 4/* 0 0 1-5') }
pollSCM：接受一个cron风格的字符串来定义Jenkins检查SCM源更改的常规间隔。如果存在新的更改，则Pipeline将被重新触发。例如：triggers { pollSCM('H 4/* 0 0 1-5') }
upstream： 接受逗号分隔的一系列作业和一个阈值。当字符串中的任何作业以定义的阈值结束时，管道将被重新触发,跨job。

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

e). tools:

   通过tools可自动安装工具，并放置环境变量到PATH。如果agent none，这将被忽略。

pipeline {
    agent any
    tools {
        //工具名称必须在Jenkins 管理Jenkins → 全局工具配置中预配置。
        maven 'apache-maven-3.0.1'
    }
    stages {
        stage('Example') {
            steps {
                sh 'mvn --version'
            }
        }
    }
}

f). when:

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

更复杂的条件结构可使用嵌套条件建：not，allOf或anyOf。嵌套条件可以嵌套到任意深度。

#内置参数：
branch： 当正在构建的分支与给出的分支模式匹配时执行
environment：当指定的环境变量设置为给定值时执行
expression：当指定的Groovy表达式求值为true时执行
not：当嵌套条件为false时执行。必须包含一个条件
allOf：当所有嵌套条件都为真时执行。必须至少包含一个条件
anyOf：当至少一个嵌套条件为真时执行。必须至少包含一个条件

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

3. Parallel(并行)：

 对耗时长，相互不存在依赖的stage可以使用此方式提升运行效率。除了parallel stage，单个parallel里的多个step也可以使用并行的方式运行。

pipeline {
    agent any
    stages {
        stage('Non-Parallel Stage') {
            steps {
                echo 'This stage will be executed first.'
            }
        }
        stage('Parallel Stage') {
            when {
                branch 'master'
            }
            failFast true
            parallel {
                stage('Branch A') {
                    agent {
                        label "for-branch-a"
                    }
                    steps {
                        echo "On Branch A"
                    }
                }
                stage('Branch B') {
                    agent {
                        label "for-branch-b"
                    }
                    steps {
                        echo "On Branch B"
                    }
                }
            }
        }
    }
}

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

                script {
                    def browsers = ['chrome', 'firefox']
                    for (int i = 0; i < browsers.size(); ++i) {
                        echo "Testing the ${browsers[i]} browser"
                    }
                }
            }
        }
    }
}