Changing an Environment Variable During a TeamCity Build

TeamCity build steps cannot directly change the in-memory environment of another step. To pass a newly computed value to later steps, emit a setParameter TeamCity Service Message to standard output. For example: echo ##teamcity[setParameter name='env.MY_VAR' value='new-value'].

TeamCity reads the message and updates the parameter for the remainder of the current build. If the parameter uses the env. prefix, the updated value is injected as an environment variable into subsequent build steps.

Important Note

A build step that sets the parameter value via a TeamCity service message continues to use the old value. The new value is available beginning with the next build step.

How to use setParameter

1. 1. (Optional) Declare the environment variable as a build parameter with the env. prefix. This is optional, but it makes the intent explicit and provides an initial value.
2. 2. In a build step, print a service message in this format:

    ##teamcity[setParameter name='env.MY_VAR' value='new-value']
   

3. 3. Read the updated value in later steps using either %env.MY_VAR% as a TeamCity parameter reference or the corresponding environment variable ($MY_VAR on Unix-like systems, %MY_VAR% on Windows).

Kotlin DSL example

The following configuration starts with MY_VAR=initial, computes a new value, and makes it available to the second step:

import jetbrains.buildServer.configs.kotlin.*
import jetbrains.buildServer.configs.kotlin.buildSteps.script

version = "2024.12"

object MyBuild : BuildType({
    name = "DSL env var mid-build"

    params {
        // Initial value; this is available as MY_VAR on the build agent.
        param("env.MY_VAR", "initial")
    }

    steps {
        script {
            name = "Step 1 - compute and set"
            scriptContent = """
                echo "Before: MY_VAR=${'$'}MY_VAR"         # prints 'initial'
                NEW_VALUE="computed-${'$'}(date +%s)"

                # Make the value available to all following steps.
                echo "##teamcity[setParameter name='env.MY_VAR' value='${'$'}NEW_VALUE']"
            """.trimIndent()
        }

        script {
            name = "Step 2 - use the new value"
            scriptContent = """
                echo "After: MY_VAR=${'$'}MY_VAR"           # prints the computed value
            """.trimIndent()
        }
    }
})

In this example:

• Step 1 sees the initial value.
• Step 1 computes and publishes a new value.
• Step 2 receives the computed value as MY_VAR.

Kotlin string escaping

${'$'} is Kotlin's escape for a literal dollar sign inside a triple-quoted string. It ensures that the shell, rather than Kotlin, expands $MY_VAR and $NEW_VALUE when the script runs.

For Windows runners, use the appropriate batch or PowerShell syntax and reference environment variables with %MY_VAR% where applicable.

Important considerations

The current step does not receive the new value

setParameter affects later steps only. If the step needs to use the computed value immediately, store it in a normal shell variable and use that variable in the current step. Emit setParameter as well if later steps need the value.

Escape service-message values when necessary

TeamCity service messages use special characters for escaping. If a value can contain characters such as apostrophes, closing brackets, backslashes, or newlines, escape them before placing the value in the message:

• ' → |'
• ] → |]
• \ → ||
• newline → |n

Simple values that contain none of these characters can be used without additional escaping.

The change is limited to the current build

The updated value is not persisted in the build configuration. The configured default is used again the next time the build runs.

Dependent builds do not inherit the value automatically

The parameter change is available only within the current build configuration. A dependent build in a build chain does not automatically receive it. Pass the value explicitly, for example through a dependency parameter or an artifact.

Summary

Use setParameter when a build step must publish a value for later steps:

compute value → emit setParameter → consume value in a later step

The service message is written to standard output, parsed by the TeamCity agent, and applied to subsequent steps in the same build.