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.

Store a Docker Registry Name

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.

Specify the JDK Version

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

Set Additional .NET Parameters

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.

object MyBuildConfig : BuildType({
    params {
        param("dotnet.output.type", "WinExe")
    }

    steps {
        dotnetBuild {
            args = "-p:OutputType=%\dotnet.output.type%"
        }
    }
})

Specify Artifact Paths

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

Modify the Build Numbering Pattern

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

Label Builds

The VCS Labeling build feature allows build configurations to tag repository sources.

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

Specify Checkout Rules

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

Last modified: 18 September 2024