TeamCity On-Premises 2022.10 Help

Integrating TeamCity with Docker

TeamCity integration with Docker includes:

  • The Docker build runner to launch Docker commands and create Docker images during a build.

  • The Docker Compose build runner to start services with the help of the Docker Compose tool during a build.

  • The Docker Wrapper extension to execute build steps inside a Docker container. Available for multiple runners.

  • The Docker Support build feature to automatically sign in to a Docker registry before starting a build. This feature also adds the Docker Info tab of Build Results with the information about the images published to the Docker registry during the build.

You can learn more details about the listed tools in the dedicated Help articles, linked above. The following article contains information common to these tools.


The integration requires Docker to be installed on the build agents. To use the Docker Compose build runner, you also need to install Docker Compose.

TeamCity periodically checks if Docker is available on active build agents. Based on the docker.server.version and docker.version variables received from the agents, TeamCity distributes builds that use Docker only between agents with the installed Docker engine.
If a build configuration uses the Docker runner or the Docker Wrapper extension, TeamCity automatically adds the docker.server.version agent compatibility requirement for this configuration.

Supported Environments

TeamCity Docker Support can run on Windows, Linux, and macOS build agents. It uses the docker executable on the build agent machine, so it should be runnable by the build agent user.

Parameters Reported by Agent

During the build, the build agent can report the following Docker-related parameters:




The Docker CLI version.


The Docker Compose file version, if the Docker Compose build step is used.


The Docker Engine version.


The Docker Engine OS platform. Supported values: linux or windows.

Docker Disk Space Cleaner

Docker Disk Space Cleaner is an extension to the Free disk space build feature ensuring a necessary amount of disk space for a build.

TeamCity regularly cleans up its related Docker images which were tagged/pulled:

For such builds,

  • A TeamCity agent tracks Docker images tagged or pulled during the builds (the list of images is stored in the buildAgent/system/docker-used-images.dat file).

  • During clean-up / freeing disk space, the TeamCity agent tries to remove these images if they have not been used within 3 days (or 1 or 0 days, on subsequent attempts to free the disk space).

Besides, TeamCity cleans local Docker Caches using the docker system prune --volumes command. Works for Docker v.17.06.1 or later.

Service Message to Report Pushed Image

If, for some reason, TeamCity cannot determine that an image has been pushed, a user can send a special service message to report this information to the TeamCity server:

##teamcity[dockerMessage type='dockerImage.push' value='<full_image_tag>,size:<size in bytes>,digest:<hash>']

For example:

##teamcity[dockerMessage type='dockerImage.push' value='myRegistry/repo-test:17,size:2632,digest:sha256:8dc5a195c3dcdc7c288d16288ff3f9ab1d8a5a230e09afb9c8dc9215e861aa55']

Conforming with Docker download rate limits

Since November 1st 2020, Docker Hub introduces download rate limits for public image pulls.

If your TeamCity builds use Docker Wrapper or Docker Compose to pull images from Docker Hub, make sure these pulls do not exceed the following limits:

  • Anonymous Docker users: 100 pulls per 6 hours

  • Docker users with the Free plan: 200 pulls per 6 hours

If you have a Team or Pro Docker account, the number of pulls stays unlimited.

A regular TeamCity agent stores a once pulled image in its cache. This allows running an indefinite number of builds using the same pulled image on a regular basis.
However, there are few cases to consider:

  • If you are using cloud agents, all required images will be downloaded every time a new cloud agent is launched.

  • If the Pull image explicitly option is enabled in the build step settings, the image will be downloaded in every new build run, even on a local agent. We recommend that you disable this option to prevent reaching the rate limit.

  • While freeing disk space for the build, TeamCity may clean up old unused Docker images from the local cache.

If previously your builds were accessing Docker Hub anonymously, you can double the number of allowed pulls by creating a Free Docker user profile and configuring a Docker connection in your TeamCity project. TeamCity agents will be able to use this connection to authenticate in Docker Hub before each build.

Last modified: 23 October 2022