Get started with Bitbucket Cloud
New to Bitbucket Cloud? Check out our get started guides for new users.
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.
To register a new runner, go to the repository you would like to create a runner for.
Select Repository settings from the left navigation sidebar.
Under the Pipelines heading on the left sidebar, select Runners.
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. Select either Linux or Windows from the System and architecture dropdown menu, depending on whether you are creating the self-hosted runner in a Linux or Windows environment.
6. In the Runner installation dialog, add a runner name.
7. 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.
c. By default, the self.hosted label and the appropriate linux, linux.arm64, windows, macos, or linux.shell label are added to Runner labels.
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.
8. Select Next.
9. For Linux (Docker): 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.
For Windows, macOS, and Linux Shell: A list of pre-configured PowerShell or Bash commands that you will need to run on the host machine where you’re installing your runners is provided. It will download, unzip, and start the software necessary to run build steps on your host. The token in the command will automatically authenticate the host with Bitbucket. Note: Make sure you securely save the commands, as the commands only displays once and you will not be able to access it again after the setup is complete.
Write down or store the provided command somewhere, as you will not be able to access it again after setup.
10. Select Next.
11. Select Finish to complete the setup. The new runner will now be listed as an available
runner in your repository. It will be in the unregistered state until you run the command to
start the runner.
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.
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 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.
Select the Settings cog on the top navigation bar.
Select Workspace settings from the Settings dropdown menu.
In the Pipelines section, select Workspace runners.
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.
Select either Linux or Windows from the System and architecture dropdown menu, depending on whether you are creating the self-hosted runner in a Linux or Windows environment.
In the Runner installation dialog, add a runner name.
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.
c. By default, the self.hosted and linux or windows labels are added to Runner
labels.
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.
8. Select Next.
9. For Linux: 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.
For Windows: A list of pre-configured PowerShell commands that you will need to run on the host machine where you’re installing your runners is provided. It will download, unzip, and start the software necessary to run build steps on your host. The token in the command will automatically authenticate the host with Bitbucket. Note: Make sure you securely save the commands, as the commands only displays once and you will not be able to access it again after the setup is complete.
Write down or store the provided command somewhere, as you will not be able to access it again after setup.
10. Select Next.
11. 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.
Was this helpful?