Container Wrapper
The Container Wrapper extension allows running a build step inside the specified Docker/Podman image. Images are pulled via docker pull
or podman pull
commands, depending on which container manager is installed on the agent that runs the build.
TeamCity can pull containers anonymously (if images are publicly available) or after logging into a registry (for private registries or to avoid DockerHub penalties for anonymous downloads). If you need TeamCity to authorize to a registry before pulling an image, configure the Docker Registry Connections build feature, as follows:
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.
In your build configuration settings, configure the Docker Registry Connections build feature using the connections created in the previous step.
The extension is available for the following build steps:
Container Settings
In the Container Settings section of the build step settings, you can specify an image which will be used to run the build step. All options apart from the image name are initially hidden, and show up only after you specify this name.
- Run step within container
The image name as stated in DockerHub or other registry. TeamCity will start a container from the specified image and will try to run the required build step within this container. For example, `ruby:2.4` will run the build step within the Ruby container, version 2.4.
If an agent that runs the build has Podman installed instead of Docker, use either full image names (for example,
docker.io/library/alpine:latest
instead ofalpine:latest
), or ensure the registry domain is specified in the registries.conf file on your build agent machine. See also: How to manage Linux container registries.- Image platform
Select <Any> (default), Linux, or Windows. Note that Windows images are not supported by Podman.
- Force pull on each run
If enabled, the image will be pulled from the repository via
docker/podman pull <imageName>
before thedocker/podman run
command is sent.- Additional run arguments
Allows specifying additional options for the
docker/podman run
command. The default argument is--rm
, but you can provide more. For example, add a custom volume mapping.
How Container Wrapper Works
TeamCity does the following to launch build steps in a container:
Wraps the contents of a build step in a shell script
Starts a container via
docker/podman run
Executes the shell script in this container via
docker/podman exec
To view the details about the started process, text of the script, and so on, check the build log in Verbose mode.
The Container Wrapper maps paths to the build checkout directory and other agent directories like buildAgent/work, so that all these directories have the same location on a build agent and inside a wrapper.
If the process environment contains the TEAMCITY_DOCKER_NETWORK
environment variable set by the previous Docker Compose build step, this network is passed to the started docker run
command with the --network
switch.
Restoring File Ownership on Linux
Build agents that use Docker execute the chown
command at the end of each step running inside a container to restore the buildAgent
user's permissions to access the checkout directory. This action prevents potential issues related to build agents being unable to remove no longer needed container files that were created with the root
ownership. Agents using Podman do not perform this step.
By default, a TeamCity agent uses the busybox
image from Docker Hub to run the chown
command. You can specify an alternative image name with the teamcity.internal.docker.busybox
parameter, either in the buildAgent.properties
file or in the build configuration parameters.
Environment Variables Handling
TeamCity passes environment variables from the build configuration into the Docker or Podman process, but it does not pass environment variables from the build agent, as they may not be relevant to the container environment. The list of the passed environment variables can be seen in the Verbose mode in the build log.
Setting Image Entrypoint
If a Docker image does not define an ENTRYPOINT
, you can use still run a container with an ENTRYPOINT
from the command line:
Add a Command Line build step.
Set the Run mode to Executable with parameters.
In the Command executable field, specify the full path to the
ENTRYPOINT
in the target container.In Docker Settings, specify the name of the container.
TeamCity will start the specified Docker image with the defined ENTRYPOINT
.
Setting Container User
If your step creates or accesses files or folders on local storage, ensure these actions are performed under the correct user with sufficient permissions. To do this, add --user=<value>
to Additional run arguments of the runner.
The host UID can be retrieved via the env.UID
parameter (--user=%env.UID%
).