Setup Linux Shell runners as a service

Summary

Linux shell self-hosted runners provide the ability to run Bitbucket Pipelines builds in your own infrastructure, directly in a shell session, without docker.

Once a new runner is created in the UI, a command will be provided to download and extract the runner to the host machine, and a start script command with all the required variables for the runner to be executed.

An example of the start script command: 

./start.sh --accountUuid {<account id>} --repositoryUuid {<repository id>} --runnerUuid {<runner id>} --OAuthClientId <OAuthClient id> --OAuthClientSecret <OAuthClient secret> --runtime linux-shell --workingDirectory ../temp

After the start command is executed, the runner will go online and start listening to events coming from Bitbucket Pipelines. 

However, there are some situations that can cause the runner script to stop and make the runner go offline, such as : 

• the host machine was rebooted (to install updates, for example)

• user session was terminated

• runner was started over an SSH session into the host machine, and the SSH connection was closed.

This will cause pipeline steps that are configured to use runners to not be executed because the runners are stopped and offline.

This article provides instructions on how to configure a Linux Shell runner to run as a service in a Linux-based system using systemd. Systemd service will run in the background without requiring any user interaction and/or an active SSH session. 

The service will also be automatically started when the operating system boots up, meaning the runner will be put online automatically after a system reboot. 

Environment

Linux Shell self-hosted runners in Bitbucket Pipelines

Solution

Systemd isa system and service manager for Linux that can be used to configure programs and scripts to run in the background as a service. Systemd can be used to start the Linux shell runner as a service, making sure that runners are not stopped after logging off or closing the SSH session to the host machine, while also automatically starting the runners on system boot. 

Following are detailed steps on how to configure a Linux shell runner as a service in systemd :

1. Open a terminal session in the runner's host and create a system unit file. In this example the .service file will be named bitbucketrunner.service. This is the name used to reference this service when executing systemd commands.

   1 sudo nano /lib/systemd/system/bitbucketrunner.service 

2. Add the following content to the file : [Unit] Description=Bitbucket Runner Service [Service] WorkingDirectory=/home/ubuntu/atlassian-bitbucket-pipelines-runner/bin/ ExecStart=/home/ubuntu/atlassian-bitbucket-pipelines-runner/bin/start.sh --accountUuid {REDACTED} --repositoryUuid {REDACTED} --runnerUuid {REDACTED} --OAuthClientId REDACTED --OAuthClientSecret REDACTED --runtime linux-shell --workingDirectory ../temp [Install] WantedBy=multi-user.target

   where :

   • WorkingDirectory: the absolute path to the bin folder inside the directory where you extracted the runner in the host.

   • ExecStart: the runner start.sh script command received when the runner was created in the UI. Please note the path to the script must be an absolute path (start from /), as systemd does not support relative paths (like home directory ~).

3. Reload systemd to read the new service created :

   1 sudo systemctl daemon-reload

   Whenever any changes are made to the .service file, reload the daemon for the changes to take effect.

4. Enable the service to start on the system boot

   1 sudo systemctl enable bitbucketrunner.service

5. Start the service

   1 sudo systemctl start bitbucketrunner.service

6. Verify if the runner started successfully by checking the status of the service

   1 sudo systemctl status bitbucketrunner.service 

   If the service status reports that the runner started successfully (service log shows the runner is online), you can check the runner state in Bitbucket UI as it should be showing as online as well, meaning it's ready to run new pipelines.