Use Parameters in Build Chains
This topic illustrates how you can use TeamCity build parameters to exchange simple data between configurations of a build chain.
Access Parameters of Preceding Chain Builds
Dependent builds can access predefined and custom parameters of the previous chain builds as dep.<bcID>.<parameter_name>
, where bcID
is the ID of a source build configuration whose parameter value you need to access.
You can use dep...
parameters to access parameters from a configuration even if the current configration has only indirect dependencies. For example, in the A → B → C chain where C depends on B and B depends on A, configuration C can access A's parameters.
The following build configuration builds and pushes a Docker image. The name of this image is written to the DockerImageName
parameter.
If this configuration's ID is "ConfigA", builds executed further down the build chain can access the image name as dep.ConfigA.DockerImageName
:
Override Parameters of Preceding Configurations
Add a parameter with the reverse.dep.<build_conf_ID>.<parameter_name>
name syntax to override the <parameter_name>
parameter defined in the target configuration that precedes the current configuration.
For example, the following Kotlin code defines a project with three build configurations united in a single build chain (ConfigA → ConfigB → ConfigC). Each build configuration has a chain.ConfigX.param
parameter with its custom value. The last configuration has the additional reverse.dep.ChainConfigA.chain.ConfigA.param
parameter.
If you run the ConfigA or the ConfigA → ConfigB sub-chain, the first configuration will report its original parameter value.
However, if you run a full build chain that ends with ConfigC, this last configuration will feed ConfigA a custom parameter value.
You can use *
wildcards in parameter names to the same parameters in multiple preceding configurations. For example, the ConfigC in the following sample has the reverse.dep.ChainConfig*.MyParam
parameter, which overrides MyParam
in both ConfigA and ConfigB.
Conflicting Parameter Overrides
If in the ConfigA → ... → ConfigB → ... → ConfigC chain both ConfigB and ConfigC configurations try to override ConfigA's parameter ConfigC has a higher priority since it depends on ConfigB (either directly or through intermediate configurations).
However, if ConfigB and ConfigC do not depend on each other, an ambiguity regarding which configuration should have a priority emerges. TeamCity tries to resolve this ambiguity by comparing parameter names and prioritizing a parameter with the most specific build configuration ID.
Highest priority: parameters with no wildcards in build configuration IDs (for example,
reverse.dep.ChainConfigA.MyParam
).Medium priority: parameters with partial configuration IDs (for example,
reverse.dep.Chain*A.MyParam
). The more specific the target configuration ID is, the higher the priority of this parameter. For instance, theChainConf*A
ID has a priority over theChain*A
ID since it is considered more specific.Lowest priority: parameters with the
*
wildcard instead of configuration IDs (for example,reverse.dep.*.MyParam
).
If all conflicting configurations have similar parameter names and neither of them is a clear winner, TeamCity reports a conflict and creates additional conflict.<build_config_ID>.<parameter_name>=<value>
parameters (one for each conflicting configuration).
Other Considerations
The
reverse.dep.*
parameters are processed on queuing a build where these parameters are defined. Since parameter values should be already known at this stage, these values must be assigned either in the build configuration or in the custom build dialog. Setting the parameter to a value calculated during a build has no effect.Pushing a new parameter into a build overrides the " Do not run new build if there is a suitable one " snapshot dependency option and may trigger a new build if the parameter is set to a non-default value.
Values of the
reverse.dep.
parameters are pushed to the dependency builds "as is", without reference resolution.%
-references, if any, will be resolved in the destination (target) build's scope.