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

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

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

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

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

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

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:

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 info

Docker service with a custom name:

definitions:
  services:
    docker-custom:
      type: docker 
      image: docker:dind

pipelines:
  default:
    - step:
        runs-on: 
          - 'self.hosted'
          - 'my.custom.label'
        services:
          - docker-custom
        script:
          - docker info

Define 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

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

pipelines:
  default:
    - step:
        runs-on: 
          - 'self.hosted'
        clone:
          skip-ssl-verify: true
        script:
          - echo "Use git with a self-signed certificate"

Was this helpful?

It wasn't accurate

It wasn't clear

It wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community