You are viewing the documentation of TeamCity 10.x and 2017.x, which is not the most recently released version of TeamCity.
View this page in TeamCity 2018.x documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

Skip to end of metadata
Go to start of metadata



For TeamCity 2017.1.x Docker Support is available as a separate plugin supporting build agents on Mac and Linux. See the related blog-post.

TeamCity 2017.2 comes with built-in Docker support. If you installed the plugin for the previous version manually, please remove it.



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

For TeamCity 2017.2.x 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. 

  • On Linux, the integration will run if the installed Docker is detected. 
  • On Windows,  the integration works in the Windows container mode only. Docker on Windows with the Linux container mode enabled is not supported, an error is reported in this case. 
  • 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:

docker.versionThe Docker Engine version
dockerCompose.versionThe Docker Compose file version if the Docker Compose build step is used
 docker.server.osTypeThe Docker server OS type, 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. 


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

Docker Support Build Feature

Adding this build feature will enable docker events monitoring: such operations as docker pull, docker run will be detected.  The build feature adds the Docker Info tab to the build results page providing information on Docker-related operations. 

Since TeamCity 2017.2 this build feature provides the following options:

  • the ability to clean-up the images
  • automatic login to an authenticated registry before the build and logout of it after the build 

These options require a configured connection to a docker registry.

Clean-up of images

If you have a build configuration which publishes images, you need to remove them at some point. You can select the corresponding option and instruct TeamCity to remove the images published by a certain build when the build itself is cleaned up. It works as follows: when an image is published, TeamCity stores the information about the registry of the images published by the build. When the server clean-up is run and it deletes the build, all the configured connections are searched for the address of this registry and the images published by the build are cleaned up using the credentials specified in the connection found.

Automatic Login to/Logout of Docker Registry

 If you need to log in to a registry requiring authentication before a build, select the corresponding option and a connection to Docker configured in the project settings. Automatic logout will be performed after the build finishes.

Docker Connection for a Project

The Project Settings | Connections page allows you to configure a connection to docker.io (default) or a private Docker registry. More than one connection can be added to the 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.

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

  • Since TeamCity 2017.2.3, it is possible to get authenticated with an Azure container registry storing Docker images using Service principal (the principal ID and password are used as connection credentials) or Admin account.

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 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.

Docker Build Runner

The runner allows building Docker images as a separate build step. When creating TeamCity projects/ build configurations from a repository URL, the runner is offered as build step during auto-detection, provided a Dockerfile is present in the VCS repository.

Docker Build Parameters




Dockerfile source

Depending on the selected source, the settings below will vary. The available options include File, a URL or File content.

Path to file

Available if File is selected as the source. Specify the path to the Docker file. The path should be relative to the checkout directory.

Context folderAvailable if File is selected as the source. Specify the context for the docker build. If blank, the enclosing folder for Dockerfile will be used.

URL to file
Available if URL is selected as the source. The URL can refer to three kinds of resources: Git repositories, pre-packaged tarball contexts, and plain text files. See Docker documentation for details.
File Content:Available if the file content is selected as the source. You can enter the content of the Dockerfile into the field.

Provide a newline-separated list of image name:tag(s)

Additional arguments for 'build' commandSupply additional arguments to the docker build command. See Docker documentation for details.

To push the built images to the repository, add the Command Line build step with the docker push command to your configuration.

Docker Compose Runner

The runner allows starting Docker Compose build services and shutting down those services at the end of the build.

Docker Compose YAML file with a description of the services to be used during the build is required. The path to the docker-compose.yml file should be relative to the checkout directory

The executed commands are


When using Docker Compose with images which support HEALTHCHECK, TeamCity will wait for the healthy status of all containers, which support this parameter.

If the start of Docker Compose was successful, the TeamCity agent will register the TEAMCITY_DOCKER_NETWORK environment variable containing the name of the Docker Compose default network. This network will be passed transparently to the Docker Wrapper when used in some build runners.

Docker Wrapper

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

Docker Settings

In this section, you can specify a Docker image which will be used to run the build step.

Run step within Docker container

Specify a Docker image here. TeamCity will start a container from the specified image and will try to run this build step within this container.  

Pull image explicitly (since TeamCity 2017.2)

If the checkbox is enabled, docker pull <imageName> will be run before the docker run command.

Additional docker run arguments

The Edit arguments field allows specifying additional options for docker run. The default argument is --rm.

Technically, the command of the build runner is wrapped in a shell script, and this script is executed inside a Docker container with the docker run command. All the details about the started process, text of the script etc. are written into the build log (the Verbose mode enables viewing them).

The checkout directory and most build agent directories are mapped inside the Docker process, and TeamCity passes most environment variables from the build agent into the docker process.

After the build step with the Docker wrapper, a build agent will run the chown command to restore access of the buildAgent user to the checkout directory. This mitigates a possible problem when the files from a Docker container are created with the 'root' ownership and cannot be removed by the build agent later. 

If the process environment contains the TEAMCITY_DOCKER_NETWORK variable, this network is passed to the started docker run command with --network switch. 

It is possible to provide extra parameters for the docker run command, for instance, provide an additional volume mapping.

Docker Disk Space Cleaner

When there is not enough disk space on the agent at the beginning of the build, the docker system prune -a command will be run cleaning the local Docker Caches. The command is run only as the last resort if all other cleaners did not manage to free enough space. Docker Disk Space Cleaner is an extension to the Free Disk Space build feature ensuring a certain amount of disk space for a build.


  • No labels


  1. From where do I download this plugin?

    1. Hello Luis,

        The plugin has not been released to the public yet, we're doing the internal testing. Please vote for https://youtrack.jetbrains.com/issue/TW-38023 to get notified when it is available.


  2. Hi, I am able to build docker image from VCS using Docker Build Runner and log-in to private Docker Registry with tne Docker Support Build Feature, but how do I push the image to the registry?


    1. If I add Command Line build step with "docker push" command, the image is successfuly pushed, but Docker Support Build Feature still complains that "There was no docker push event for the following image" in the log.

      1. Hi, Jakub Dorňák,

        Thank you for your comments. Please submit an issue to our tracker attaching the build log, agent's log, and the events.jason file from hidden artifact located in the .teamcity/docker directory? The screenshot of the Docker Info tab will also be useful to us to investigate the issue.

  3. hi  Kirill Maximov User Jakub Dorňák

    In my docker push step i've a issue . In the Custom script i would want to write the variable of (Name:tag(s)) but i cant find it .  i Dont want to write all the name again .

    Do you know where i can find a list with all variables ?

    Thank in advance

    1. Hello, you can create a custom build configuration parameter my_tags='tags/you_need' and then re-use this parameter in all places you need with %my_tags%. Would it solve your task?

      Please note that the coming TeamCity 2018.1 will have a dedicated "Docker" runner with a Docker push command.

  4. yeah that solve my problem thank you !