Get started with Bitbucket Cloud
New to Bitbucket Cloud? Check out our get started guides for new users.
Configure your runner in bitbucket-pipelines.yml
To use your runner in Pipelines, add a runs-on parameter to a step in the bitbucket-pipelines.yml file. The runner will run on the next available runner that has all the required labels.
If all matching runners are busy, your step will wait until one becomes available again.
If you don’t have any online runners in your repository that match all labels, the step will fail.
bitbucket-pipelines.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
pipelines:
custom:
customPipelineWithRunnerStep:
- step:
name: Step 1
runs-on:
- 'self.hosted'
- 'my.custom.label'
script:
- echo "This step will run on a self hosted runner.";
- step:
name: Step 2
script:
- echo "This step will run on Atlassian's infrastructure as usual.";Using your Linux Shell runner in your build configuration
To use your Linux Shell runner in Pipelines, add a runs-on parameter with at least the linux.shell label to a step, and it will run on the next available Linux Shell Runner that has all the required labels.
Note
If you don’t specify the linux.shell label, our scheduler will assume it is a Linux Docker step and will try to run it as a Linux Docker Runner.
If all matching Linux Shell Runners are busy, your step will be queued until one becomes available again.
If you don't have any online runners in your repository that match all your labels, the step will fail.
bitbucket-pipelines.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
pipelines:
custom:
customPipelineWithRunnerStep:
- step:
name: Step 1
runs-on:
- 'self.hosted'
- 'linux.shell'
- 'customlabel'
script:
- echo 'This step will run on a self-hosted Linux Shell runner.';
- step:
name: Step 2
script:
- echo "This step will run on Atlassian's infrastructure as usual.";Using your Linux Docker ARM runner in your build configuration
To use your Linux Shell runner in Pipelines, add a runs-on parameter with at least the linux.arm64label to a step, and it will run on the next available Linux Docker ARM Runner that has all the required labels.
If using the atlassian/default-image for your steps, you must use atlassian/default-image:4 or above for ARM support.
Note
If you don’t specify the linux.arm64 label, our scheduler will assume it is a Linux Docker step and will try to run it as a Linux Docker Runner.
If all matching Linux ARM Runners are busy, your step will be queued until one becomes available again.
If you don't have any online runners in your repository that match all your labels, the step will fail.
bitbucket-pipelines.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
image: atlassian/default-image:4
pipelines:
custom:
customPipelineWithRunnerStep:
- step:
name: Step 1
runs-on:
- 'self.hosted'
- 'linux.arm64'
- 'customlabel'
script:
- echo 'This step will run on a self-hosted Linux ARM runner.';
- step:
name: Step 2
script:
- echo "This step will run on Atlassian's infrastructure as usual.";Using your Windows runner in your build configuration
To use windows runner in Pipelines, add a runs-on parameter with at least the windows label to a step, and it will run on the next available Windows Runner that has all the required labels.
Note
If you don’t specify the windows label, our scheduler will assume it is a Linux Docker step and will try to run it as a Linux Docker Runner.
If all matching Windows Runners are busy, your step will be queued until one becomes available again.
If you don't have any online runners in your repository that match all your labels, the step will fail.
bitbucket-pipelines.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
pipelines:
custom:
customPipelineWithRunnerStep:
- step:
name: Step 1
runs-on:
- 'self.hosted'
- 'windows'
- 'customlabel'
script:
- >
Write-Host 'This step will run on a self hosted Windows runner.';
- step:
name: Step 2
script:
- echo "This step will run on Atlassian's infrastructure as usual.";Recommendation: The yaml file can run into issues when it includes a PowerShell script that includes special characters, such as escape characters, delimiters and quotes, it is always better to use folded style for your PowerShell script commands.
Using your MacOS runner in your build configuration
To use your MacOS runner in Pipelines, add a runs-on parameter with at least the macos label to a step, and it will run on the next available MacOS Runner that has all the required labels.
Note
If you don’t specify the macos label, our scheduler will assume it is a Linux Docker step and will try to run it as a Linux Docker Runner.
If all matching MacOS Runners are busy, your step will be queued until one becomes available again.
If you don't have any online runners in your repository that match all your labels, the step will fail.
bitbucket-pipelines.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
pipelines:
custom:
customPipelineWithRunnerStep:
- step:
name: Step 1
runs-on:
- 'self.hosted'
- 'macos'
- 'customlabel'
script:
- echo 'This step will run on a self hosted MacOS runner.';
- step:
name: Step 2
script:
- echo "This step will run on Atlassian's infrastructure as usual.";Large step size
A runs-on parameter must contain a self.hosted label.
You can allocate additional memory to a step that runs on a self-hosted runner.
At this time, valid sizes are 1x, 2x, 4x, and 8x. The corresponding memory available is 4GB, 8GB, 16GB, and 32GB.
Example: Increasing memory for a step that runs on a self-hosted runner
1
2
3
4
5
6
7
8
9
pipelines:
default:
- step:
runs-on:
- 'self.hosted'
- 'my.custom.label'
size: 8x
script:
- echo "This step will run on a self hosted runner with 32 GB of memory."Custom docker-in-docker image
The minimum runner version with support for this feature is 1.179.
A runs-on parameter must contain a self.hosted label.
With runners, you have more control over the docker-in-docker daemon. Now you can specify a custom image for the docker service, but it only can be used if the step runs on a self-hosted runner. You can also use a custom name for the docker service - see the example below.
Example: Using a custom docker image for a step that runs on a self-hosted runner
Docker service with the default name:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
definitions:
services:
docker: # can only be used with a self-hosted runner
image: docker:dind
pipelines:
default:
- step:
runs-on:
- 'self.hosted'
- 'my.custom.label'
services:
- docker
script:
- docker infoDocker service with a custom name:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
definitions:
services:
docker-custom:
type: docker
image: docker:dind
pipelines:
default:
- step:
runs-on:
- 'self.hosted'
- 'my.custom.label'
services:
- docker-custom
script:
- docker infoDefine multiple docker services
Add a type parameter with the docker value to your service definition to use multiple docker services. It allows you to use a custom docker image on a self-hosted runner and a default docker service for steps that run in the cloud.
Example: Using multiple 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
definitions:
services:
docker: # default docker service
memory: 512
docker-custom:
type: docker
image: docker:dind
pipelines:
default:
- step:
name: Step 1
runs-on:
- 'self.hosted'
- 'my.custom.label'
services:
- docker-custom
script:
- docker info
- step:
name: Step 2
services:
- docker
script:
- docker info
- echo "This step will use the defult docker service defenition.";Skip SSL on git clone
A runs-on parameter must contain a self.hosted label.
Add a skip-ssl-verify parameter to disable SSL verification during git clone and allow using a self-signed certificate.
Example
1
2
3
4
5
6
7
8
9
pipelines:
default:
- step:
runs-on:
- 'self.hosted'
clone:
skip-ssl-verify: true
script:
- echo "Use git with a self-signed certificate"Was this helpful?