# Use Teamcity

> Interact with the kotlinx-rpc TeamCity CI/CD project using the `teamcity` CLI. Use this skill whenever the user wants to trigger builds, check build status, view build logs, monitor failures, manage the build queue, inspect agents, or do anything related to TeamCity CI. Also use it when the user mentions "TC", "TeamCity", "CI build", "run build", "build status", "build log", "trigger build", "check CI", or references a build configuration name or ID. Trigger even if the user doesn't say "TeamCity" explicitly -- if they ask about CI status, build failures, or want to run something on CI rather than locally, this is the right skill. Do NOT use this skill for local Gradle builds -- use `running_gradle_builds` or `running_gradle_tests` instead.

- Skill: `kotlin/use-teamcity` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add kotlin/use-teamcity`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kotlin/use-teamcity/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: Kotlin (https://skillmd.com/u/kotlin)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kotlin/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:

```bash
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

```bash
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):

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

### Check recent build status

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# List artifacts
teamcity run artifacts <build-id>

# Download artifacts
teamcity run download <build-id>
```

### View project/job hierarchy

```bash
# 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)

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

### JSON output for scripting

```bash
# 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=...`