Set up and use runners for Linux

Runners is currently in beta.

Runners allow you to run builds in Pipelines on your own infrastructure, and you won’t be charged for the build minutes used by your self-hosted runners.


  • a 64-Bit Linux instance with at least 8GB of RAM as a host for the runner. 2x-Steps with additional service may require more.

  • Docker must be installed - Install Docker

Best practice

We strongly recommend disabling swap and configuring vm.swappiness. Having swap enabled can lead to non-deterministic build results in regards to memory and OOMing, meaning that sometimes enough swap is available and a build may pass while other times not enough swap is available and the same build will OOM.

Disable swap in a Linux environment

Below are the steps to disable swap for most Linux distributions. If the following commands aren’t installed, you will have to install them. Consult your distributions documentation to configure swap.

  1. Use the following command to check if swap is enabled:

    1 sudo swapon -sv

    If swap is enabled, you should see output similar to the following:

  2. If swap is enabled, you will have to disable it using the following processes:

    1. Disable any swap suing the following command:

      1 2 NAME TYPE SIZE USED PRIO /dev/sda3 partition 2G 655.2M -1
    2. Open /etc/fstab and remove any swap partitions or files that are configured.

    3. Reboot your machine.

    4. Run the following command again ensuring there is no output:

      1 sudo swapoff -av
    5. If there is output, repeat Step 2, ensuring all swap files are removed from /etc/fstab.

Configure vm.swappiness in a Linux environment

Below are the steps to configure vm.swappiness for most Linux distributions. If the following commands aren’t installed, you will have to install them. Consult your distributions documentation to configure swap.

  1. Use the following command to check the value of vm.swappiness:

    1 sudo sysctl -n vm.swappiness

    If the value is anything other than 1, it means you have some swap behavior still enabled.

  2. If the swappiness value is anything except 1, configure it using the following process:

    1. Open /etc/sysctl.conf and add vm.swappiness = 1 to the file on its own line.

    2. Reboot your machine.

    3. Run the following command ensuring that the output is now 1.

      1 sudo sysctl -n vm.swappiness
    4. If there is an output other than 1, repeat Step 2 and ensure that /etc/sysctl.conf is configured correctly.

Adding a new runner in the Bitbucket UI

At this time, runners can only be added at the repository level. You can have up to 100 runners per repository.

  1. To register a new runner, go to the repository you would like to create a runner for.

  2. Select Repository settings from the left navigation sidebar.

  3. Under the Pipelines heading on the left sidebar, select Runners.

  4. Select Add runner to add a new runner. If you have already registered runners for this repository, you will see a list of all the previously registered runners.

  5. In the Runner installation dialog, add a runner name.

  6. Assign labels to your runner by adding them in the Runner labels field.

    1. Labels can only contain lowercase, alphanumerical characters and dots.

    2. You can have up to 10 custom labels per runner, but you don’t need to add any at all if there is no need to distinguish between runners when scheduling steps.

Labels allow you to schedule a step on a runner matching certain requirements. For example, you could label runners with “os.linux.alpine” to target that runner specifically from build steps that should run on a Linux Alpine host, and label another runner as “” for runners that have a special configuration, so they can deploy to a production environment.

7. Select Next.
8. Copy/paste and run the pre-configured Docker command on your runner host machine. This command automatically downloads and starts the necessary software to run build steps on your host. The token in the provided command will automatically authenticate the host with Bitbucket.

Write down or store the provided command somewhere, as you will not be able to access it again after setup.

9. Select Next.
10. Select Finish to complete the setup. The new runner will now be listed as an available runner in your repository. It will remain in an unregistered state until you run the command you saved in Step 6 on your host machine.

Make sure you run the command and that the state of the runner changes to ‘online’ before you try to use the runner in your Pipelines.

Add a runs-on parameter to 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.


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 with 128 GB of memory."; - step: name: Step 2 script: - echo "This step will run on Atlassian's infrastructure as usual.";

Use your runner in Pipelines

Currently, we only support running one runner per host machine.

  • Use the pre-configured Docker command provided in Step 6 above to run the runner.

    • If this is the first time running the runner, it will pull the image.

    • If you are starting the runner again or to update the runner, always pull the runner manually before using the following command to ensure you are always running the most up-to-date runner.

      1 docker image pull
    • If you encounter the following error, run the ‘docker container rm -f runner’ command below to remove the runner.

      1 2 docker: Error response from daemon: Conflict. The container name "/runner" is already in use by container "c3403236e3af5962ed3a9b8771561bd2021974941cc8a89a40c6c66cecb18f53". You have to remove (or rename) that container to be able to reuse that name. See 'docker run --help'.

      docker container rm -f runner command

      1 docker container rm -f runner

Changing the working directory of your runner

If you want to change the working directory that the runner uses on your host machine, add the following two flags to the docker run command when you start the runner:

1 docker run [all existing parameters] -v /localdirectory:/mydir -e WORKING_DIRECTORY=/mydir

In this command, the first value in -v parameter will be the local directory on your machine that will serve as the working directory. The second value will be the directory inside the runner. It can be anything you like, it just needs to match the value specified in the WORKING_DIRECTORY environment variable.

Last modified on May 7, 2021
Cached at 10:27 PM on Jun 11, 2021 |

Additional Help

Ask the Community