Assign an agent to run the specific build using REST API

Hi Rohith. You can run a build in the web UI on a specific agent there the Run Custom Build dialog. If you need to automate that, you can also do that via REST API. See this section of the REST API reference.

If you want TeamCity to always assign the builds of certain build configurations to certain agents, please take a look at Agent pools or Agent Requirements.

Thanks for your swift reply. Highly appreciate it.

No, Assigning agents to builds are dynamic and they change every time. So, I think Agent pools won't work in my case.

Regarding the REST API, It looks promising but I am not sure where to inject this automation logic. In short, How can I tell TeamCity not to use it's predefined logic to assign agents for the queue builds but instead use my automation logic. Do I have to write a plugin for that?

That depends on your use case. Can you share a bit more information about it? Such as how do you trigger the builds currently? How do you want to trigger them ideally? When do you need a specific agent and when you are fine with TeamCity choosing an agent?

We use the standard teamcity server - agent model provided by you guys. We have multiple build configurations for different projects and for each configuration, we have certain number of build steps which needs to be performed in order. We don't use any plugins except Slack Notifications.

We want to take control of triggering the agent - build assignment into our control completely. We don't want TeamCity to do that. Currently, TeamCity handles choosing an agent logic based on CPU rank but in our case, we want to use different heuristic which we think it's better for our build pipeline.

For that, I thought of two options

1. Use TeamCity REST API to trigger the agent-build assignment and override the original behaviour given by TeamCity. If it's REST, I can stick to our preferred language stack and can make this work.

2. https://github.com/grundic/teamcity-agent-priority/ I came across this plugin. I can modify it and trigger builds accordingly but this seems to be a bit more work than the 1st option.

Hope this explains and please suggest the best way. In short, We want to take control of TeamCity agent - build assignment.

The first option should work. You can specify the agent when triggering a build via REST API using the <agent id="agentId"/> element. Whenever you omit that element, TeamCity will choose an agent itself.

As for the agent priority plugin, I do not have comments about how you can use it, sorry. We have a feature request in our tracker for native support of the agent priority feature. You might want to vote for and watch this item: https://youtrack.jetbrains.com/issue/TW-23336.

As a side note, since 2020.1, TeamCity has a built-in Slack integration for sending notifications.

Once again, thanks for the swift reply. But I am still confused about usage. If I plan to use the REST API, there will be two separate processes trying to do agent - build assignment. One is my REST API and the other is from TeamCity.

So, How can I disable TeamCity assignment and only listens to REST API? Is that possible? If that's the case, I can have a daemon running in my teamcity server, continuously polling for new changes, compute my heuristics and choose the best agent and assign that.

You are right: the solution with triggering a build via REST API would work best if you want to handle the triggering of the builds. But if you need TeamCity to trigger the builds, e.g. with a VCS Trigger, and you also would like to be able to switch between the default (agent-CPU-rank-based) policy to a custom way of assign the builds, you can use the Agent Requirements. You can add an agent requirement like system.agent.name contains MyAgentName to the necessary (or even all) configurations when you want the custom policy, and remove that requirement when you want the default one.

You can automate editing the build configuration settings to add/remove the requirement via REST API as well.

I am not sure how and when you would like to change the way the builds are assigned to the agents, and what is the desired policy going to look like. If you share those details, it might also help.

So, Here's my requirement. For every change in my VCS root, I would like to compute some heuristics and rank my build agents and assign the best agent to the current change for build. Either I can trigger the build (or) let the TeamCity trigger it, It really does not matter to me.

According to your suggestion, I have to edit build configuration every time there's a change and then add the `system.agent.name` to the best agent I have found such that TeamCity will trigger the build based on these new build config. Is that right? If yes, how to avoid TeamCity not to pick up the build configuration until I compute my heuristics and assign the agent requirement? Because TeamCity server will be running in parallel along with my new custom script and It can result in conflict.

Does it make sense?

Any response here?

Hi Rohith,

sorry, Anatoly has been a bit busy this last week, I'll take over to avoid further delays.

I think you are making this seem a lot more complex than it actually is. If you don't mind triggering yourself via REST, as you mentioned, then simply remove all automatic triggers from the build configuration and trigger via REST specifying the agent. That way, teamcity will not attempt to trigger or to assign another agent, it will only process your request and assign the agent you specified.

If this is not the behavior you are observing, then it is very likely that there is some configuration in your setup that you haven't disclosed and is interacting with the process. Dependencies, automatic triggers, external scripts or other modifications to the build configurations might be disrupting here and we would need to have that information to know why your setup doesn't behave as expected.

If you still want teamcity to automate triggering so you don't have to but, in the process, run some script to customize some of the parameters, such as the agent, the easiest approach is to have a "triggering build". A separate build that has the automated trigger (typically VCS, but can be scheduled, or any other of course), then it runs the calculations you want to run, and once you have everything compiled, just send the trigger to the actual build via REST. Again, if you send the REST request yourself to a build that has no automated triggers, teamcity will not try in itself to override your settings.

okay, I will keep the problem statement pretty clear here. 

Our teamcity setup has five build agents. For the notational purposes, let's call them A, B, C, D, E. Whenever we see a change in vcs root, we trigger a build ( add it to the build queue ) and one of the build agents will pick up them. This is pretty standard support provided by teamcity. Build agents are chosen based on CPU rank heuristic. Fair enough.

On our build agents, we run bazel builds. Bazel is quite intelligent enough to cache untouched binaries which results in faster build process. Let's say there's commit X which is about to be scheduled on either A (or) B build agents, we would like to assign commit X to the build agent which has less build time.

How do we find out the right build agent? It's completely heuristic and we would like to start with something like number of lines of code changed between last successful build revision on the build agent and the current revision of the pending change which is about to be assigned.

Hope you understand it quite clear by now. My options

1. https://github.com/grundic/teamcity-agent-priority/ ( I am modifying this plugin currently to support this functionality )
2. REST API ( this will make my life easier and better but I am not sure exactly on how to achieve that )

Please suggest the best option

Hi Rohith,

I'm not sure I expressed myself clearly enough. Your setup is clear, I wasn't asking for more details. TeamCity is a very flexible tool and often there are many ways to do the same thing. Both the "agent priority" plugin if modified, and the REST API can accomplish what you want to do.

What is the best option at that point is not up to us, but to you, as you will be in the position of having to maintain whatever route you take. Plugin APIs are usually stable but can often need to be recompiled for newer versions. REST APIs are typically very stable and on most scenarios don't need to be adapted, so it's often even easier. As you also mentioned, it would let you keep your language stack, so it's likely to be much easier. The plugin route's main advantage is that it would be more tightly integrated and you could change functionality easily, while still taking advantage of the integrated features.

Again, both options will do the job. Which is better depends on you and your preferences, so we would rather not make the call in there.