Cache and service container definitions

The definitions option allows you to define custom dependency caches and service containers (including database services) for Bitbucket Pipelines.

Caches and Services for pipelines

The following options can be used for defining caches and service containers:

Definitions

The definitions property is used to define resources used elsewhere in your pipeline configuration. Resources can include:

Propertydefinitions

Required — No

Data type — Block (YAML spec - Block Mapping)

Allowed parent properties — The YAML root (definitions can only be a top-level property)

Allowed child properties — Requires one or more of the caches and services properties.

Example — using definitions to add a custom cache and a database service to a pipeline step

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 definitions: caches: bundler-packages: vendor/bundle services: my-mariadb: image: mariadb:latest variables: MARIADB_USER: $MY_MARIADB_USER MARIADB_PASSWORD: $MY_MARIADB_PASSWORD MARIADB_ROOT_PASSWORD: $MARIADB_ADMIN_PASSWORD pipelines: default: - step: name: Hello world example services: - my-mariadb caches: - bundler-packages script: - ruby -e 'print "Hello, World\n"'

Example — using YAML anchors to create reusable steps

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 definitions: steps: - step: &build-test name: Build and test script: - mvn package artifacts: - target/** pipelines: branches: develop: - step: *build-test main: - step: *build-test

Caches

The caches option is used to cache external build dependencies and directories, such as 3rd-party libraries, between builds providing faster builds, and reducing the number of consumed build minutes.

There are several predefined caches available. For a complete list of predefined caches, see Caches — Predefined caches.

For information on using the caches option, see Caches.

Propertycaches

Required — No

Data type — Block of new-line separated name-value pairs (YAML spec - Block Mapping)

Allowed parent propertiesdefinitions

Example — using the caches option to create a custom dependency cache for a Ruby project

1 2 3 4 5 6 7 8 9 10 11 12 definitions: caches: my-bundler-cache: vendor/bundle pipelines: default: - step: caches: - my-bundler-cache # Cache is defined above in the definitions section script: - bundle install --path vendor/bundle - ruby -e 'print "Hello, World\n"'

Services

Bitbucket Pipelines can create separate Docker containers for services, which results in faster builds, and easy service editing. For details on creating services see Databases and service containers. This services option is used to define the service, allowing it to be used in a pipeline step.

Secrets and login credentials should be stored as user-defined pipeline variables to avoid being leaked. For details, see Variables and secrets — User-defined variables.

Propertyservices

Required — No

Data type — Block (YAML spec - Block Mapping)

Allowed parent propertiesdefinitions

Allowed child properties — A user-defined string. This string will be the name of the service.

Example — using a service definition to add a database service to a build step

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 definitions: services: my-service-name: image: mariadb:latest variables: MARIADB_USER: $MY_MARIADB_USER MARIADB_PASSWORD: $MY_MARIADB_PASSWORD MARIADB_ROOT_PASSWORD: $MARIADB_ADMIN_PASSWORD pipelines: default: - step: name: Hello world example services: - my-service-name script: - echo "Hello, World"

Image

For details on the image options, including using the image options for services, see Docker image options.

Memory

The memory option is used to limit the memory (in megabytes) available to a service container. 4096MB (or 8192 MB for size: 2x builds) is the total amount of memory that can be allocated to a step, including scripts and pipeline services. For example: if a service requires 3072MB, then only 1024MB is available to run steps using that service. For details on service container memory limits see Databases and Service Containers — Service memory limits.

Propertymemory

Required — No

Data type — Integer

Allowed values — From 128 to 4096MB (or 256 to 8192 for size: 2x builds).

Default value1024

Allowed parent properties — A service name (nested under services)

Example — using the memory option to restrict a service container to 512MB of memory
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 definitions: services: my-postgresql-db: image: postgres:latest memory: 512 variables: POSTGRES_PASSWORD: $MY_POSTGRES_PASSWORD pipelines: default: - step: name: Hello world example services: - my-postgresql-db script: - echo "Hello, World"

Type

Only available for self-hosted pipeline runners.

The type option is used to specify Docker services containers (running Docker-in-Docker) for:

  • Docker-in-Docker service containers with a custom name.

  • Multiple Docker-in-Docker service containers.

For details on:

Propertytype

Required — No

Data type — String

Allowed valuesdocker

Allowed parent properties — A service name (nested under services)

Example — using the type option to add multiple Docker-in-Docker services
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 definitions: services: docker: # Default Docker-in-Docker service image: docker:dind my-docker-in-docker-name: image: docker:latest type: docker docker-custom: type: docker image: docker:dind pipelines: default: - step: script: - docker version - docker run hello-world services: - docker - step: script: - docker version - docker run hello-world services: - my-docker-in-docker-name - step: script: - docker version - docker run hello-world services: - docker-custom

Variables

The services variables option is used to pass environmental variables to service containers, typically used to configure the service. For details on creating services see Databases and service containers.

Secrets and login credentials should be stored as user-defined pipeline variables to avoid being leaked. For details, see Variables and secrets — User-defined variables.

Propertyvariables

Required — No

Data type — Block of new-line separated name-value pairs (YAML spec - Block Mapping)

Allowed parent properties — A service name (nested under services)

Example — using variables to set up a MariaDB service container
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 definitions: services: my-service-name: image: mariadb:latest # Official MariaDB image from DockerHub: https://hub.docker.com/_/mariadb/ variables: MARIADB_USER: $MY_MARIADB_USER MARIADB_PASSWORD: $MY_MARIADB_PASSWORD MARIADB_ROOT_PASSWORD: $MARIADB_ADMIN_PASSWORD pipelines: default: - step: name: Hello world example services: - my-service-name script: - echo "Hello, World"
Example — using variables to set up a PostgreSQL service container
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 definitions: services: my-postgresql-db: image: postgres:latest # Official PostgreSQL image from DockerHub: https://hub.docker.com/_/postgres variables: POSTGRES_PASSWORD: $MY_POSTGRES_PASSWORD pipelines: default: - step: name: Hello world example services: - my-postgresql-db script: - echo "Hello, World"

Additional Help