Detaching Build from Agent
If a final step of a build triggers some external service and the build does not require a build agent anymore, the respective runner can detach the build from the agent. This makes this agent available to other builds. The build then continues running on the TeamCity server, and the external service reports its progress directly to the server. Such build steps are called agentless steps.
Releasing build agent
To release its current build agent, a runner needs to send the ##teamcity[buildDetachedFromAgent]
service message. After receiving this message, the agent skips all the following steps of the build, unless they have the "Always, even if build stop command was issued" execution policy enabled. If necessary, you can enable it for mandatory final steps — the agent will be released only after completing them.
If the limit of agentless builds is not exceeded, the server releases the agent and it instantly becomes available to other builds. Otherwise, the agent stays attached to the build until some of the running agentless builds finish.
Logging build data
During agentless steps, the external tool should report all build status information and send any other types of requests directly to the TeamCity server via REST API.
To perform a request, it needs to provide:
- build-level authentication credentials specified as build system properties:
username:
%system.teamcity.auth.userId%
password:
%system.teamcity.auth.password%
build ID:
%teamcity.build.id%
TeamCity server URL:
%teamcity.serverUrl%
An agent should send these parameters to the external software in advance, before being released.
Logging messages
To log messages, use the following call:
Here, you can send any service message as <message>
.
An example request to send a warning:
Finishing build
It is important to ensure that a build, executed externally, delivers a finishing request to the TeamCity server. If the server is temporarily unavailable and cannot receive this request, the external tool should retry until this operation is successful. Without the finishing request, the build will be running on the TeamCity server indefinitely, until reaching its specified timeout, if any.
To finish a build, use the following call:
Alternatively, you can finish it by sending the exact finish date as a non-empty string in the yyyyMMdd'T'HHmmssZ
format:
Agentless builds' licensing
The number of builds that can simultaneously run without an agent is limited by the number of your active agent licenses. For example, if you have 10 agent licenses, you can run in parallel up to 10 regular builds on agents plus up to 10 agentless builds. As soon as you reach the limit of running agentless builds, TeamCity will not detach steps in the following builds until some of the current agentless builds finish.