Using Build Parameters
This topic illustrates simple use cases where you might opt for referencing parameters in TeamCity UI instead of specifying plain values. Refer to the Main Use Cases section for the general overview of parameters' usage scenarios.
If you have various configurations that utilize the same image registry, you can create a custom parameter for the <Root> project to store this registry's name. As a result, you can reference this parameter in any Docker step that pulls or pushes your images.
tip
Parameters declared inside the <Root> project are available in all TeamCity build configurations.
![Use a custom parameter in TeamCity Use a custom parameter in TeamCity](https://resources.jetbrains.com/help/img/teamcity/2024.12/dk-params-reuseParameter.png)
The following Gradle step always uses JDK 19 instead of the default version referenced by the JDK_HOME
environment variable. The runner retrieves a path for this required JDK from the corresponding env.
parameter.
steps {
gradle {
name = "Gradle step"
tasks = "build-dist"
jdkHome = "%\env.JDK_19_0_ARM64%"
}
}
In the following sample, the value of the .NET runner's Command line parameters field is specified using a reference to the dotnet.output.type
parameter.
![Additional parameters Additional parameters](https://resources.jetbrains.com/help/img/teamcity/2024.12/dk-params-additionalSettings.png)
object MyBuildConfig : BuildType({
params {
param("dotnet.output.type", "WinExe")
}
steps {
dotnetBuild {
args = "-p:OutputType=%\dotnet.output.type%"
}
}
})
tip
You can achieve the same result even faster by creating the
system.dotnet.output.type
parameter and setting its value toOutputType=WinExe
. TeamCity will write this value to the response (.rsp) file with .NET settings, so you do not need to set the Command line parameters field in TeamCity UI.This approach is based on the mechanism that passes all parameters with the
system.
prefix to a build engine. See this section for more information: Pass Values to Builders' Configuration Files.
When setting artifact paths on the Build Configuration Settings | General Settings | Artifact paths page, you can utilize custom configuration parameters to substitute plain values.
object GoalInBuildScripts : BuildType({
artifactRules = "testfile1.txt => %\default.artifact.path%"
params {
param("default.artifact.name", "/bin/artifacts/build_artifact.tar.gz")
}
})
The Build Configuration Settings | General Settings | Build Number Format field allows you to customize the numbering pattern for builds of this configuration.
A build's default zero-based integer index is stored in the build.counter
parameter. The sample below adds the name of a repository branch to the build number.
object MyBuildConf : BuildType({
buildNumberPattern = "%\build.counter%-%\teamcity.build.branch%"
})
The VCS Labeling build feature allows build configurations to tag repository sources.
![VCS Labeling with Parameters VCS Labeling with Parameters](https://resources.jetbrains.com/help/img/teamcity/2024.12/dk-params-vcs-labeling.png)
The following setup illustrates how to use the values of the release.status
parameter as tags. See also: Parameters Display Mode.
object MyBuildConf : BuildType({
params {
param("release.status", "EAP")
}
features {
vcsLabeling {
vcsRootId = "${DslContext.settingsRoot.id}"
labelingPattern = "%\release.status%"
}
}
})
VCS Checkout Rules can be configured on the Build Configuration Settings | Version Control Settings page. If your organization has a certain convention for branch names, you can store these default names as parameters and specify checkout rules as shown below.
object GoalInBuildScripts : BuildType({
params {
param("branch.ignored", "refs/heads/sandbox")
param("branch.default", "refs/heads/main")
}
vcs {
root(YourVcsRootName, "+:%\branch.default%", "-:%\branch.ignored%")
}
})
Thanks for your feedback!