Integrating TeamCity with Container Managers
TeamCity integrates with container managers (Docker, Podman) on multiple levels.
The Docker build runner launches Docker commands and creates Docker images during a build.
The Container Wrapper extension executes build steps inside containers. Supports Docker and Podman. Available for multiple runners.
The Docker Support build feature automatically signs in to container registries using Docker or Podman before starting a build. This feature also adds the Container Info tab of Build Results with the information about the images published to a 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.
Compatibility and Requirements
To run a Docker- or Podman-related operation, a build agent must be able to use the
Docker can be installed on Linux, Windows, and macOS build agents.
On Linux, the Docker Support integration will run if the installed Docker is detected.
On Windows, the integration works for Linux and Windows container modes.
On macOS, the official Docker support for Mac should be installed for the user running the build agent.
Podman is a tool designed primarily for Linux. To run on Windows and macOS, Podman requires an installed Linux virtual machine ("Podman machine"). See the following article to learn more about installing Podman on different operating systems: Podman Installation Instructions.
Specify container registry domains in the
registries.conffile on your build agent machine. For example:
unqualified-search-registries = ["docker.io"]. Podman and TeamCity require this list of registries to:
Resolve full container addresses when a
podman ...command uses a short image name (for example,
podman pull ubi8instead of
podman pull registry.access.redhat.com/ubi8:latest).
Successfully log in to a registry if your build configuration has the Docker Support build feature.
See the following article to learn more about the
registries.conffile: How to manage Linux container registries.
Build Parameters and Agent Requirements
TeamCity checks the following parameters to identify the available agent software:
container.engine— returns "docker", "podman" or "docker,podman", depending on which container manager is installed on the agent machine. If both Docker and Podman are installed, TeamCity uses Docker by default.
podman.version— stores the version of installed Podman software.
podman.osType— return the type of the agent OS. Supported values are "linux" (for both Linux and macOS agents) and "windows".
dockerCompose.version— returns the Docker Compose file version, if the Docker Compose build step is used.
Depending on the exact Docker/Podman integration you utilize, TeamCity specifies different agent compatibility requirements. For instance, if your build configuration uses the Docker runner, this configuration can only run on agents that meet the
docker.server.version exists requirement.
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:
in a build with the Docker Support build feature, or
in a build step with the enabled Container Wrapper extension.
For such builds,
A TeamCity agent tracks Docker images tagged or pulled during the builds (the list of images is stored in the
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 сaches using the
docker/podman system prune --volumes command. For Docker installations, this clean-up works for 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:
Conforming with Docker Download Rate Limits
Since November 1st 2020, Docker Hub introduces download rate limits for public image pulls.
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.