JetBrains / JetBrains/teamcity-cli

Start a build configuration and forward an agent port to localhost

Open
#426 0 comments 0 reactions 0 assignees View on GitHub
area:build-ops enhancement
Dominant language
Go
Stars
123
Forks
16
Avg merge
1d 13h
Merged PRs (30d)
22

Description

### Area

Build Operations (run, trigger, cancel, logs)

### Problem or use case

I want to start a build configuration that prepares a remote workspace and runs a service, then connect a local client to it. For example, run a Codex app-server in the TeamCity environment and use the local Codex terminal UI, without manually finding the assigned agent and configuring a tunnel.

### Proposed solution

Illustrative syntax:

```bash
# Terminal 1 (proposed syntax)
teamcity run start Remote_Codex --forward-port 1144:4500

# Terminal 2
codex --remote ws://127.0.0.1:1144
```

Here, the build configuration starts a Codex app-server on port `4500` of its build agent. The proposed flag exposes it locally on `127.0.0.1:1144`.

Expected behavior:

- Start the specified configuration with the usual branch, revision, and parameter options; wait for the run and remote port to become ready.
- Forward TCP traffic to the agent assigned to that run, including agents without direct inbound access from the user's machine.
- Bind to localhost by default, print the run URL and local endpoint, and keep the tunnel open in the foreground.
- Report startup, port-binding, and connection failures; close the tunnel when the run ends and make detach versus build cancellation explicit on interruption.

The forwarding mechanism should work for arbitrary TCP services, including web previews and debuggers.

### Alternatives considered

Start the run, find its agent, and configure SSH port forwarding manually. This requires separate connection setup and direct access to the agent.

### Contribution

- [ ] I'd be willing to submit a PR (once it's `status:finalized`)

Contributor guide

Open the contributing guide

Research direction

Start by tracing the existing build-configuration run flow and agent connectivity; the issue names no files or tests. Define how the command starts a run, waits for the remote port, forwards arbitrary TCP traffic on localhost, reports failures, and handles interruption, completion, detachment, and cancellation.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
build-system, cli, networking
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.