Jenkins的一些记录

设置环境变量

在 Jenkins 流水线中，取决于使用的是声明式还是脚本式流水线，设置环境变量的方法不同。

声明式流水线支持 environment 指令，而脚本式流水线的使用者必须使用 withEnv 步骤。

shell 复制代码

pipeline {
    agent any
    environment { 
        CC = 'clang'
    }
    stages {
        stage('Example') {
            environment { 
                DEBUG_FLAGS = '-g'
            }
            steps {
                sh 'printenv'
            }
        }
    }
}

用在最高层的 pipeline 块的 environment 指令适用于流水线的所有步骤。

定义在 stage 中的 environment 指令只适用于 stage 中的步骤。

凭据部分

凭据使用

shell 复制代码

node {
  withCredentials([string(credentialsId: 'mytoken', variable: 'TOKEN')]) {
    sh /* 错误！ */ """
      set +x
      curl -H 'Token: $TOKEN' https://some.api/
    """
    sh /* 正确 */ '''
      set +x
      curl -H 'Token: $TOKEN' https://some.api/
    '''
  }
}

处理参数

（构建化参数的作用）

声明式流水线支持参数开箱即用，允许流水线在运行时通过parameters 指令接受用户指定的参数。配置脚本式流水线的参数是通过 properties 步骤实现的，可以在代码生成器中找到。

如果你使用 Build with Parameters 选项将流水线配置为接受参数，这些参数将作为 params 变量的成员被访问。

假设在 Jenkinsfile 中配置了名为 "Greeting" 的字符串参数，它可以通过 ${params.Greeting} 访问该参数：
string

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

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

还有更多其它类型

groovy 复制代码

pipeline {
    agent any
    parameters {
        // build with parameter时候也可以用界面输入
        string(name: 'Greeting', defaultValue: 'Hello', description: 'How should I greet the world?')
    }
    stages {
        stage('Example') {
            steps {
                echo "${params.Greeting} World!"
            }
        }
    }
}

可选的步骤参数

流水线遵循 Groovy 语言允许在方法周围省略括号的惯例。

许多流水线步骤也使用命名参数语法作为在 Groovy 中创建的 Map（使用语法 [key1: value1, key2: value2] ）的简写。下面的语句有着相同的功能：

groovy 复制代码

git url: 'git://example.com/amazing-project.git', branch: 'master'
git([url: 'git://example.com/amazing-project.git', branch: 'master'])

为了方便，当调用只有一个参数的步骤时（或仅一个强制参数），参数名称可以省略，例如：

groovy 复制代码

sh 'echo hello' /* short form  */
sh([script: 'echo hello'])  /* long form */

多个代理

在之前所有的示例中都只使用了一个代理。这意味着 Jenkins 会分配一个可用的执行者而无论该执行者是如何打标签或配置的。流水线不仅可以覆盖这种行为，还允许在 Jenkins 环境中使用 同一个 Jenkinsfile 中的多个代理，这将有助于更高级的用例，例如跨多个平台的执行构建/测试。

在下面的示例中，"Build" 阶段将会在一个代理中执行，并且构建结果将会在后续的 "Test" 阶段被两个分别标记为 "linux" 和 "windows" 的代理重用。

groovy 复制代码

Jenkinsfile (Declarative Pipeline)
pipeline {
    agent none
    stages {
        stage('Build') {
            agent any
            steps {
                checkout scm
                sh 'make'
                stash includes: '**/target/*.jar', name: 'app' 
            }
        }
        stage('Test on Linux') {
            agent { 
                label 'linux'
            }
            steps {
                unstash 'app' 
                sh 'make check'
            }
            post {
                always {
                    junit '**/target/*.xml'
                }
            }
        }
        stage('Test on Windows') {
            agent {
                label 'windows'
            }
            steps {
                unstash 'app'
                bat 'make check' 
            }
            post {
                always {
                    junit '**/target/*.xml'
                }
            }
        }
    }
}

stash 步骤允许捕获与包含模式（\*/target/.jar）匹配的文件，以便在_同一个_流水线中重用。一旦流水线执行完成，就会从 Jenkins master 中删除暂存文件。
agent/node 中的参数允许使用任何可用的 Jenkins 标签表达式。参考流水线语法
部分了解更多信息。
unstash 将会从 Jenkins master 中取回命名的 "stash" 到流水线的当前工作区中。
bat 脚本允许在基于 Windows 的平台上执行批处理脚本。

高级脚本式流水线

脚本式流水线是一种基于 Groovy 的领域特定语言 [3] ，大多数 Groovy 语法都可以无需修改，直接在脚本式流水线中使用。

并行执行

上面这节中的示例跨两个不同的平台串联地运行测试。在实践中，如果执行 make check 需要30分钟来完成，那么 "Test" 阶段就需要 60 分钟来完成！

幸运的是，流水线有一个内置的并行执行部分脚本式流水线的功能，通过贴切的名为 parallel 的步骤实现。

使用 parallel 步骤重构上面的示例：

groovy 复制代码

Jenkinsfile (Scripted Pipeline)
stage('Build') {
    /* .. snip .. */
}

stage('Test') {
    parallel linux: {
        node('linux') {
            checkout scm
            try {
                unstash 'app'
                sh 'make check'
            }
            finally {
                junit '**/target/*.xml'
            }
        }
    },
    windows: {
        node('windows') {
            /* .. snip .. */
        }
    }
}

测试不再在标记为 "linux" 和 "windows" 节点中串联地执行，而是并行执行。

在流水线中使用Docker

设计流水线的目的是更方便地使用 Docker镜像作为单个 Stage或整个流水线的执行环境。这意味着用户可以定义流水线需要的工具，而无需手动配置代理。实际上，只需对 Jenkinsfile进行少量编辑，任何 packaged in a Docker container的工具，都可轻松使用。
Jenkinsfile (Declarative Pipeline)

groovy 复制代码

pipeline {
    agent {
        docker { image 'node:7-alpine' }
    }
    stages {
        stage('Test') {
            steps {
                sh 'node --version'
            }
        }
    }
}

使用多个容器

代码库依赖于多种不同的技术变得越来越容易。比如, 一个仓库既有基于Java的后端API 实现 and 有基于JavaScript的前端实现。 Docker和流水线的结合允许 Jenkinsfile 通过将 agent {} 指令和不同的阶段结合使用 multiple 技术类型。
Jenkinsfile (Declarative Pipeline)

groovy 复制代码

pipeline {
    agent none
    stages {
        stage('Back-end') {
            agent {
                docker { image 'maven:3-alpine' }
            }
            steps {
                sh 'mvn --version'
            }
        }
        stage('Front-end') {
            agent {
                docker { image 'node:7-alpine' }
            }
            steps {
                sh 'node --version'
            }
        }
    }
}

使用Dockerfile

对于更需要自定义执行环境的项目, 流水线还支持从源仓库的Dockerfile 中构建和运行容器。与使用"现成" 容器的 previous approach 不同的是 , 使用 agent { dockerfile true } 语法从 Dockerfile 中构建一个新的镜像而不是从 Docker Hub中拉取一个。

重复使用上面的示例, 使用一个更加自定义的 Dockerfile:
Dockerfile

FROM node:7-alpine

RUN apk add -U subversion

通过提交它到源仓库的根目录下, 可以更改 Jenkinsfile 文件，来构建一个基于该 Dockerfile 文件的容器然后使用该容器运行已定义的步骤:
Jenkinsfile (Declarative Pipeline)

groovy 复制代码

pipeline {
    agent { dockerfile true }
    stages {
        stage('Test') {
            steps {
                sh 'node --version'
                sh 'svn --version'
            }
        }
    }
}

agent { dockerfile true } 语法支持大量的其它选项，这些选项的更详细的描述请参考流水线语法部分。

environment

environment 指令制定一个键-值对序列，该序列将被定义为所有步骤的环境变量，或者是特定于阶段的步骤，这取决于 environment 指令在流水线内的位置。

该指令支持一个特殊的助手方法 credentials() ，该方法可用于在Jenkins环境中通过标识符访问预定义的凭证。对于类型为 "Secret Text"的凭证, credentials() 将确保指定的环境变量包含秘密文本内容。对于类型为 "SStandard username and password"的凭证, 指定的环境变量指定为 username:password ，并且两个额外的环境变量将被自动定义 :分别为 MYVARNAME_USR 和 MYVARNAME_PSW 。

示例
Jenkinsfile (Declarative Pipeline)

groovy 复制代码

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

	顶层流水线块中使用的 environment 指令将适用于流水线中的所有步骤。
	在一个 stage 中定义的 environment 指令只会将给定的环境变量应用于 stage 中的步骤。
	environment 块有一个助手方法 credentials() 定义，该方法可以在 Jenkins 环境中用于通过标识符访问预定义的凭证。

触发器

triggers 指令定义了流水线被重新触发的自动化方法。对于集成了源（比如 GitHub 或 BitBucket）的流水线, 可能不需要 triggers ，因为基于 web 的集成很肯能已经存在。当前可用的触发器是 cron, pollSCM 和 upstream。

Required	No
Parameters	None
Allowed	Only once, inside the pipeline block.

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) }

	pollSCM 只在Jenkins 2.22 及以上版本中可用。

示例
Jenkinsfile (Declarative Pipeline)

groovy 复制代码

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

when

when 指令允许流水线根据给定的条件决定是否应该执行阶段。 when 指令必须包含至少一个条件。如果 when 指令包含多个条件, 所有的子条件必须返回True，阶段才能执行。这与子条件在 allOf 条件下嵌套的情况相同 (参见下面的示例)。

使用诸如 not, allOf, 或 anyOf 的嵌套条件可以构建更复杂的条件结构 can be built 嵌套条件可以嵌套到任意深度。

Required	No
Parameters	None
Allowed	Inside a stage directive

内置条件
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' } }

在进入 stage 的 agent 前评估 when

默认情况下, 如果定义了某个阶段的代理，在进入该stage 的 agent 后该 stage 的 when 条件将会被评估。但是, 可以通过在 when 块中指定 beforeAgent 选项来更改此选项。如果 beforeAgent 被设置为 true, 那么就会首先对 when 条件进行评估 , 并且只有在 when 条件验证为真时才会进入 agent 。

示例
Jenkinsfile (Declarative Pipeline)

groovy 复制代码

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

并行

声明式流水线的阶段可以在他们内部声明多隔嵌套阶段, 它们将并行执行。注意，一个阶段必须只有一个 steps 或 parallel 的阶段。嵌套阶段本身不能包含进一步的 parallel 阶段, 但是其他的阶段的行为与任何其他 stage 相同。任何包含 parallel 的阶段不能包含 agent 或 tools 阶段, 因为他们没有相关 steps。

另外, 通过添加 failFast true 到包含 parallel的 stage 中，当其中一个进程失败时，你可以强制所有的 parallel 阶段都被终止。

示例

groovy 复制代码

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"
                    }
                }
            }
        }
    }
}