Bitbucket Cloud Pipelines - Set up runners for Windows as a windows service

Summary

One can launch the Windows runner by using a PowerShell script command. An example of such a command is:

Administrators who execute the PowerShell runner launch script command may encounter issues, such as runners going offline when the server is rebooted and requiring re-login during certain events, such as mandated security patch updates or other similar occurrences. 

The pipeline builds will not be triggered due to the unavailability of Windows runners, which are offline.

Solution

Microsoft provides an option called Windows service to enable background tasks and long-running applications to run continuously and independently of user interaction. These applications are designed to start automatically when the operating system boots up and run in the background without any user interface.

The runners' script is not packaged to run as a Windows service, but we have opened a feature request BCLOUD-21928 - Support Pipelines Windows Runners as a service to implement this functionality. However, there are third-party solutions available to run the runners launch script as a Windows OS service.

A third-party WinSW wrapper can be used to run the runner as a Windows service, which ensures that logging off will not impact the runner's status. The wrapper can be downloaded from the repository.

Detailed steps to set up the runners as Windows Service using WinSW.exe wrapper

1. Download the WinSW.exe wrapper from the repo to the runner folder and rename it as runner.exe. For example, "C:\Users\your_user_name\atlassian_runners\runner.exe".

2. Create a configuration file by saving the content of the XML file as runner.xml. The runner.xml file should contain the following configuration:

   1. 1 2 3 4 5 6 7 8 9 10 <service>         <id>BitbucketRunnerWrapper</id>        <name>Bitbucket Runner Wrapper (powered by WinSW)</name>         <description>Wrapper for JAVA based Bitbucket Runner</description>       <executable>java</executable>         <arguments>-jar -Dbitbucket.pipelines.runner.account.uuid={xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx} -Dbitbucket.pipelines.runner.repository.uuid={xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx} -Dbitbucket.pipelines.runner.uuid={xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx} -Dbitbucket.pipelines.runner.environment=PRODUCTION -Dbitbucket.pipelines.runner.oauth.client.id=xxxxxxxxxxxxxx -Dbitbucket.pipelines.runner.oauth.client.secret=xxxxxxxxxxxxxxx -Dbitbucket.pipelines.runner.directory.working=..\temp -Dbitbucket.pipelines.runner.runtime=windows-powershell -Dbitbucket.pipelines.runner.scheduled.state.update.initial.delay.seconds=0 -Dbitbucket.pipelines.runner.scheduled.state.update.period.seconds=30 -Dbitbucket.pipelines.runner.cleanup.previous.folders=false -Dfile.encoding=UTF-8 -Dsun.jnu.encoding=UTF-8 ./bin/runner.jar</arguments>       <log mode="roll"></log>       <logpath>%BASE%\logs</logpath>       <stopparentprocessfirst>true</stopparentprocessfirst> </service> 

   2. Note:

      Make sure to note down the following variable values while creating the new runner:

      • Dbitbucket.pipelines.runner.account.uuid

      • Dbitbucket.pipelines.runner.repository.uuid

      • Dbitbucket.pipelines.runner.uuid

      • Dbitbucket.pipelines.runner.oauth.client.id

      • Dbitbucket.pipelines.runner.oauth.client.secret

      The above arguments are required for repository-based runners. In the case of a workspace based runner, the "Dbitbucket.pipelines.runner.repository.uuid" argument is not required; you would only pass the following.

      • Dbitbucket.pipelines.runner.account.uuid

      • Dbitbucket.pipelines.runner.uuid

      • Dbitbucket.pipelines.runner.oauth.client.id

      • Dbitbucket.pipelines.runner.oauth.client.secret

3. The runner folder structure "C:\Users\your_user_name\atlassian_runners" should look like this:

   1. 1 2 3 4 5 6 7 8 Mode LastWriteTime Length Name ---- ------------- ------ ---- d----- 4/10/2023 8:10 AM bin d----- 4/10/2023 8:21 AM logs d----- 4/10/2023 8:10 AM target -a---- 4/5/2023 2:53 AM 3083 README.md -a---- 4/10/2023 8:12 AM 18243033 runner.exe -a---- 4/10/2023 8:20 AM 1244 runner.xml

4. Run the following command to install the runner as a Windows service.

   1. 1 .\runner.exe install runner.xml

5. Go to 'windows services' and start the "BitbucketRunnerWrapper" service.

   1. WinSW wrapper is a third-party developed tool. Please refer to their tool page for tool maintenance, support, warranty, and licensing information.