JZTXT

七、流水线语法之Sections

发布时间 2023-05-23 21:47:55作者: shigp1

流水线分为声明式和命令式。这里主要介绍声明式语法。

所有有效的声明性管道必须包含在pipeline块内，例如：

pipeline {
    /* insert Declarative Pipeline here */
}

在Declarative Pipeline（声明式）中有效的基本语句和表达式遵循与Groovy语法相同的规则，但有以下例外：

  1. 管道的顶层必须是一个块，特别是：pipeline｛｝。
  2. 没有分号作为语句分隔符。每个语句都必须在自己的行上。
  3. 块只能由Sections, Directives, Steps或赋值语句组成。
  4. 属性引用语句被视为无参数方法调用。因此，例如，input被视为input（）。

Sections

声明性管道中的Sections通常包含一个或多个指令或步骤。

agent

agent指定整个管道或特定阶段将在Jenkins环境中执行的位置，具体取决于代理部分的位置。该节必须在管道块内部的顶层定义，但阶段级别的使用是可选的。

顶级Agents和阶段级Agents之间的差异
顶级Agents：在管道顶层声明的代理中，分配一个代理，然后应用超时选项。超时选项设置的限制中不包括分配代理的时间。

pipeline {
    agent any
    options {
        // Timeout counter starts AFTER agent is allocated
        timeout(time: 1, unit: 'SECONDS')
    }
    stages {
        stage('Example') {
            steps {
                echo 'Hello World'
            }
        }
    }
}

timeout超时时间不包含agent any分配代理的时间。

阶段级 Agents：在阶段内声明的代理中，在分配代理之前和检查任何when条件之前调用选项。在这种情况下，当使用超时时，它会在分配代理之前应用。分配代理的时间包含在超时选项设置的限制中。

pipeline {
    agent none
    stages {
        stage('Example') {
            agent any
            options {
                // Timeout counter starts BEFORE agent is allocated
                timeout(time: 1, unit: 'SECONDS')
            }
            steps {
                echo 'Hello World'
            }
        }
    }
}

timeout包含agent any分配代理的时间。

 
为了支持Pipeline可能拥有的各种各样的用例，代理部分支持几种不同类型的参数。这些参数可以应用于流水线块的顶层，也可以应用于每个阶段指令中:

any

在任何可用的代理上执行管道或阶段。例如：agent any

none

当在管道块的顶层应用时，不会为整个管道运行分配全局代理，并且每个阶段段都需要包含自己的代理段。例如：agent none

label

使用提供的标签在Jenkins环境中可用的代理上执行Pipeline或stage。例如：agent { label 'my-defined-label' }

node

代理｛node｛label‘labelName’｝｝的行为与代理｛labels‘labelName‘｝的相同，但node允许其他选项（如customWorkspace）。

docker

使用给定容器执行管道或阶段，该容器将在预先配置为接受基于Docker的管道的节点上或在与可选定义的标签参数匹配的节点上动态提供。docker还可以选择接受一个args参数，该参数可能包含要直接传递给docker运行调用的参数，以及一个alwaysPull选项，该选项将强制docker pull，即使映像名称已经存在。例如：代理｛docker'maven:3.90-eclipse-temurin-11'｝或

agent {
    docker {
        image 'maven:3.9.0-eclipse-temurin-11'
        label 'my-defined-label'
        args  '-v /tmp:/tmp'
    }
}
dockerfile

使用从源存储库中包含的Dockerfile构建的容器来执行Pipeline或stage。为了使用此选项，Jenkinsfile必须从Multibranch Pipeline或SCM的Pipeline加载。按照惯例，这是源存储库根目录中的Dockerfile：agent｛Dockerfile true｝。如果在另一个目录中构建Dockerfile，请使用dir选项：agent｛Dockerfile｛dir 'someSubDir'｝｝。如果Dockerfile有其他名称，您可以使用filename选项指定文件名。您可以将其他参数传递给docker构建…​ 带有additionalBuildArgs选项的命令，如代理｛dockerfile｛additionalBuildingArgs '--build arg foo=bar'｝｝。例如，具有文件build/Dockerfile.build的存储库，需要构建参数版本：

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'
        args '-v /tmp:/tmp'
    }
}
kubernetes

在部署在Kubernetes集群上的pod中执行Pipeline或stage。

常用选项

label：用于运行管道或单个阶段的标签或标签条件。
customWorkspace：在此自定义工作区中运行此代理应用到的管道或单个阶段，而不是默认的阶段。它可以是相对路径，在这种情况下，自定义工作空间将位于节点上的工作空间根目录下，也可以是绝对路径。例如：

agent {
    node {
        label 'my-defined-label'
        customWorkspace '/some/other/path'
    }
}

这个选项在node, docker, 和 dockerfile才有效。
reuseNode：布尔值，默认为false。如果为true，请在同一工作区中的管道顶层指定的节点上运行容器，而不是完全在新节点上运行。此选项对docker和dockerfile有效，只有在单个阶段的代理上使用时才有效。
args：要传递给docker运行的运行时参数。

post

post定义了在管道或阶段运行完成后运行的一个或多个附加步骤（取决于post在管道内的位置）。post可以支持以下任何post条件块：always, changed, fixed, regression, aborted, failure, success, unstable, unsuccessful, 和 cleanup。这些条件块允许根据管道或阶段的完成状态在每个条件内执行步骤。

always
无论管道或阶段运行的完成状态如何，都要在post中运行步骤。
changed
只有当当前管道的运行与上次运行的完成状态不同时，才在post运行步骤。
fixed
仅当当前管道的运行成功，而上一次运行失败或不稳定时，才在post运行步骤。
regression
只有当当前管道或状态为失败、不稳定或中止，并且上一次运行成功时，才在post运行步骤。
aborted
只有在当前管道的运行处于“中止”状态时（通常是由于手动中止管道），才在post运行步骤。这通常在web UI中用灰色表示。
failure
只有在当前管道或阶段的运行处于“失败”状态（通常在web UI中用红色表示）时，才在post运行步骤。
success
只有当当前管道或阶段的运行状态为“成功”（通常在web UI中用蓝色或绿色表示）时，才在post运行步骤。
unstable
只有当当前管道的运行处于“不稳定”状态时，才在post运行步骤，这通常是由测试失败、代码冲突等引起的。这通常在web UI中用黄色表示。
unsuccessful
只有当当前管道或阶段的运行状态不是“成功”时，才在post运行步骤。这通常在web UI中表示，具体取决于前面提到的状态（对于阶段，如果构建本身不稳定，这可能会触发）。
cleanup
无论管道或阶段的状态如何，在评估完其他每个post条件后，运行此post条件中的步骤。
 
例子

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

总会输出I will always say Hello again!

stages

包含一个或多个阶段指令序列的stages部分是管道所描述的大部分“工作”所在的位置。建议阶段至少为连续交付过程的每个离散部分（如构建、测试和部署）包含一个阶段指令。例如：

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

steps

steps部分定义了要在给定阶段指令中执行的一系列一个或多个步骤。例如：

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