Composite Build Configuration
Composite build configurations are "step-less" configurations designed to trigger multiple regular build configurations and track the results in a single place.
Key Takeaways
Composite configurations do not carry out any actual building routines.
Composite configurations aggregate all information from their dependencies and present them in a centralized manner.
Composite builds do not occupy build queue slots and do not require agents to run.
To switch a build configuration type, navigate to the Configuration settings | General tab.
Example
In this tutorial, you will create multiple build configurations, bind them in a single build chain, and learn how you can benefit from turning the topmost build configuration of a chain into a composite configuration.
Create a Sample Project
In this step, you will create a project with an empty build configuration and a subproject with five build configurations that build, test, and publish .NET/.NET Framework projects under different platforms.
![Sample setup Sample setup](https://resources.jetbrains.com/help/img/teamcity/2023.09/dk-compositeConf-projects.png)
Create a project from the following GitHub repository (or its fork): TeamCity DotNet Samples. When importing a project, choose the Do not import settings, create project from scratch option.
Set the build configuration name to "Build All".
Do not select any steps suggested by TeamCity after it scans the repository. We will perform actual building tasks in separate configurations, and this initially created configuration will be used later to trigger all of them at once.
Go to Administration | <Your Project> and click Create Subproject. This subproject should target the same GitHub repository as in Step 1.
Since your subproject uses the same repository as the root project, TeamCity suggests that both projects share the same VCS root instead of creating a duplicate. Click Use this when prompted to agree.
In your new "Building Configurations" subproject, create five building configurations. All configurations should target the same repository as in Step 1 and use the shared VCS root (see Step 5).
Run Tests (Linux) — a configuration with a single .NET runner that tests the "Clock.Tests" C# project inside the .NET SDK container for Linux.
Run Tests (Windows) — a configuration with a single .NET runner that tests the "Clock.Tests" C# project on a Windows agent with a required .NET SDK installed.
Build Desktop (Windows) — a configuration with a single .NET runner that executes the "msbuild" command on the "Clock.Desktop" and "Clock.Desktop.Uwp" projects.
Build console & web (win-x64) — a configuration with two .NET steps.
One step executes the "publish" command on the "Clock.Console" project with the "win-x64" runtime option. The output directory for this step is set to "bin/Clock.Console/win-x64".
Another step executes the "publish" command on the "Clock.Web" project. The Runtime option for this step is "win-x64", the Output directory is "bin/Clock.Web/win-x64".
Build console & web (linux-x64) — same as the previous configuration, but the Runtime and Output directory settings of .NET steps are set to "linux-x64" and "bin/<ProjectName>/linux-x64" respectively.
Since these build configurations will be parts of a single build chain, you do not need automatically added build triggers to start all five build configurations independently whenever TeamCity detects changes in the remote repository. Go to Build configuration settings | Triggers and disable or delete triggers for all configurations (except for the "Build All" configuration owned by the topmost project).
Both "Build console & web" configurations should publish their "bin" folders. To do that, specify the
bin => bin
artifact paths in these configurations. Published artifacts will be later used by deployment configurations.
You should end up with five independent build configurations that perform build steps and an empty "Build All" configuration. Run each configuration to ensure they finish successfully. The Kotlin code below illustrates settings for all five build configurations and their parent TeamCity projects.
Set Up a Build Chain
In this step you will create snapshot dependencies to bind build configurations in a single chain.
![Full chain Full chain](https://resources.jetbrains.com/help/img/teamcity/2023.09/dk-compositeConf-chain.png)
In the "Build Desktop (Windows") configuration settings, switch to the Dependencies tab and click Add new snapshot dependency. Check the "Run Tests (Windows)" build configuration to tell TeamCity it should run tests before launching this building configuration.
Repeat step 1 to set up snapshot dependencies for both "Build console & web ..." configurations. They should depend on corresponding "Run Tests..." configurations.
In the "Build All" configuration settings, add snapshot dependencies to all three "Build..." configurations.
The three "Build..." configurations publish artifacts. To make them accessible from the topmost "Build All" configuration, you need to create artifact dependencies.
Navigate to <Build All settings> | Dependencies, click Add new artifact dependency, and create dependencies for all three "Build..." configurations. The Artifact rules setting in each artifact dependency should be
**/*.* => .
.Now that the "Build All" configuration can access to artifacts produced by individual "Build..." configurations, add the
bin/**/*.* => .
artifact publishing rule in its general settings.
The Kotlin code below illustrates the final chain setup.
Create a Composite Configuration
You can choose a build configuration type in the General tab of configuration settings. In this sample chain, you can change the "Build All" configuration type to "Composite".
![Configuration type Configuration type](https://resources.jetbrains.com/help/img/teamcity/2023.09/dk-compositeConf-ConfType.png)
When compared to regular build configurations, composite configurations exhibit the following differences.
Icons
TeamCity uses different icons to help you differentiate regular and composite configurations.
In the navigation bar:
![Regular configuration icon Regular configuration icon](https://resources.jetbrains.com/help/img/teamcity/2023.09/dk-compositeConf-regularIcon.png)
On the Build Configuration | Chains page:
![Regular configuration icon in chains Regular configuration icon in chains](https://resources.jetbrains.com/help/img/teamcity/2023.09/dk-compositeConf-regIconChains.png)
In the navigation bar:
![Composite configuration icon Composite configuration icon](https://resources.jetbrains.com/help/img/teamcity/2023.09/dk-compositeConf-compIcon.png)
On the Build Configuration | Chains page:
![Composite configuration icon in chains Composite configuration icon in chains](https://resources.jetbrains.com/help/img/teamcity/2023.09/dk-compositeConf-compIconChains.png)
Configuration Settings
A composite build configuration aggregates results produced by other builds. It is not designed to carry out actual building routines. For that reason, composite configuration settings do not show Build steps or Agent requirements tabs.
![Composite configuration settings Composite configuration settings](https://resources.jetbrains.com/help/img/teamcity/2023.09/dk-compositeConf-ConfSetting.png)
Starting and Cancelling Composite Builds
Since a composite build configuration does not have any actual build steps to perform, it does not occupy a slot in a build queue.
![Running composited configuration Running composited configuration](https://resources.jetbrains.com/help/img/teamcity/2023.09/dk-compConf-queue.png)
If you limit the number of simultaneously running composite builds, it will affect all dependencies as well. For example, suppose the current limit is 1, and a composite build is running. In that case, all dependency builds that belong to another queued composite build will wait for the ongoing build to finish.
When you stop a composite build or remove it from the queue, the entire build chain is stopped or removed.
Aggregating Results
When the first dependency of a build chain starts, the composite build is shown as running. The build's status text, duration, and progress indicator reflect the aggregated parameters of every regular build in this chain.
![Composite build running Composite build running](https://resources.jetbrains.com/help/img/teamcity/2023.09/dk-compositeConf-running.png)
If any build in a chain fails, the composite build reflects this so you can instantly spot the issue.
![Composite build failing Composite build failing](https://resources.jetbrains.com/help/img/teamcity/2023.09/dk-compositeConf-failing.png)
The Tests tab of a composite build aggregates tests and shows all passed, failed, muted, and ignored tests in a single place. The same applies to code coverage or results of code inspection/code duplicate analysis.
![Composite build tests Composite build tests](https://resources.jetbrains.com/help/img/teamcity/2023.09/dk-compositeConf-tests.png)
Artifacts
Neither regular nor composite builds aggregate artifacts from builds in their chains. To show artifacts produced by regular builds in the composite build's Artifacts tab, add corresponding artifact dependencies and set up required artifacts rules (see steps 4 and 5 in the Set Up a Build Chain section).
![Artifacts of a composite build Artifacts of a composite build](https://resources.jetbrains.com/help/img/teamcity/2023.09/dk-compositeConf-artifacts.png)
Since a composite configuration does not have its own artifacts, artifact clean-up policies need to be set in dependency configurations.
Composite Build Grouping
The Project | Build Chains page displays the Group composite builds option that allows you to collapse all parts of a build chain that end with a composite configuration into one visual element.
![Grouping composite builds Grouping composite builds](https://resources.jetbrains.com/help/img/teamcity/2023.09/dk-compConf-groupCompBuilds.png)