TeamCity

Connect TeamCity to Team Server, install the Runtime Sensor on every build agent, and add first and final Endura steps to protected build configurations.

Object Mapping

Discover the project before instrumenting it. All its build configurations share one policy; subprojects are separate pipelines.

Project and build matching use the public project ID and numeric build ID. Renaming a project preserves its pipeline. Renaming a build configuration starts a new exact-name group for protection calculations.

Prerequisites

• Operator or Administrator access to Team Server
• TeamCity access that can create a token and edit build configurations
• Root access to every protected Build Agent host

Configure the Integration

Credentials and Permissions

Use a dedicated TeamCity service account with the Project Viewer role on every project Team Server should discover. Assign the role to a common parent project when all of its subprojects should be included because project permissions are inherited by subprojects.

Under Profile > Access Tokens, create a project-limited token and select the Read-only preset for each required project or common parent. Team Server only reads server information, projects, build configurations, and build history. It does not need permission to edit projects, run builds, or administer TeamCity.

Set an expiry and rotation owner; store the token in a secrets manager.

Add TeamCity to Team Server

1. Open Integrations, then TeamCity under Discover.
2. Select Get Started or Create.
3. Enter the TeamCity base URL and token.
4. Select Test, then Save.

Projects appear under Pipelines. Use separate integrations for separate TeamCity servers. For a private address or internal CA, configure Team Server outbound HTTP policy.

Schedule Discovery

Add these jobs to scheduler.jobs:

teamcity_pipelines:
  run: "teamcity_sync mode:pipelines trigger:scheduled"
  schedule: "0 8 * * * * *"
teamcity_builds:
  run: "teamcity_sync mode:builds trigger:scheduled"
  schedule: "0 12,27,42,57 * * * * *"

Keep statistics_calculate and status_reconcile enabled. Restart Team Server after changing configuration; see Scheduler.

Manage Sync and Deletion

Use Start Sync for an immediate run. See sync controls and deletion.

Install the Runtime Sensor on Agents

Install the Sensor on every eligible Linux x86-64 Build Agent in protected pools, including autoscaled images/provisioning.

Keep license, token, and Team Server URL in root-only host configuration; build steps need only unprivileged job commands. Verify endura sensor status and root-only endura sensor hooks on each agent.

Configure Build Parameters

The Runtime Sensor reads teamcity.build.id and teamcity.project.id from TeamCity’s generated Java properties files. TeamCity exposes the build properties through its predefined build parameters as the TEAMCITY_BUILD_PROPERTIES_FILE environment variable; the file can point to the configuration properties that contain the project ID. Do not create replacement ID parameters manually.

Add these environment parameters at the Root Project, project, or build-configuration level:

Root Project parameters are inherited by subprojects and configurations unless overridden.

Instrument a Build Configuration

First Step

Add teamcity.internal.bootstrap.steps.enabled=true as a project configuration parameter to enable bootstrap steps. Under Build Steps, add a Command Line step named Start Endura Job with this custom script:

set -e

# Start protection before source checkout.
ENDURA_JOB_ID=$(endura job start)
echo "started endura job with id ${ENDURA_JOB_ID}"

Keep set -e to propagate startup failure. Both Endura steps must use the same existing workspace: leave their working directory at the checkout directory, or pass the same explicit workspace. The default is the step’s PWD.

Select Run during bootstrap, then move the step before the Preparation stage block. A bootstrap step runs before TeamCity checks out source files, so checkout is protected too.

Final Step

Add a Command Line step named Stop Endura Job:

endura job stop

Move it last and set Execute step to Always, even if build stop command was issued. This setting is required for cleanup after failures and cancellation.

Force cancellation can skip the final step. Keep cancellation retirement enabled as a fallback.

Build Configuration Templates

Create a TeamCity template containing the bootstrap-enablement parameter, the three environment parameters, and both Endura steps. In the step-order editor:

1. mark Start Endura Job as a bootstrap step and place it before Preparation stage;
2. place Stop Endura Job below the build-configuration steps placeholder so it remains last; and
3. attach the template to every existing protected configuration.

Set it as the project’s default template for new configurations. Existing configurations must still be attached explicitly.

Container-wrapped Build Steps

Keep Endura start/stop on the Build Agent and use the Container Wrapper for build steps. The host Sensor covers containers; those steps need no CLI or socket.

If the Endura steps must also use a Container Wrapper, bake the CLI into their image with the testing installer. Configure both Endura steps to use that image and add this volume under Additional run arguments for both:

--volume=/run/endura/sensor.sock:/run/endura/sensor.sock

Each wrapped step has a separate container: both Endura steps need the CLI image and socket. Keep the stop step unconditional.

Standard wrappers preserve agent paths, including generated properties files; no extra properties mount is needed. Custom arguments must keep those paths readable.

Build Chains and Composite Builds

Instrument each working configuration in snapshot-dependency chains; composite configurations execute no work. Configurations share their project policy, while separate projects can differ. Derive across the full chain.

Verify

1. Run each instrumented build configuration.
2. Open the TeamCity project under Pipelines in Team Server.
3. Confirm each run appears under Builds.
4. Confirm each selected Build Agent reports the expected Team Server connection and hook coverage.
5. If a build is missing, check discovery, agent pool placement, template attachment, and step logs.

Troubleshooting

Create and Assign a Policy

Derive across representative build configurations and chains and capture the policy printed by endura job stop. Refine and test it in observe mode, then assign it to the TeamCity project pipeline before enforcement.

Configure notifications after violations reach Team Server.