Service containers for Bitbucket Pipelines

Alpha Feature - this feature is currently under development and only available to Pipelines Alpha users.

The capabilities and configuration of this feature may change as development proceeds. To provide feedback on this feature, please see Pipelines Alpha.

Bitbucket Pipelines allows you to run multiple Docker containers from your build pipeline. You'll want to start additional containers if your pipeline requires additional services when testing and operating your application. These extra services may include datastores, code analytics tools and stub webservices.

You define such additional services (and other resources) in the definitions section of the bitbucket-pipelines.yml file. These services can then be referenced in the configuration of each pipeline that needs them.

When a pipeline runs, services referenced in a step of your bitbucket-pipeline.yml will be scheduled to run with your pipeline step. These services share a network interface with your pipeline step, and bound ports can be accessed via localhost.

Pipelines enforces a maximum of 3 service containers per build step, which is based on the limited memory available for builds in our infrastructure.

Complete example

This example shows both the definition of a service and its use in a pipeline step. A breakdown of how it works is presented below.

pipelines:
  branches:
    master:
      - step:
          image: redis
          script:
            - redis-cli -h localhost ping
          services:
            - redis
            - database
definitions:
  services:
    redis:
      image: redis
    database:
      image: mysql
      environment:
        MYSQL_ROOT_PASSWORD: password

Defining a service

Services are defined in the definitions section of the bitbucket-pipelines.yml file.

For example, the following defines two services: one named redis that uses the library image redis from Docker Hub, and another named database that uses the official Docker Hub MySQL image.

definitions:
  services:
    redis:
      image: redis
     database:
       image: mysql
       environment:
         MYSQL_ROOT_PASSWORD: password


Use a service in a pipeline

Once a service has been defined in the 'definitions' section of the bitbucket-pipelines.yml file, you can reference that service in pipeline steps.

For example, the following causes the redis service to run alongside the step:

pipelines:
  default:
    - step:
        image: node
        script:
          - npm install
          - npm test
        services:
          - redis


Use a private image

You can define a service that has restricted access as follows:

definitions:
  services:
    redis:
      image: 
        name: redis
        username: username@organisation.com
        password: $DOCKER_PASSWORD

For more complete example of using docker images from different registries and different formats, see Using Docker images as build environments

Caveats and limitations

The number of service containers you can run in a build is limited by the available memory for the build:

  •  Maximum of 3 services.
  •  Each service has 1GB memory reserved for it that is taken from the 4GB limit for a pipeline.
Number of services Memory available for your pipeline
1 3 GB
2 2 GB
3 1 GB

Alpha limitations

The following parts of the feature are still under development:

  • Service log collection and UI for displaying logs
  • REST API for accessing services and logs under pipeline results
  • No mechanism to wait for service startup.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport