BitBucket Runner/Agent Plan
BitBucket Self-Hosted Runners are a lightweight, powerful tool used to execute jobs in BitBucket Pipelines. They handle tasks defined in pipeline configuration files (YAML format), such as building, testing, and deploying code. Unlike BitBucket's cloud-hosted runners, self-hosted runners allow you to run pipelines on your own infrastructure, providing greater control and customization. The runner fetches code from the BitBucket repository, runs it in your predefined environment, and returns the results to BitBucket. For more information, refer to the official BitBucket Self-Hosted Runners documentation.
Document Overview
This document provides step-by-step instructions for adding a self-hosted runner to a BitBucket repository. Self-hosted runners are used to execute pipelines on machines that you manage, offering greater control and customization compared to BitBucket's cloud-hosted runners.
Adding a Self-Hosted Runner to a 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.
Select MacOS from the System and architecture dropdown menu.
In the Runner installation dialog, add a runner name.
Assign labels to your runner by adding them in the Runner labels field.
Labels can only contain lowercase, alphanumeric characters and dots.
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.
By default, the self.hosted label and the appropriate macos label are added to Runner labels.
Select Next.
For our purposes you will need to save accountUuid, repositoryUuid, runnerUuid, 0AuthCliendId, and 0AuthClientSecrect. Please MAKE SURE YOU SAVE YOUR TOKENS SOMEWHERE LOCALLY. Once the token is generated, you will not be able to access it again unless you have it saved locally.
Select Next and Finish.
Setting Up your Agent on MacinCloud
Log in to the MacinCloud Portal.
From the dashboard, navigate to Agents > Bitbucket Agent.
Once selecting your agent you will see a page similar to this.
Select the agent under your subscription.
Click Actions > Edit Agent and complete the necessary fields:
Account UUID: Enter the Account UUID generated in BitBucket when setting up your runner.
Repository UUID: Enter the Repository UUID generated in BitBucket when setting up your runner.
Runner UUID: Enter the Runner UUID generated in BitBucket when setting up your runner.
OAuth Client ID: Enter the OAuth Client ID generated during the setup of your BitBucket runner.
OAuth Client Secret: Enter the OAuth Client Secret generated during the setup of your BitBucket runner.
Version: The latest release version is preselected, but you may choose previous stable releases if necessary.
Once done, click Update and allow up to 2 minutes for the changes to take effect.
When your agent is successfully configured, you should see the following confirmation.
Verifying Your Runners Connection
To verify that your newly added runner is working, go to the repository where you want to check the runner.
Select Repository settings from the left navigation sidebar.
Under the Pipelines heading on the left sidebar, select Runners.
The online status next to your runner indicates that it has successfully connected, is online, and ready for jobs.
Troubleshooting your Agent
If your agent has not been successfully configured, it will enter an error state. Below are common examples and steps to resolve the issues:
Account UUID is not configured correctly: Please verify that the account UUID has been entered correctly and update the agent accordingly.
Repository UUID is not configured correctly: Please verify that the repository UUID has been entered correctly and update the agent accordingly.
Runner UUID is not configured correctly: Please verify that the runner UUID has been entered correctly and update the agent accordingly
These errors typically occur when the Account UUID, Repository UUID, or Runner UUID are incorrectly entered, preventing your BitBucket agent from connecting to the correct repository. Additionally, if the OAuth Client ID, OAuth Client Secret, or the registration token are incorrectly entered or have expired, the runner will fail to be verified.
Steps to Resolve Account UUID is Not Configured Correctly Error:
Navigate to the runner in the error state and select Actions > Edit Agent.
Verify that the Account UUID is entered correctly and matches the one provided by BitBucket when you created your runner.
If any of the information appears incorrect, please replace it with the correct information and select update.
If all information appears correct, navigate to the runner in the error state and click Actions > Restart.
If restarting the agent does not resolve the issue, please contact support.
Steps to Resolve Repository UUID is Not Configured Correctly Error:
Navigate to the runner in the error state and select Actions > Edit Agent.
Verify that the Repository UUID is entered correctly and matches the one provided by BitBucket when you created your runner.
If any of the information appears incorrect, please replace it with the correct information and select update.
If all information appears correct, navigate to the runner in the error state and click Actions > Restart
If restarting the agent does not resolve the issue, please contact support.
Steps to Resolve Runner UUID is Not Configured Correctly Error:
Navigate to the runner in the error state and select Actions > Edit Agent.
Verify that the Runner UUID is entered correctly and matches the one provided by BitBucket when you created your runner.
If any of the information appears incorrect, please replace it with the correct information and select update.
If all information appears correct, navigate to the runner in the error state and click Actions > Restart.
If restarting the agent does not resolve the issue, please contact support.