预定义构建参数列表
TeamCity 提供了数十个预定义的 构建参数 ,可在构建配置或构建脚本的设置中使用。
所有这些参数(除了 预定义的配置参数 )都是 传递到构建过程。 请注意,根据您的构建类型(例如,参见 构建属性 部分,了解在 Gradle 构建中访问 TeamCity 系统属性的信息),访问这些参数所需要的技术可能会有所不同。
tip
要查看可用参数的列表,请点击 TeamCity UI 中文本字段旁边的
按钮,或者输入
%
。
这些参数是在特定构建的范围内在服务器端生成的 - 例如,构建号。
服务器构建参数通常以系统属性和相应的环境变量的形式可用。
- 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分配给生成的生成号。 参数采用特殊的 构建编号格式。
- teamcity.build.responsibleNode.id
在 multinode setup中,此参数返回其附加的节点。 可以在发送日志记录 REST API 请求到
/app/rest/builds/id:build_id/log
端点时分配给X-TeamCity-Node-Id-Cookie
cookie。- 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的时间戳。
这些 系统属性对于每个构建都是唯一的(例如,包含更改列表的文件路径)。 他们的值是在构建开始之前在代理端计算的,然后传递给构建。
- system.teamcity.build.checkoutDir
用于构建的 签出目录。
- system.teamcity.build.workingDir
开始构建的 工作目录。 这是 TeamCity 构建运行程序预计启动进程的路径。 这是一个针对运行器的特定属性,因此它在每个步骤中都有一个不同的值。
- system.teamcity.build.changedFiles.file
包含构建中更改文件信息的文件的完整路径。 您可以使用此属性在您的自定义测试运行器中 支持风险测试重新排序。
此文件不适用于 历史构建 ,并且如果此特定构建没有任何更改。- system.teamcity.build.properties.file | env.TEAMCITY_BUILD_PROPERTIES_FILE
包含所有构建系统属性的文件(包括路径)的全名,但不包括其
system.
后缀。 当构建过程开始时,将会写入此文件,并使用 Java Properties 文件格式 (例如,特殊字符将通过反斜杠进行转义)。
这些特定于代理的参数在每个构建代理上定义,并根据其环境变化。 除了标准参数(例如,由运行在代理上的 JVM 提供的 teamcity.agent.jvm.os.name
或 teamcity.agent.jvm.os.arch
),代理可以根据其安装的软件进行参数设置。 TeamCity 会自动检测 .NET Framework、Mono 或 Visual Studio 等软件,并添加相应的 系统属性和 环境变量。
如果代理机器上安装了额外的软件,系统管理员可以修改 <Agent Home>/conf/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 相关环境变量。
- DotNetFramework<version>[_x86|_x64]_Path
此参数的值被设置为相应框架运行时版本的路径。
请注意,此参数仅为每个主要版本的最新安装版本定义。 例如,如果您安装了 3.5 、 4.5 和 4.8 的版本,此参数将仅为 3.5 和 4.8 定义。 版本/参数 4.5 将被省略,因为存在 .NET Framework 4 的较新版本。 要明确定义此类版本,请考虑改用DotNetFrameworkTargetingPack<version>_Path
参数。- 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"。- teamcity.dotnet.nunitlauncher<版本>
包含独立 NUnit 测试启动器的目录路径,
NUnitLauncher.exe
。 版本号是指测试将在其下运行的 .NET Framework 的版本。 版本等同于 .NET Framework 的版本。- teamcity.dotnet.nunitlauncher.msbuild.task
包含 MSBuild 任务
dll
的目录的路径,为 MSBuild 和 Visual Studio (sln) 提供 NUnit 任务。- teamcity.agent.ownPort
TeamCity 服务器用于连接到代理的 代理端口。
- teamcity.agent.protocol
代理和服务器之间用于数据传输的 协议。
- teamcity.agent.cpuBenchmark
该代理的 CPU 基准测试 结果。
tip
在使用 MSBuild 脚本中的参数时,请确保将
.
替换为_
。 例如,使用teamcity_dotnet_nunitlauncher_msbuild_task
而不是teamcity.dotnet.nunitlauncher.msbuild.task
。
_x86
和_x64
参数后缀用于指定框架的特定版本。
teamcity.dotnet.nunitlauncher
参数不能被隐藏或禁用。
当构建代理启动时,它会检测已安装的 JDK 和 JRE,然后按照下述 方式定义与 Java 相关的环境变量。 如果一个已启动的代理已经设置了与 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
环境变量指定的路径中,如果已定义。特定操作系统的位置:
WindowsUnixmacOS系统将搜索 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 安装。 为了实现这个,将 teamcity.agent.java.search.path
属性添加到 buildAgent.properties
文件中。
您可以定义一个目录列表:分隔符类型取决于操作系统。
对于每个 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,您可以使用以下路径:
%\env.JDK_1_6%/bin/javac
%\JDK_1_6%\bin\javac
$JDK_1_6/bin/javac
配置参数可以被其他参数引用(仅当在 参数 页面上定义时),但它们不会传递到构建中。
要查看这些服务器参数的完整列表,请打开任何构建的 参数标签页 ,或下载内部 teamcity/properties/build.start.properties.gz 工件。
请参阅以下文章,以了解更多关于依赖参数的信息: 在构建链中使用参数。
这些是附加到构建配置的 VCS 根的设置。
VCS 参数具有以下格式:
vcsroot.<VCS_root_ID>.<VCS_root_parameter_name>
<VCS_root_ID>
— 这是 VCS 根 ID。<VCS_root_parameter_name>
— 这是 VCS 根参数的名称。 这个参数是特定于 VCS 的。 参见如何获取 可用参数列表。
如果构建配置中只有一个 VCS 根,那么可以省掉 <VCS_root_ID>.
部分。
被 VCS 标记为 secure
的参数(例如,密码)对 引用 不可用。
当 TeamCity 在配置了 分支规格 的构建配置中启动构建时,它会给每个构建添加一个分支标签,或逻辑名称。 这个逻辑名称也可以作为配置参数使用:
teamcity.build.branch
为了区分在默认分支和非默认分支上启动的构建,有一个额外的布尔配置参数可以区分这些情况:
teamcity.build.branch.is_default=true|false
对于 Git 和 Mercurial,TeamCity 会在构建开始时提供附带已知 VCS 分支名称的额外参数。 请注意,根据分支配置的规范,这些可能与逻辑分支名称有所不同。 这个 VCS 分支可以通过以下名称的配置参数获得:
teamcity.build.vcs.branch.<VCS_root_ID>
在此, <VCS_root_ID>
是 VCS 根 ID。