Integrating TeamCity with Docker

Last modified: 20 April 2023

TeamCity comes with Docker Support, implemented as a bundled plugin.

note

The integration requires Docker installed on the build agents. Docker Compose also needs to be installed to use the Docker Compose build runner.

Supported Environments



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

note

  • On Linux, the 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.

Parameters Reported by Agent



During the build, the build agent reports the following parameters:

Parameter

Description

docker.version

The Docker CLI version

dockerCompose.version

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

docker.server.version

The Docker Engine version

docker.server.osType

The Docker Engine OS platform, can have the linux or windows value

If you are using the Command Line Build step (and not the TeamCity-provided docker steps), these parameters can be used as agent requirements to ensure your build is run only on the agents with Docker installed.

Features



TeamСity-Docker integration provides the following features which facilitate working with Docker under TeamCity:

Docker Support Build Feature



Docker Connection for a Project



Docker Runner



Docker Compose Runner



Docker Wrapper



TeamCity provides the Docker Wrapper extension for Command Line, Maven, Ant, and Gradle runners. Each of the supported runners has the dedicated Docker settings section.

Docker Settings



Docker Disk Space Cleaner



Docker Disk Space Cleaner is an extension to the Free Disk Space build feature ensuring a certain amount of disk space for a build. Since 2018.2 TeamCity performs regular clean-up of Docker images, related to TeamCity:

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

  • During cleanup / freeing disk space, TeamCity agent tries to remove these images if they were not used within 3 days, 1 day, 0 on subsequent attempts to free disk space.

Besides that, TeamCity cleans local Docker Caches using the command:

  • Since TeamCity 2018.1.2: docker system prune --volumesWorks for Docker v.17.06.1 or later.

  • Before TeamCity 2018.1.2: docker system prune -a

Service Message to Report Pushed Image



If TeamCity (for some reason) cannot determine that an image was 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']