Step execution containers

Step execution containers can be defined for any Bitrise project. You define the container in the top level of the configuration file and then refer to it in a Step or a Step bundle. The Step or the Step bundle will run in the referred execution container. Within the same Workflow or Pipeline, you can run different Steps and Step bundles in different execution containers.

Important

Containers apply to individual Steps and Step bundles, not to entire Workflows or Pipelines.

To define the execution container, you need to set the following:

The ID of the container. It will be used to reference this container.
The type of the container: execution.
The name and version of the Docker image you want to use.

Getting images

You can use any public Docker image from Docker Hub.

After the containers are defined, you can refer to them in a Step or Step bundle which will then run in the referred container during your build.

Defining an execution container

Use the container property to define an execution container. You can define them either on the Workflow Editor or directly in your configuration YAML file.

When you have at least one execution container defined, you can run Steps and Step bundles in them: Running an execution container.

Workflow Editor

Configuration YAML

Log in to Bitrise and select Bitrise CI on the left, then select your project.
Click the Workflows button on the main page.
On the left, select Containers.
Go to the Execution containers tab and then click Add container.
Set the required properties for the container. They are:
- Unique ID: This ID is used to refer to the container in your configuration YAML file.
- Image: The name and version of the Docker image. You can use any image found on Docker Hub or you can use other registries.
  
  For a Docker Hub image, use the [name]:[version] format. For other registries, use [registry server]/[owner]/[name]:[version].
Optionally, add port mappings in the Ports field in the [HostPort01]:[ContainerPort01] format.

Read more about port publishing and port mapping in Docker's official documentation.
Click Show more options to access Docker authentication credentials, Environment Variables for your container, and Docker create options.
Optionally, set up your Docker credentials.

The credentials are used for the docker login command. You can set up:
- 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.
Tip

You must use secrets to pass your Docker credentials to your configuration.
Optionally, add options in the Docker create options field.

These are Docker container resource options: parameters that will be passed to the docker container create command.

For a list of all available options, see the Docker documentation.
When done, click Create container.

Add the containers property to the top level of your configuration YAML.

YAML syntax reference

For detailed YAML syntax reference, see Docker container properties.
Set an ID for your container.

It must be unique within the configuration. The ID is used to refer to the container in Steps or Step bundles.
```
containers:
  node-18:
```
Set the required properties for the container. They are:
- The name and version of the Docker image, in a name:version format. You can use any image found on Docker Hub.
- The container type: execution.
```
containers:
  node-21:
    type: execution
    image: node:21.6
  node-18: 
    type: execution
    image: node:18
```
Optionally, set up a port mapping in the [HostPort01]:[ContainerPort01] format.

Read more about port publishing and port mapping in Docker's official documentation.
```
containers:
  node-21:
    type: execution
    image: node:21.6
    ports: 
    - 3000:3000
```
Optionally, set up your Docker credentials.

The credentials are used for the docker login command. You can set up:
- A server: It should be a fully qualified registry server URL. This is optional if the server is already part of the image reference.
- A username.
- A password.
Tip

We recommend using secrets to pass your Docker credentials to your configuration.
```
containers:
  node-21:
    type: execution
    image: node:21.6
    credentials:
      username: $DOCKER_USERNAME
      password: $DOCKER_PASSWORD
      server: us-central1-docker.pkg.dev
```
Optionally, use the options property to configure additional Docker container resource options: parameters that will be passed to the docker container create command.

In this example, the service is configured to have healthchecks.
```
containers:
  node-21:
    type: execution
    image: node:21.6
    options: >-
      --health-cmd pg_isready
      --health-interval 10s
      --health-timeout 5s
      --health-retries 5
```
For a list of all available options, see the Docker documentation.

Running an execution container

You can run a Step or a Step bundle in an execution container. To do so, refer to a defined container in the Step or Step bundle configuration.

You can:

Refer to the container in a Step or a Step bundle within a Workflow. When that Workflow runs, the Step or the Step bundle will run within that container.
Refer to the container in the Step bundle definition. When that Step bundle is added to the Workflow, it will run within that container by default, unless you override it within the Workflow.

This guide covers both options.

Container nesting

You can define containers on different levels: Steps and Step bundles both support their own container configuration. This creates a hierarchy between different levels. For the principles governing the hierarchy, see Container nesting rules.

Workflow Editor

Configuration YAML

Open the Workflow Editor.
Select a Step or a Step bundle in a Workflow.

Alternatively, you can select Step Bundles on the left navigation menu and set a container in the Step bundle definition. The subsequent steps in the procedure are the same.

Bundle definition override

By default, if you set a container in the Step bundle definition the Step bundle will run in the referred container in any Workflow you add it to.

However, if you set a container in a Step bundle instance (the Step bundle within a Workflow), it overrides the container set in the Step bundle definition.
Select Containers.
Under Execution Container, click Add container and select a container from the menu.
If your container is already running but you want to run a clean instance of the container, check the Recreate container option.

By default, the Step or Step bundle will use an already running container if there is one.

Open your configuration YAML file and find your Workflow.
Add the execution_container property with a container name to the Step or Step bundle you need. You can only refer to a single execution container.

Add an execution container to a Step within a Workflow format:
```
workflows:
  ci:
    steps:
    - git-clone: {}
    - script:
        execution_container: node-21
```
Add an execution container to a Step bundle within a Workflow:
```
workflows:
  ci:
    steps:
    - git-clone: {}
    - script: {}
    - bundle::test-bundle-id:
        execution_container: node-21
```
Add the execution container to a Step bundle definition:
```
step_bundles:
  test-bundle-id:
    steps:
    - git-clone@8: {}
    - restore-cache@2: {}
    execution_container: test-container
```
Bundle definition override

By default, the Step bundle will run in the referred container in any Workflow you add it to. However, if you set a container for the Step bundle within a Workflow, it overrides the container set in the Step bundle definition.
If your container is already running but you want to run a clean instance of the container, set the recreate property to true .

By default, the Step or Step bundle will use an already running container if there is one. Use the property to change the default behavior.
```
workflows:
  ci:
    steps:
    - git-clone: {}
    - script:
        execution_container:
        node:21
    - bundle::test-bundle-id:
        execution_container:
          node-21:
            recreate: true
```

In this section:

Step execution containers

Important

Getting images

File sharing across containers