Jenkins 内置全局变量

归-尘

5289人浏览 · 2022-09-09 14:31:56

归-尘 · 2022-09-09 14:31:56 发布

Overview
Global Variable Reference

Overview

全局变量直接在 Pipeline 中可用，而不是作为步骤。它们公开了要在 Pipeline 脚本中访问的方法和变量。

Global Variable Reference

pipeline

该 pipeline 步骤允许您以更结构化的方式定义您的管道。有关更多信息，请参阅 wiki。

env

环境变量可以从 Groovy 代码中作为 env.VARNAME 或简称为 VARNAME 进行访问。您也可以写入此类属性（仅使用 env. 前缀）

在 pipeline 中使用 ${env.BRANCH_NAME}，在 shell 中使用 $BRANCH_NAME

env.MYTOOL_VERSION = '1.33'
node {
  sh '/usr/local/mytool-$MYTOOL_VERSION/bin/start'
}

这些定义也将在构建期间或完成后通过 REST API 以及使用该 build 步骤从上游管道构建中获得。

但是，以这种方式设置的任何变量对于 Pipeline 构建都是全局的。对于具有节点特定内容的变量（例如：文件路径），您应该改用该 withEnv 步骤，将变量仅绑定在一个 node 块内。

一组环境变量可供所有 Jenkins 项目使用，包括流水线。以下是可用变量名称的一般列表：

变量名	作用
BRANCH_NAME	对于多分支项目，这将设置为正在构建的分支的名称，例如，如果您希望从主分支而不是从功能分支部署到生产；如果对应于某种更改请求，则名称通常是任意的（参考 `CHANGE_ID` 和 `CHANGE_TARGET`）
BRANCH_IS_PRIMARY	对于多分支项目，如果 SCM 源报告正在构建的分支是主分支，则将其设置为 “true”; 否则未设置。一些 SCM 来源可能将多个分支报告为主要分支，而其他来源可能不提供此信息
CHANGE_ID	对于与某种变更请求对应的多分支项目，如果支持，这将设置为变更 ID，例如：拉取请求编号；否则未设置
CHANGE_URL	对于对应于某种变更请求的多分支项目，如果支持，将设置为变更 URL；否则未设置
CHANGE_TITLE	对于与某种变更请求对应的多分支项目，如果支持，这将设置为变更的标题；否则未设置
CHANGE_AUTHOR	对于与某种变更请求对应的多分支项目，如果支持，这将设置为提议变更作者的用户名；否则未设置
CHANGE_AUTHOR_DISPLAY_NAME	对于与某种变更请求对应的多分支项目，如果支持，这将设置为作者的人名；否则未设置
CHANGE_AUTHOR_EMAIL	对于与某种变更请求对应的多分支项目，如果支持，这将设置为作者的电子邮件地址；否则未设置
CHANGE_TARGET	对于与某种变更请求对应的多分支项目，如果支持，这将设置为可以合并变更的目标或基础分支；否则未设置
CHANGE_BRANCH	对于与某种变更请求相对应的多分支项目，这将设置为源代码控制系统上实际负责人的名称，该名称可能与 `BRANCH_NAME`。例如：在 GitHub 或 Bitbucket 中，这将具有原始分支的名称，而 `BRANCH_NAME` 类似于 `PR-24`
CHANGE_FORK	对于与某种变更请求对应的多分支项目，如果更改源自一个，则将其设置为分叉 repo 的名称；否则未设置
TAG_NAME	对于与某种标签对应的多分支项目，如果支持，这将设置为正在构建的标签的名称；否则未设置
TAG_TIMESTAMP	对于与某种标签对应的多分支项目，如果支持，这将设置为标签的时间戳，以 Unix 纪元以来的毫秒数为单位；否则未设置
TAG_UNIXTIME	对于与某种标签对应的多分支项目，如果支持，这将设置为标签的时间戳，以 Unix 纪元以来的秒数为单位；否则未设置
TAG_DATE	对于与某种标签对应的多分支项目，如果支持，这将设置为 java.util.Date#toString() 定义的格式的时间戳（例如：2020 年 1 月 1 日星期三 00:00:00 UTC）；否则未设置
JOB_DISPLAY_URL	将重定向到首选用户界面中的作业的 URL
RUN_DISPLAY_URL	将重定向到首选用户界面中的构建的 URL
RUN_ARTIFACTS_DISPLAY_URL	将重定向到首选用户界面中构建的工件的 URL
RUN_CHANGES_DISPLAY_URL	将重定向到首选用户界面中构建的变更日志的 URL
RUN_TESTS_DISPLAY_URL	将重定向到首选用户界面中构建的测试结果的 URL
CI	静态设置为字符串 “true”，表示 “持续集成” 执行环境
BUILD_NUMBER	当前内部版本号，例如：“153”。
BUILD_ID	当前构建 ID，与 1.597+ 中创建的构建的 `BUILD_NUMBER` 相同，但旧版本的时间戳为 `YYYY-MM-DD_hh-mm-ss`
BUILD_DISPLAY_NAME	当前构建的显示名称，默认类似于 “#153”
JOB_NAME	此构建的项目名称，例如：“foo” 或 “foo/bar”
JOB_BASE_NAME	此构建的项目的短名称剥离文件夹路径，例如：“bar/foo” 的 “foo”
BUILD_TAG	`jenkins-${JOB_NAME}-${BUILD_NUMBER}` 的字符串。`JOB_NAME` 中的所有正斜杠 (“/”) 都替换为破折号 (“-”)。方便放入资源文件、jar 文件等，便于识别
EXECUTOR_NUMBER	标识正在执行此构建的当前执行程序（在同一台机器的执行程序中）的唯一编号。这是你在 “构建执行器状态” 中看到的数字，只是数字是从 0 开始的，而不是 1
NODE_NAME	如果构建在代理上，则代理的名称，如果在内置节点上运行，则为 `built-in`（或在 Jenkins 2.306 之前为 `master`）
NODE_LABELS	分配给节点的标签的空格分隔列表
WORKSPACE	作为工作空间分配给构建的目录的绝对路径
WORKSPACE_TMP	工作区附近的临时目录，不可浏览且不会干扰 SCM 签出。最初可能不存在，因此请务必根据需要创建目录（例如：在 Linux 上 `mkdir -p`）。当常规工作区是驱动器根时未定义
JENKINS_HOME	控制器文件系统上分配给 Jenkins 存储数据的目录的绝对路径
JENKINS_URL	Jenkins 的完整 URL，例如：`http://server:port/jenkins/`（注意：仅在系统配置中设置 Jenkins URL 时可用）
BUILD_URL	此构建的完整 URL，例如：`http://server:port/jenkins/job/foo/15/`（必须设置 Jenkins URL）
JOB_URL	此作业的完整 URL，例如：`http://server:port/jenkins/job/foo/`（必须设置 Jenkins URL）

特定于 SCM 的变量，例如：GIT_COMMIT 不会自动定义为环境变量；相反，您可以使用 checkout 步骤的返回值。

作为从 Groovy 加载变量值的示例：

mail to: 'devops@acme.com',
    subject: "Job '${JOB_NAME}' (${BUILD_NUMBER}) is waiting for input",
    body: "Please go to ${BUILD_URL} and verify the build"

params

在 pipeline 中使用 ${params.NAME}，在 shell 中使用 $NAME

将构建中定义的所有参数公开为具有各种类型值的只读映射。例子：

if (params.BOOLEAN_PARAM_NAME) { doSomething() }

或提供一个重要的默认值：

if (params.getOrDefault('BOOLEAN_PARAM_NAME', true)) { doSomething() }

多分支（Jenkinsfile）使用注意事项：该 properties 步骤允许您定义作业属性，但这些属性在步骤运行时生效，而构建参数定义通常在构建开始之前进行咨询。为方便起见，当前在作业中定义的任何具有默认值的参数也将在此映射中列出。这允许您编写，例如：

properties([parameters([string(name: 'BRANCH', defaultValue: 'master')])])
git url: '…', branch: params.BRANCH

并确保 master 即使在分支项目的初始构建中，或者如果先前的构建没有指定参数或使用不同的参数名称，分支也会被签出。

currentBuild

currentBuild 变量属于 RunWrapper 类型，可用于引用当前正在运行的生成。它具有以下可读属性：

currentBuild 变量属性	作用
getBuildCauses	返回当前构建的构建原因的 JSON 数组
getBuildCauses(String causeClass)	实验性-可能改变，获取表示完全限定 Cause 类的字符串，并返回按该类型为当前构建筛选的构建原因的 JSON 数组，如果指定类型的原因不适用于当前构建，则返回空 JSON 数组
number	内部版本号（整数）
result	通常是 SUCCESS，UNSTABLE，或 FAILURE（对于正在进行的构建可能为空）
currentResult	通常是 SUCCESS，UNSTABLE 或 FAILURE，永远不会为空
resultIsBetterOrEqualTo(String)	将当前生成结果与提供的结果字符串（SUCCESS，UNSTABLE 或 FAILURE）进行比较，如果当前构建结果优于或等于提供的结果，则返回 true
resultIsWorseOrEqualTo(String)	将当前生成结果与提供的结果字符串（SUCCESS，UNSTABLE 或 FAILURE）进行比较，如果当前构建结果差于或等于提供的结果，则返回 true
displayName	通常是 #123 但有时设置为例如：SCM 提交标识符
fullDisplayName	通常是 folder1 » folder2 » foo #123
projectName	本次构建的项目名称，如：foo
fullProjectName	本次构建的项目全名，包括文件夹，例如：folder1/folder2/foo
description	有关构建的其他信息
id	通常是 number 作为字符串
timeInMillis	自计划构建时起的时间
startTimeInMillis	自构建开始运行以来的时间
duration	构建持续时间（以毫秒为单位）
durationString	构建持续时间的可读表示
previousBuild	项目的先前版本，或 null
previousBuildInProgress	当前正在构建的项目的先前构建，或 null
previousBuiltBuild	已构建的项目的先前构建（可能当前正在构建），或 null
previousCompletedBuild	上次完成构建的项目的先前构建，或 null
previousFailedBuild	上次构建失败的项目的先前构建，或 null
previousNotFailedBuild	没有失败的项目的先前构建（例如：结果是 successful（成功的）或 unstable（不稳定的）），或 null
previousSuccessfulBuild	已成功构建的项目的先前构建，或 null
nextBuild	项目的下一个版本，或 null
absoluteUrl	构建索引页面的 URL
buildVariables	对于非管道下游构建，提供对已定义构建变量映射的访问；对于 Pipeline 下游构建，在构建结束时在 `env` 上全局设置的任何变量。子管道作业可以通过在 `env` 中设置变量向父作业报告其他信息。请注意，`buildVariables` 中没有显示构建参数
changeSets	来自不同 SCM 检出的变更集列表；每个都有一种类型，并且是一个提交列表；每个提交都有一个 `commitId`、`timestamp`、`msg`、`author` 和 `affectedFiles`，每个提交都有一个 `editType` 和路径；该值通常不可序列化，因此您只能在标记 @NonCPS 的方法内访问它
upstreamBuilds	上游构建列表。这些是上游项目的构建，其工件将反馈到此构建中
rawBuild	ahudson.model.Run 带有更多 API，仅适用于受信任的库或沙盒外管理员批准的脚本；该值将不可序列化，因此您只能在标记 @NonCPS 的方法内访问它
keepLog	如果应保留而不是删除此生成的日志文件，则为 true