Get started with Bitbucket Cloud
New to Bitbucket Cloud? Check out our get started guides for new users.
The definitions option allows you to define custom dependency caches and service containers (including database services) for Bitbucket Pipelines.
The following options can be used for defining caches and service containers:
The definitions property is used to define resources used elsewhere in your pipeline configuration. Resources can include:
Services that run in separate Docker containers – see Databases and service containers.
Caches – see Caches.
YAML anchors - a way to define a chunk of your YAML for easy re-use - see YAML anchors.
Property — definitions
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.
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"'
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
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.
Property — caches
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 properties — definitions
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)
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"'
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"'
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.
Property — key
Required — No
Data type — Block of files
Allowed parent properties — A cache name (nested under caches)
Allowed child properties — 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"'
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.
Property — files
Required — Yes
Data type — List of Strings matching file names (allows glob patterns)
Allowed parent properties — key
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"'
The caches path option defines the path to be cached. This can be outside the source repository.
Property — path
Required — No
Data type — User-defined file path as String (allows glob patterns)
Allowed parent properties — A cache name (nested under caches)
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"'
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.
Property — services
Required — No
Data type — Block (YAML spec - Block Mapping)
Allowed parent properties — definitions
Allowed child properties — A user-defined string. This string will be the name of the service.
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"
For details on the image options, including using the image options for services, see Docker image options.
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.
Property — memory
Required — No
Data type — Integer
Allowed values — From 128 to 4096MB (or 256 to 8192 for size: 2x builds).
Default value — 1024
Allowed parent properties — A service name (nested under services)
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"
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:
Adding custom Docker-in-Docker services, see Configure your runner in bitbucket-pipelines.yml — Custom docker-in-docker image.
Using a Docker-in-Docker service, see Run Docker commands in Bitbucket Pipelines.
Property — type
Required — No
Data type — String
Allowed values — docker
Allowed parent properties — A service name (nested under 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
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.
Property — variables
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)
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"
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"
All pipelines defined under the pipelines variable will be exported and can be imported by other repositories in the same workspace.
Property — pipelines
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 properties — definitions
Allowed child properties — Requires one or more of the step, stage, or parallel properties.
1
2
3
4
5
6
7
8
9
10
export: true
definitions:
caches:
services:
pipelines:
export-pipeline:
- step:
script:
- echo hello
Was this helpful?