About Docker containers on Bitrise
Container support enables the use of any Docker container image as an execution environment for a group of Steps within a Workflow. It also enables running background services : this can be used, for example, to run advanced testing scenarios.
Use any Docker image as the execution environment for your Steps or as a background service: spin up a database, HTTP server, or any dependency your tests need.
Using containers comes with several potential benefits:
-
Full control over your build environment. Install any tool, any version, without waiting on Bitrise to support it.
-
Dependencies live in the image. This reduces build times and complexity. No need to install them during the build itself. This reduces build times and complexity.
-
You can use the same environment that you use locally to test and build the app.
There are two types of containers supported on Bitrise:
-
Execution containers: You can run Steps or Step bundles within execution containers. This provides an easy, clean and reliable way to provision a build environment.
-
Service containers: Define service containers and refer to them in Steps or Step bundles to run services in the background while running a Step or Step bundle. Examples of services might include an HTTP server, a database, or any other type of executable program that you wish to run in a distributed environment.
Linux only
This is a Linux-only feature. macOS-based environments are not supported.
Container nesting rules
Steps and Step bundles both support their own container configuration. This creates a natural hierarchy: a step can define containers that differ from its parent bundle, and bundles can be nested within other bundles — each level can override or extend what came before.
Two rules govern how configurations at different levels combine:
-
Execution containers follow closest-wins inheritance. Each Step uses the execution container defined nearest to it in the hierarchy—its own definition takes priority, then its parent bundle's, then its grandparent's. Only one execution container is active per Step.
-
Service containers accumulate additively. A Step inherits service containers from every level of its ancestry, not just the nearest one. The deeper the nesting, the more service containers a Step may have.
Docker authentication credentials
We recommend logging in with your Docker credentials when using containers. To do so, you need to provide Docker credentials when setting up containers:
-
Registry server: It should be a fully qualified registry server URL. This is optional if the server is already part of the image reference.
-
Username.
-
Password.
These credentials must be stored as Secrets. They are used when running the docker login command during container setup.
Container resource options
The docker container create (or shorthand: docker create) command creates a new container from the specified image, without starting it. In your container configuration on Bitrise, you can specify additional options for the command. It shares most of its
options with the docker run command.
Bitrise supports most options for container creation. The only exceptions are:
-
--network -
--volume (-v) -
--entrypoint
For all available options, check out docker container create.