如何使用Python自动化为TeamCity项目中所有构建添加新构建代理

API 探路者

2026-4-29

Got it, let's figure out how to automate adding that new agent hostname to all build configurations in your TeamCity project. Doing this manually is a total drag, so here are a couple of reliable approaches depending on your setup:

Approach 1: Use TeamCity REST API (Great for external scripts)

This works if you want to run automation from a CI/CD tool, a server script, or your local machine.

First, grab your TeamCity API token: Head to your user profile > Access Tokens to create a token with sufficient permissions (you'll need Project Administrator or higher for the target project).
Fetch all build configurations in your target project with a GET request. Replace <project-id> with your project's actual ID (you can find this in the TeamCity URL when viewing the project):
```
curl -u "your-username:your-api-token" "http://your-teamcity-server-url/app/rest/projects/<project-id>/buildTypes"
```
For each build configuration returned, update its agent requirements. To add a new requirement instead of replacing all existing ones, first fetch the current requirements for a build type, merge in your new one, then send the updated list via PUT.
Example JSON request (add a header Content-Type: application/json):
```
{
  "agentRequirements": [
    // Include existing requirements here, plus your new one
    {
      "type": "equals",
      "propertyName": "agent.name",
      "value": "new-agent-hostname"
    }
  ]
}
```
The PUT endpoint for a build type is:
```
http://your-teamcity-server-url/app/rest/buildTypes/<build-type-id>/agentRequirements
```

Approach 2: Use TeamCity Server-Side Groovy Script (In-server automation)

If you prefer running automation directly within TeamCity, this is the way to go. You can run this via the Script Runner (Administration > Server Administration > Script Runner) or set it up as an automated task.

Here's a ready-to-use script (just replace the placeholder values):

import jetbrains.buildServer.serverSide.SBuildServer
import jetbrains.buildServer.serverSide.SProject
import jetbrains.buildServer.serverSide.AgentRequirement

// Update these to match your setup
def targetProjectId = "Your_Project_ID"
def newAgentHostname = "new-agent-01"

// Get the TeamCity server instance
def server = ctx.getSingleton(SBuildServer)

// Fetch the target project
def project = server.findProjectById(targetProjectId)
if (!project) {
    println "Project with ID $targetProjectId not found. Exiting."
    return
}

// Loop through all build configurations in the project
project.getBuildTypes().each { buildType ->
    // Check if the requirement already exists to avoid duplicates
    def requirementExists = buildType.getAgentRequirements().any { req ->
        req.getPropertyName() == "agent.name" && req.getValue() == newAgentHostname
    }

    if (!requirementExists) {
        // Create and add the new agent requirement
        def newRequirement = new AgentRequirement("agent.name", AgentRequirement.Type.EQUALS, newAgentHostname)
        buildType.addAgentRequirement(newRequirement)
        println "Added agent requirement to build config: ${buildType.getName()}"
    } else {
        println "Requirement already exists for build config: ${buildType.getName()}"
    }
}

println "Agent requirement automation finished!"

Bonus: Tie It to Agent Registration

If your new agents auto-register with TeamCity, you can take this a step further: set up an event listener to trigger the Groovy script automatically when a new agent registers. This way, the requirement gets added without any manual intervention at all.

内容的提问来源于stack exchange，提问作者Jamie s