Use Teamcity

TeamCity CLI for kotlinx-rpc

Interact with the kotlinx-rpc TeamCity project via the teamcity CLI (expected

to be installed at /opt/homebrew/bin/teamcity).

For local Gradle builds and tests, use running_gradle_builds /

running_gradle_tests skills instead.

Agent workflow override

When this skill is invoked from the fix-issue skill (autonomous issue-fixing workflow),

never run teamcity auth status or teamcity auth login. Instead, prefix every

teamcity command with TEAMCITY_TOKEN=$TEAMCITY_AGENT_TOKEN. The fix-issue skill's

Authentication section has full details. Outside of fix-issue, the defaults below apply.

Prerequisites

Before running any commands, verify authentication:

teamcity auth status

If not authenticated, the user needs to log in interactively -- suggest they run

! teamcity auth login in the prompt so the browser-based auth flow works in

their session.

TeamCity Project Structure

The root project is kRPC. It has two main branches:

• Build (Build_kRPC) -- CI builds triggered on PRs and commits
• Release (Release_kRPC) -- Publication to Maven Central, Space, GitHub

Reference Files

Read these as needed -- don't load them all upfront:

• references/build-ids.md -- Full catalog of build configuration IDs

(composite builds, platform builds, quality checks, compiler plugin builds,

special/scheduled builds). Read when you need to look up a specific build ID.

• references/remote-verification-table.md -- Decision table mapping changed

file paths to the minimal set of TeamCity builds to trigger. Read when deciding

which builds to run for a set of changes.

• references/release-builds.md -- Release pipeline build IDs for Sonatype,

Space EAP, and Space gRPC. Read only during release workflows.

Common Workflows

Trigger a build on a branch

teamcity run start Build_kRPC_All --branch feature/my-branch

Add --watch to stream progress in real-time. Without it, the command returns

immediately after queuing.

To trigger with custom parameters (e.g., override Kotlin version):

teamcity run start Build_kRPC_All --branch main -E KOTLIN_COMPILER_VERSION_ENV=2.3.20

Check recent build status

# Recent failures across all builds
teamcity run list --status failure --since 24h

# Recent builds for a specific configuration
teamcity run list --job Build_kRPC_All --limit 10

# Recent builds on a specific branch
teamcity run list --job Build_kRPC_All --branch main --limit 5

# Only running builds
teamcity run list --status running

Investigate a build failure

# View build details
teamcity run view <build-id>

# Show failure summary (most useful for quick diagnosis)
teamcity run log <build-id> --failed

# Stream full build log (opens in pager)
teamcity run log <build-id>

# Show test results
teamcity run tests <build-id>

# Show VCS changes that triggered the build
teamcity run changes <build-id>

Cancel or restart builds

# Cancel a running or queued build
teamcity run cancel <build-id> --comment "Cancelling: wrong branch"

# Restart a failed build
teamcity run restart <build-id>

Download build artifacts

# List artifacts
teamcity run artifacts <build-id>

# Download artifacts
teamcity run download <build-id>

View project/job hierarchy

# List all projects
teamcity project list

# View project tree
teamcity project tree kRPC

# List jobs in a project
teamcity job list --project Build_kRPC

# View snapshot dependency tree for a build config
teamcity job tree Build_kRPC_All

Dry-run (preview without triggering)

teamcity run start Build_kRPC_All --branch main --dry-run

JSON output for scripting

# Full JSON
teamcity run list --json --limit 5

# Specific fields
teamcity run list --json=id,status,webUrl --limit 5

# Plain text (for grep/awk)
teamcity run list --plain --limit 10

Build Configuration DSL

The TeamCity Kotlin DSL configs live in the sibling repository:

../kotlinx-rpc-build/.teamcity/src/

Ensure that the repository is cloned and up-to-date before running commands.

Remote: https://git.jetbrains.team/krpc/krpc-build.git

If not cloned - notify the user to clone it.

Key files when you need to understand or modify build configs:

| Path (relative to .teamcity/src/) | Purpose |

|---|---|

| project/Project.kt | Root project definition |

| project/build/__project.kt | Build subproject structure |

| project/release/__project.kt | Release subproject structure |

| util/id.kt | All build configuration IDs |

| util/target.kt | Platform target definitions |

| util/compilerVersions.kt | Supported Kotlin versions list |

| util/agent.kt | Agent requirements |

| util/repository.kt | Publication repository definitions |

| settings/kotlin.kt | Kotlin version parameters, IDE integration |

| settings/artifacts.kt | Artifact collection rules |

| settings/publishing.kt | Publishing configuration |

| dsl/build/ | Build DSL builders (per-platform) |

| dsl/release/ | Release DSL builders |

| project/vcs.kt | VCS root configuration |

Read these files from ../kotlinx-rpc-build/ when the user asks about

how a specific build is configured or wants to modify CI behavior.

Tips

• Build IDs are case-sensitive -- use them exactly as listed in references/build-ids.md.
• For composite builds (like Build_kRPC_All), failures in any dependency build

will show in the composite. Use run log <id> --failed on the specific

dependency build that failed, not the composite.

• Use --since and --until with durations like 24h, 7d, 1h for time-based

filtering.

• The teamcity api command can make raw REST API calls for anything the CLI

doesn't directly support: teamcity api /app/rest/builds?locator=...