How to connect from a build to an internal resource

Question

Affected versions: TeamCity Cloud

The build is running on a JetBrains-provided agent and needs to access a resource on an internal network to which the agent doesn't have direct access. How to connect from a build to a resource on the internal network?

Answer

There are two main options:

1. Use a Dedicated On-Premises or Self-Managed Cloud Agent

Run at least one TeamCity agent inside your internal network — either on-premises or in a self-managed cloud environment (e.g., an EC2 cloud profile with a VPC connected to Site-to-Site VPN). Then, configure the build configuration that requires access to internal resources to run only on that agent.

Pros:

• Straightforward setup (in the case of an on-premises agent).
• No need for networking workarounds during the build.

Cons:

• You must maintain at least one self-managed agent (on-premises or cloud).

2. Establish Secure Network Access from the Build Runtime

If you prefer to use only JetBrains-hosted agents, consider setting up secure access to your internal resources at runtime. Since JetBrains-hosted agents provide root access during builds, you can configure network access dynamically.

Common approaches include:

• VPN Setup via Scripted Build Step Install and configure a VPN client during the build. This joins the build agent to your private network. You must also join your internal resource to the same VPN network. Note: Tailscale is commonly used for its simplicity, but other VPN solutions may also work.
• SSH Tunnel to Internal Network Establish an SSH tunnel to a bastion host or NAT gateway that resides inside your network. Restrict access to the tunnel by IP or authentication.

Pros:

• Allows you to use JetBrains-hosted agents without maintaining your own build agents or agent cloud profiles.

Cons:

• Adds complexity to builds.
• Can be tedious to debug if the network configuration fails.