TeamCity On-Premises 2024.07 Help

Docker

The Docker build runner allows launching the build, push, and tag Docker commands inside your build.

If you need to push the newly built image to a registry, you can authorize to a Docker or Podman registry by configuring the Docker Support build feature, as follows:

  1. In your project settings, select Connections from the sidebar and follow the instructions in Configuring Connections to Docker to add new Docker or Podman connections to your project.

  2. In your build configuration settings, follow the instructions in Docker Support to configure the Docker Support build feature, adding the connections created in the previous step.

If a Dockerfile is present in your VCS repository and you create a TeamCity project based on this repository, TeamCity will autodetect it and offer creating a build step using this runner.

Common Settings

This runner is a part of the TeamCity-Docker/Podman integration toolset. Refer to this documentation article for information on software requirements, supported environments, and other common aspects of this integration: Integrating TeamCity with Container Managers.

Available step execution policies are described here.

Docker Command

The runner provides the following settings, depending on the selected command:

Command

Parameter

Description

build

Dockerfile source

Depending on the selected source, the settings below will vary. Available options are File, URL, and File content.

Path to file

Available for the File source type:

Specify the path to the Dockerfile. The path should be relative to the build checkout directory.

Context folder

Available for the File source type:

Specify the context for the docker build. If blank, the parent directory of the Dockerfile will be used.

URL to file

Available for the URL source type:

The URL can refer to one of the three kinds of resources: Git repositories, prepackaged tarball contexts, and plain text files. See the Docker documentation for details.

File Content

Available for the File Content source type:

You can enter the content of the Dockerfile into the field.

Image platform

Select \<Any\> (default), Linux, or Windows.

Image name:tag

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

Additional arguments for the build command

Supply additional arguments to the docker build command. See the Docker documentation for details.

push

Remove image from agent after push

If selected, TeamCity will remove the image with docker rmi at the end of the step.

Image name:tag

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

other

Command name

Docker sub-command, like push or tag. For the run command, use Container Wrapper.

Working directory

Specify the build working directory if it differs from the checkout directory.

Additional arguments for the command

Additional arguments that will be passed to the docker command.

Running Docker via sudo

You can enforce starting Docker commands on a TeamCity agent via sudo. Add the teamcity.docker.use.sudo=true setting in the build agent configuration file or as an agent's system property. On the agent start, the TeamCity agent log will inform you that the sudo prefix is used to run Docker commands.

To configure the sudoers file for the sudo command, use visudo as follows:

buildagentuser ALL=(ALL) NOPASSWD:SETENV:<full_path_to_docker>

We recommend removing (or commenting out) the Defaults requiretty line from the sudoers file to prevent the problem with docker login.

Building Multi-Arch Images

The other... command option allows you to execute any custom docker ... command. For example, you can invoke buildx commands to build multi-arch images.

  1. Add a new Docker runner to your build configuration.

  2. Switch its Docker command option to "other...".

  3. Type "buildx" in the Command name field and "create --use" in Additional arguments for the command. TeamCity will combine these fields into a single docker buildx create --use command.

  4. Repeat steps 1~3 to for each new command you want to execute. For example, you may want to add additional nodes (docker buildx create --append --name mybuild <context_name>) or call docker buildx build <path> --platform linux/amd64,linux/arm64 to start building and image.

Last modified: 12 June 2024