Cache, service container, and export pipelines 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

Bitbucket Pipelines supports caching build dependencies and directories, enabling 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), with the cache name as the name and values being either of:

  • A string representing the file or directory path (allows glob patterns)

  • A node containing the cache key and path options

Allowed parent propertiesdefinitions

Allowed child properties — Either:

  • If you are providing a string representing a file or directory path: None

  • If you are using the key and path options: A cache name (nested under caches)

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"'

Example — using the caches option to create a custom dependency cache for a Ruby project with file checksum-based hashing

The key files option is used to specify files to monitor for changes. The cache specified by the path will be versioned based on changes to the key files.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 definitions: caches: my-bundler-cache: key: files: - Gemfile.lock - "**/*.gemspec" # glob patterns are supported for cache key files path: 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"'

Key

The caches key option defines the criteria for determining when to create a new version of the cache. The cache key used for versioning is based on the hashes of the files defined.

Propertykey

Required — No

Data type — Block of files

Allowed parent properties — A cache name (nested under caches)

Allowed child propertiesfiles

Example — using the caches key option to create a custom dependency cache for a Ruby project with file checksum-based hashing

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 definitions: caches: my-bundler-cache: key: files: - Gemfile.lock - "**/*.gemspec" # glob patterns are supported for cache key files path: 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"'
Key files

The caches key files property lists the files in the repository to monitor for changes. A new version of the cache will be created when the hashes of one or more of the files change.

Propertyfiles

Required — Yes

Data type — List of Strings matching file names (allows glob patterns)

Allowed parent propertieskey

Example — using the caches key files option to create a custom dependency cache for a Ruby project with file checksum-based hashing

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 definitions: caches: my-bundler-cache: key: files: - Gemfile.lock - "**/*.gemspec" # glob patterns are supported for cache key files path: 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"'

Path

The caches path option defines the path to be cached. This can be outside the source repository.

Propertypath

Required — No

Data type — User-defined file path as String (allows glob patterns)

Allowed parent properties — A cache name (nested under caches)

Example — using the caches path option to create a custom dependency cache for a Ruby project with file checksum-based hashing

The key files option is used to specify files to monitor for changes. The cache specified by the path will be versioned based on changes to the key files.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 definitions: caches: my-bundler-cache: key: files: - Gemfile.lock - "**/*.gemspec" # glob patterns are supported for cache key files path: 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"

Pipelines - Bitbucket Premium only

All pipelines defined under the pipelines variable will be exported and can be imported by other repositories in the same workspace.

Propertypipelines

Required — No

Data type — Block of new-line separated name-value pairs (YAML spec - Block Mapping), with the pipeline name as the name and values being pipeline

Allowed parent propertiesdefinitions

Allowed child properties — Requires one or more of the step, stage, or parallel properties.

Example — exported pipeline with name export-pipeline and have one step defined:

1 2 3 4 5 6 7 8 9 10 export: true definitions: caches: services: pipelines: export-pipeline: - step: script: - echo hello

Still need help?

The Atlassian Community is here for you.