预定义构建参数列表
TeamCity 提供了数十个预定义的构建参数,可在构建配置或构建脚本的设置中使用。
除了 预定义的配置参数 ,所有这些参数都被 传递给一个构建过程。 请注意,根据您的构建类型(例如,参见 构建属性 部分,了解在 Gradle 构建中访问 TeamCity 系统属性的信息),访问这些参数所需要的技术可能会有所不同。
预定义的服务器构建参数
这些参数是在特定构建的范围内在服务器端生成的 - 例如,构建号。
服务器构建参数通常以系统属性和相应的环境变量的形式可用。
system.teamcity.version | env.TEAMCITY_VERSION
TeamCity 服务器的版本。 这个属性可以用来判断构建是否在 TeamCity 中运行。
system.teamcity.projectName | env.TEAMCITY_PROJECT_NAME
当前构建所属的项目名称。
system.teamcity.buildConfName | env.TEAMCITY_BUILDCONF_NAME
当前构建所属的构建配置的名称。
system.teamcity.buildType.id
TeamCity 使用 唯一 ID 来引用当前构建所属的构建配置。
system.teamcity.configuration.properties.file
包含所有按字母顺序排列的构建参数的文件的全名(包括路径)。 当构建过程开始时,会编写此文件,并使用 Java 属性文件格式 (例如,特殊字符将以反斜杠转义)。 另请参阅:build.properties.file
system.build.is.personal | env.BUILD_IS_PERSONAL
返回
true
用于 个人构建。 对于常规构建,未定义(不存在)。system.build.number | env.BUILD_NUMBER
由TeamCity分配给生成的生成号。 参数采用特殊的 构建编号格式。
env.BUILD_URL
当前构建的链接。
system.teamcity.build.id
TeamCity 用于引用构建的内部唯一 ID。
system.teamcity.auth.userId
生成的用户名,可用于下载其他构建配置的工件。 仅在构建期间有效。 参见此部分获取更多信息:构建级别的身份验证。
系统团队城市认证密码
生成的密码,可用于下载其他构建配置的工件。 仅在构建期间有效。 参见此部分获取更多信息:构建级别的身份验证。
system.build.vcs.number.<VCS_root_ID> | env.BUILD_VCS_NUMBER_<VCS_root_ID>
包含在指定根的生成中的最新VCS修订。 有关 VCS 根 ID 的更多信息,请参阅以下文章:配置 VCS 根.
如果构建配置只有一个 VCS 根,您可以使用build.vcs.number
参数而不使用根 ID 标识符。
该值是 VCS 特有的。 例如,SVN的修订号和CVS的时间戳。
预定义的 Agent 构建参数
这些 系统属性 对于每一个构建都是唯一的(例如,一个包含变更列表的文件的路径)。 他们的值是在构建开始之前在代理端计算的,然后传递给构建。
system.teamcity.build.checkoutDir
用于构建的签出目录。
system.teamcity.build.workingDir
开始构建的 工作目录。 这是 TeamCity 构建运行程序预计启动进程的路径。 这是一个针对运行器的特定属性,因此它在每个步骤中都有一个不同的值。
system.teamcity.build.tempDir
由 TeamCity 生成的构建临时目录的完整路径。 构建后会清理目录。
system.teamcity.build.changedFiles.file
包含构建中更改文件信息的文件的完整路径。 您可以使用此属性在您的自定义测试运行器中支持风险测试重新排序。
此文件不适用于历史构建,并且如果此特定构建没有任何更改。system.teamcity.build.properties.file | env.TEAMCITY_BUILD_PROPERTIES_FILE
包含所有构建系统属性的文件(包括路径)的全名,但不包括其
system.
后缀。 当构建过程开始时,将会写入此文件,并使用 Java Properties 文件格式 (例如,特殊字符将通过反斜杠进行转义)。
预定义的 Agent 环境参数
这些特定于代理的参数在每个构建代理上定义,并根据其环境变化。 除了标准参数(例如,由运行在代理上的 JVM 提供的 teamcity.agent.jvm.os.name
或 teamcity.agent.jvm.os.arch
),代理可以根据其安装的软件进行参数设置。 TeamCity 会自动检测像 .NET Framework、Mono 或 Visual Studio 这样的软件,并添加相应的 系统属性 和 环境变量。
如果代理机器上安装了额外的软件,系统管理员可以修改 <Agent Home>/conf/buildAgent.properties
文件来覆盖相应参数的值。
代理环境参数可以用来设置构建配置选项,定义 代理需求,和 在构建脚本内部。
要查看给定构建代理的所有现有参数及其当前值,请打开代理详细信息页面并切换到 参数 标签。 请查看此链接以获取更多信息:检查参数值。
teamcity.agent.name
代理的名称,如在
buildAgent.properties
代理配置文件 中所指定。 您可以使用代理名称来指定 代理要求,并限制目标配置可以使用的代理数量。teamcity.agent.work.dir
代理工作目录 的路径。
teamcity.agent.work.dir.freeSpaceMb
代理工作目录 中可用的空闲空间。
teamcity.agent.home.dir
代理主目录 的路径
teamcity.agent.tools.dir
代理上的 Tools 目录的路径。
teamcity.agent.jvm.os.version
操作系统的版本。 报告对应 JVM 属性的值。
teamcity.agent.jvm.user.country
用户所在的国家。 报告对应 JVM 属性的值。
teamcity.agent.jvm.user.home
用户的主目录。 报告对应 JVM 属性的值。
teamcity.agent.jvm.user.timezone
用户的时区。 报告对应 JVM 属性的值。
teamcity.agent.jvm.user.name
用户的帐户名称。 报告对应 JVM 属性的值。
teamcity.agent.jvm.user.language
用户的主要操作系统语言。 报告对应 JVM 属性的值。
teamcity.agent.jvm.user.variant
用于表示用户区域设置的变化的任意值。 报告对应 JVM 属性的值。
teamcity.agent.jvm.file.encoding
默认字符集的名称,默认为 UTF-8。 报告对应 JVM 属性的值。
teamcity.agent.jvm.file.separator
文件分隔符。 报告对应 JVM 属性的值。
teamcity.agent.jvm.path.separator
路径分隔符。 报告对应 JVM 属性的值。
teamcity.agent.jvm.specification
Java 运行时环境(JRE)规范版本。 返回 java.specification.version JVM 属性 的值。
teamcity.agent.jvm.version
Java 虚拟机(JVM)实现版本。 报告对应 JVM 属性的值。
teamcity.agent.jvm.java.home
Java 安装目录。 有关更多信息,请参阅以下部分:Java 相关环境变量。
teamcity.agent.os.arch.bits
代理的操作系统位数。
DotNetCLI
.NET CLI 版本。
DotNetCLI_Path
.NET CLI可执行文件的路径。
DotNetFramework <版本>[_x86 | _X64]
仅当相应版本的 .NET Framework 运行时已安装,才会定义。
DotNetFramework<version>[_x86|_x64]_Path
此参数的值被设置为相应框架运行时版本的路径。
请注意,此参数仅为每个主要版本的最新安装版本定义。 例如,如果您安装了 3.5 、 4.5 和 4.8 的版本,此参数将仅为 3.5 和 4.8 定义。 版本/参数 4.5 将被省略,因为存在 .NET Framework 4 的较新版本。 要明确定义此类版本,请考虑改用DotNetFrameworkTargetingPack<version>_Path
参数。DotNetFrameworkSDK<version>[_x86|_x64]
定义是否已安装对应版本的 .NET Framework SDK 。
DotNetFrameworkSDK<version>[_x86|_x64]_Path
对应框架 SDK 版本的路径。
DotNetFrameworkTargetingPack<version>_Path
对应的参考程序集(又名目标包)位置的路径。
DotNetCoreSDKx.x_Path
.NET SDK 版本。
DotNetWorkloads_<版本>
列出代理机器上安装的所有 .NET 工作负载。
末尾的<version>
是已安装的 .NET SDK 的版本。 例如,如果安装了版本 7.0.300,代理将报告 `DotNetWorkloads_7.0.300` 参数。
除了这些完整的 SDK 版本,代理还会报告带有缩短的major.minor
后缀的工作负载参数。 例如,如果代理机器已安装了 7.0.100、7.0.200 和 7.0.300 的 .NET SDK,那么将报告引用最高版本 7.0.300 的DotNetWorkloads_7.0
参数。
参数值是由逗号分隔的工作负载名称字符串,根据 <dotnet_dir>/metadata/workloads/<sdk_version>/InstalledWorkloads目录中的文件夹。 例如,"android,maui-ios,wasm-tools"。WindowsSDK<version>
只有在安装了相应的 Windows SDK 版本后才会定义。
WindowsSDK<version>_Path
对应版本的 Windows SDK 的路径。
VS<Version>
定义是否已安装对应的 Visual Studio 版本
VS<Version>_Path
指向 Visual Studio 安装文件夹的路径(包含 devenv.exe 的目录)。
teamcity.dotnet.nunitlauncher<版本>
包含独立 NUnit 测试启动器的目录路径,
NUnitLauncher.exe
。 版本号是指测试将在其下运行的 .NET Framework 的版本。 版本等同于 .NET Framework 的版本。teamcity.dotnet.nunitlauncher.msbuild.task
包含 MSBuild 任务
dll
的目录的路径,为 MSBuild 和 Visual Studio (sln) 提供 NUnit 任务。teamcity.dotnet.msbuild.extensions2.0
包含 MSBuild 2.0 监听器和任务组件的目录的路径。
teamcity.dotnet.msbuild.extensions4.0
包含 MSBuild 4.0 监听器和任务程序集的目录路径。
teamcity.agent.ownPort
TeamCity 服务器用于连接到代理的 代理端口。
teamcity.agent.protocol
代理和服务器之间用于数据传输的 协议。
teamcity.agent.cpuBenchmark
该代理的 CPU 基准测试 结果。
teamcity.agent.hardware.cpuCount
代理机器 CPU 上的核心 / 线程数量。
teamcity.agent.hostname
构建代理主机的名称。
与 Java 相关的环境变量
当构建代理启动时,它会检测已安装的 JDK 和 JRE,然后按照下述方式定义与 Java 相关的环境变量。 如果一个已启动的代理已经设置了与 Java 相关的环境变量,那么它们将不会被重新定义。
这些变量可以像通常的 环境变量 一样在构建脚本中使用。
在 Agent 上检测 Java
代理程序会搜索并启动所有 Java 安装,以验证它们是否有效。 它根据输出确定 Java 版本和位数。
以下位置将被搜索(其中一些位置对所有操作系统通用,一些是特定操作系统专有的):
如果已定义,代理上的自定义目录。 参见 如何定义自定义目录。
代理工具目录,
<Agent Home Directory>/tools
,已检查是否包含 JRE 或 JDK。 默认情况下,/tools
的子目录不会被扫描。 要搜索子目录,请在buildAgent.properties
文件中定义teamcity.agent.java.search.path=%agent.tools.NAME%/INNER_PATH
。
对于 Unix 和 macOS,记住在文件上 设置可执行位,以便 TeamCity 能够启动发现的 Java。在由
JAVA_HOME
、JDK_HOME
、JRE_HOME
环境变量指定的路径中,如果已定义。特定操作系统的位置:
系统将搜索 Windows 注册表,以查找使用 Java 安装程序安装的 Java。
C:\Program Files
和C:\Program Files (x86)
目录会被搜索,寻找Java
和JavaSoft
子目录。C:\Java
/usr/local/java
/usr/local
/usr/java
/usr/lib/jvm
/usr
/System/Library/Frameworks/JavaVM.framework/Versions/<Java Version>/Home
/Library/Java/JavaVirtualMachines/Versions/<Java 版本>/Home
/Library/Java/JavaVirtualMachines/<Java 版本>/Contents/Home
在由
PATH
环境变量指定的路径中,如果已定义。
定义用于搜索 Java 的自定义目录
您可以在代理上定义一个自定义目录来搜索 Java 安装。 为了实现这个,将 teamcity.agent.java.search.path
属性添加到 buildAgent.properties
文件中。
您可以定义一个目录列表:分隔符类型取决于操作系统。
定义 Java 相关环境变量
对于每个 Java 版本,都定义了以下变量: JDK_<major>_<minor>[_x64]
。 例如, env.JDK_1_6
(Java 6)或 env.JDK_14_0_x64
(Java 14 64 位)。
当找到 JDK 时, JDK
变量将被定义。 在 Java 11 之前,当找到 JRE 但没有找到 JDK 时, JRE
变量就被定义了。
_x64
变量只指向 64 位的 Java。 没有 _x64
后缀的变量可能指向 32 位或 64 位安装程序,但优先选择 32 位程序。
如果发现有多个安装程序拥有相同的主版本和位数,但次版本/更新不同,则选择最新的一个。
另外,定义了以下变量:
JAVA_HOME
— 用于最新的 JDK 安装(但更推荐 32 位的)。JDK_HOME
— 与JAVA_HOME
相同。JRE_HOME
— 适用于最新的 JRE 或 JDK 安装(但优先选择 32 位版本),即使发现了 JDK 也需要定义。
JRE_HOME
和 JDK_HOME
变量可能指向不同的安装。 例如,如果已安装 JRE 1.7 和 JDK 1.6,但没有安装 JDK 1.7 —— JRE_HOME
将指向 JRE 1.7,而 JDK_HOME
将指向 JDK 1.6。
所有变量都指向 Java Home 目录,而不是二进制文件。 例如,如果您想要执行 javac 版本 1.6,您可以使用以下路径:
预定义的配置参数
配置参数可以被其他参数引用(只有在 参数 页面中定义后才能使用),但它们不会传递给构建。
要查看这些服务器参数的完整列表,请打开任何构建的 参数标签页,或下载内部 teamcity/properties/build.start.properties.gz 工件。
依赖性参数
请参阅以下文章,以了解更多关于依赖参数的信息:在构建链中使用参数。
VCS 参数
这些是附加到构建配置的 VCS 根的设置。
VCS 参数具有以下格式:
<VCS_root_ID>
— 这是 VCS 根 ID。<VCS_root_parameter_name>
— 这是 VCS 根参数的名称。 这个参数是特定于 VCS 的。 参见如何获取 可用参数列表。
如果构建配置中只有一个 VCS 根,那么可以省掉 <VCS_root_ID>.
部分。
被 VCS 标记为 secure
的参数(例如,密码)对 引用 不可用。
构建分支参数
当 TeamCity 在配置了 分支规格 的构建配置中启动构建时,它会给每个构建添加一个分支标签,或逻辑名称。 这个逻辑名称也可以作为配置参数使用:
为了区分在默认分支和非默认分支上启动的构建,有一个额外的布尔配置参数可以区分这些情况:
对于 Git 和 Mercurial,TeamCity 会在构建开始时提供附带已知 VCS 分支名称的额外参数。 请注意,根据分支配置的规范,这些可能与逻辑分支名称有所不同。 这个 VCS 分支可以通过以下名称的配置参数获得:
在此, <VCS_root_ID>
是 VCS 根 ID。
其他参数
teamcity.build.triggeredBy
返回构建触发方式的人性化描述。
teamcity.build.triggeredBy.username
如果构建是由用户触发的,系统将报告这个用户的用户名。 当构建不是由用户触发时,将不会报告此属性。