Adding a new runner in Bitbucket

Adding a new repository runner

By adding runners to a repository, you will be able to run builds in Pipelines on your own infrastructure for specific repositories in a workspace. 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.

Add runner empty state user interface

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

runner installation dialog

6. Assign labels to your runner by adding them in the Runner labels field.
a. Labels can only contain lowercase, alphanumerical characters and dots.
b. 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 “env.prod” 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.

Adding a new workspace runner

By using runners within a workspace, you will be able to run builds in Pipelines on your own infrastructure for any repository in the workspace. You can have up to 100 runners per workspace.

  1. To register a new runner, go to the workspace you would like to create a runner for. To select a workspace, select your profile and settings avatar and select a workspace from the Recent Workspaces list or select All workspaces to open a page listing all the workspaces in which you are a member.

  2. Select Settings from the left navigation sidebar.

  3. In the Pipelines section, select Workspace runners.

  4. You will see a list of all the runners belonging to this workspace. This will be empty if you are registering your first runner. To add a new runner, select Add runner.

  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 “env.prod” 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.

 

Last modified on Aug 12, 2021
Cached at 2:40 AM on Sep 25, 2021 |

Additional Help