TeamCity On-Premises 2023.11 Help

Configuring Connections to Docker

A preconfigured Docker connection allows you to:

  • sign in to an authenticated Docker or Podman registry before running a build / sign out after the build;

  • clean up the published images after the build (currently not available for Podman).

You can configure a Docker Registry connection on the Project Settings | Connections page. TeamCity supports connections to docker.io (default) or private Docker registries. More than one connection can be added to a project. The connection will be available in all the subprojects and build configurations of the current project.

Registry Address Format

By default, https://docker.io is used. If a build agent that runs a build uses Podman instead of Docker, the registry domain must be added to the registries.conf file. See the following article for more information: How to manage Linux container registries.

To connect to a registry, use the following format: [http(s)://]hostname:port.

If the protocol is not specified, the connection over https is used by default.

Connecting to Private Cloud Registry

TeamCity supports the Azure container registry storing Docker and traditional LXC images. You can authenticate using the Service principal (the principal ID and password are used as the connection credentials) or Admin account.

Amazon Elastic Container Registry (AWS ECR) is supported: specify the AWS region and your AWS Security Credentials when configuring the connection.

Connecting to Insecure Registry

To connect to an insecure registry:

  1. Configure all TeamCity agents where Docker is installed to work with insecure repositories as stated in the Docker documentation. This is sufficient to allow the connection to the private registry over HTTP.

  2. To connect to an insecure registry over HTTPS with a self-signed certificate, in addition to the step above, import the self-signed certificate to the JVM of the TeamCity server as described here. You can consult the Docker documentation on using self-signed certificates.

Running multiple agents with Docker on one machine

TeamCity supports the case when multiple agents are running parallel builds on the same machine and connect to a Docker registry during these builds. This setup requires using different Docker environments: the docker logout command executed at the end of the one build should not affect the parallel build on another agent.
To configure it, you need to specify locations of each agent's .docker directory. For this, define the env.DOCKER_CONFIG=%teamcity.agent.home.dir%/system/.docker environment variable either as a build configuration parameter or in the buildAgent.properties file of each agent.

Last modified: 07 September 2023