Windows Runners EAP - Getting Started
Welcome to the Early Access Program (EAP) for self-hosted Windows Runners in Bitbucket Pipelines. With this feature, you will be able to run builds in Pipelines on your own Windows infrastructure. In this guide, we will walk you through the steps to set up and use runners so you can get started right away.
You won’t be charged for the build minutes used by your self-hosted Windows Runners.
Prerequisites
-
OpenJDK 11 is installed
-
Git is installed
-
PowerShell 5.0+ is installed
-
A 64-Bit Windows 10+ or Windows Server 2019+ instance with at least 8GB of RAM as a host for the runner
Below are the sample chocolatey scripts to install all of the prerequisites required:
choco install -y git
choco install -y openjdk11
choco install -y dotnetfx --pre
We recommend installing any other dependencies your Pipelines require in advance to improve build times, for example: nuget, xUnit, nUnit, etc.
Adding a new Windows Runner in Bitbucket Cloud
- Windows Runners can be added at both the repository and workspace level. You can have up to 100 runners per repository. To register a new runner, go to the repository in which you would like to create a runner.
- Select Repository settings from the left navigation sidebar.
-
In the Pipelines section, select Runners.
- You will see a list of all the runners belonging to this repository. This will be empty if you are registering your first runner. To add a new runner, select Add runner.
- In the Runner installation dialog, select System and architecture and choose Windows from the dropdown list. You can also name the new runner and assign labels.
-
Labels allow you to schedule a step on a runner matching certain requirements. For example, you could label runners with ‘dotnet.5’ to target it specifically from build steps that should run on a host with dotnet 5 installed, and then create a separate label, such as ‘env.prod’ for runners that have a special configuration so they can deploy to a production environment.
-
Labels can only contain lowercase, alphanumerical 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.
-
-
Select Next. The next page will have a list of pre-configured PowerShell commands that you will need to run on the host machine where you’re installing your runners. 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 remember or write down the commands, as you will not be able to access it again after the setup is complete.
-
Select Next.
-
Select Finish to complete the setup. Now the new runner is listed as a runner in your repository. It will be in the 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.
Using your Windows runner in the bitbucket-pipelines.yml
To use your runner in Pipelines, add a runs-on parameter with at least a windows label to a step, and it will run on the next available Windows Runner that has all the required labels.
-
If you don’t specify the
windowslabel, our scheduler will assume it is a Linux step and will try to run it as a Linux 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.
pipelines:
custom:
customPipelineWithRunnerStep:
- step:
name: Step 1
runs-on:
- 'self.hosted'
- 'windows'
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: Given that yaml file can become easily confused by characters used in PowerShell, such as escape characters, delimiters and quotes, it is always better to use folded style for your PowerShell script commands.
Using your runner
Warning: Currently we only support running one runner per machine.
- Download the zip file provided in Step 6 above.
- Unzip the zip file to the desired directory, for example: C:\Users\your_user_name\atlassian_runners
- Open PowerShell as an administrator, go to the bin directory under your Runner folder, run the command provided in Step 6 above.
- Windows Runners is using PowerShell and will run directly in your instance which means it is not a clean build environment for every step, and any side effects generated by the step (i.e., installing any applications, starting a db service, or editing a file outside of the build directory) would potentially affect the next step to be run. Because of this, the runner would only make it is best effort to keep the build directory empty. It is your responsibility to make sure the script you run in your step won’t have major impact on other steps.
Limitations during the EAP
Shared build environment
The Windows Runner uses PowerShell to execute the step scripts, and the host machine will be shared by multiple steps that schedule onto the runner. If you install/change something globally in your step, such as installing a new library, then this change will affect the next step run on the host machine.
Unsupported features
Note: At the moment, self-hosted Windows Runners does not support all features provided when running Pipelines on Atlassian’s infrastructure. The following features are not yet supported:
- Test reports: (https://support.atlassian.com/bitbucket-cloud/docs/test-reporting-in-pipelines/)
- Caches: (https://support.atlassian.com/bitbucket-cloud/docs/cache-dependencies/)
- Artifacts: (https://support.atlassian.com/bitbucket-cloud/docs/use-artifacts-in-steps/)
- SSH keys: (https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/)
- Git-LFS: (https://bitbucket.org/blog/git-lfs-now-available-bitbucket-pipelines - Can't find link)
- Conditional steps: (https://support.atlassian.com/bitbucket-cloud/docs/configure-bitbucket-pipelinesyml/#condition)
The following features won't be support by self-hosted Windows Runners:
- Pipes: (https://support.atlassian.com/bitbucket-cloud/docs/what-are-pipes/)
- Custom build images on AWS ECR
- Service containers: (https://support.atlassian.com/bitbucket-cloud/docs/databases-and-service-containers/)
- Step size: Given that Windows Runners is run directly on your Windows instance, we don’t put any restriction for memory usage.
As we continue to work on the known issues and implement new features, check out the Bitbucket Cloud roadmap to see what’s coming down the pipes.
Known Issues
The following are known issues for current Windows Runners which we are plan to fix before our beta release:
- git-credential-manager-core: If you install
git-credential-manager-corevia chocolatey and don't have the .NetFramework installed, pipelines steps will hang during "git clone"with the following modal:
Solution: you need to install .NetFramework on the host machine. Here is a quick chocolatey command to do so: "choco install -y dotnetfx --pre." - Orphaned child processes: At the end of a step, the runner will attempt to kill any child processes that are launched during the step. This is a best effort cleanup, and there is a possibility that child processes that became orphaned during the step have not been stopped. Any orphaned child processes that have not been stopped will cause an error and the runner will not be able to finish the step successfully. Below is the step error message that will display:
Solution: Manually stop any orphaned child processes and restart the runner. - Stopping steps: Stopping a step is a work-in-progress at the moment. Although you can stop the step via the UI, there are still some known issues related to this feature:
- Slow response for stop step: It could take up to 30s for the runner to respond after you click "Stop" button in the UI.
- Gracefully shutdown the runner via ctrl+c or ctrl+break: Currently, ctrl+c will kill the runner process directly, but it won’t kill any of the child processes, and it will not clean up the build folder generated by the previous runner process. So you need to make sure to clean up any of the child processes generated by the step, as well as the build folder.
Leaving Feedback
We're very interested in any comments you may have around your experience with self-hosted Windows Runners! Please leave your feedback in this community group.
Need Help?
For further assistance on using the self-hosted Windows Runner:
-
Post your question in this community group.
Was this helpful?
Thanks!
lliang2
5 comments