Bitbucket Pipelines Runner Setup Guide (Ubuntu & Amazon Linux 2)

Self-hosted Bitbucket Pipelines Runner allows you to run builds on your own infrastructure. This guide covers installation, registration, and setup as a systemd service.

1. System Requirements

• OS: Ubuntu 20.04+ / Amazon Linux 2
• Packages: git, curl, unzip, wget, java
• User with sudo privileges
• Open outbound HTTPS (443) access to Atlassian domains

Bitbucket is a Git solution for teams using Jira.

2. Install Java (required for runner)

Ubuntu

sudo apt update -y
sudo apt install -y openjdk-11-jdk
java -version

Amazon Linux 2

sudo yum update -y
sudo amazon-linux-extras enable corretto11
sudo yum install -y java-11-amazon-corretto
java -version

3. Download the Bitbucket Runner

Switch to the runner’s home directory:

cd /home/runner
curl -L https://product-downloads.atlassian.com/software/bitbucket/pipelines/atlassian-bitbucket-pipelines-runner-1.501.tar.gz -o runner.tar.gz
tar -xvzf runner.tar.gz
cd atlassian-bitbucket-pipelines-runner/bin

Check Atlassian docs for the latest runner version.

4. Register the Runner

Run interactive setup:

./start.sh --setup

• Authenticate with Bitbucket.
• After registration, you’ll receive a startup command like:

./start.sh --accountUuid {uuid} \
--repositoryUuid {repo-uuid} \
--runnerUuid {runner-uuid} \
--OAuthClientId xxxx \
--OAuthClientSecret yyyy \
--runtime linux-shell \
--workingDirectory ../temp

Save this command; it will be used in the systemd service.

5. Create Systemd Service

Create the service file:

sudo nano /etc/systemd/system/bitbucket-runner.service

Paste the following content (replace placeholders with your actual values):

[Unit]
Description=Bitbucket Pipelines Runner
After=network.target
 
[Service]
WorkingDirectory=/home/runner/atlassian-bitbucket-pipelines-runner/bin
ExecStart=/home/runner/atlassian-bitbucket-pipelines-runner/bin/start.sh \
--accountUuid {YOUR_ACCOUNT_UUID} \
--repositoryUuid {YOUR_REPO_UUID} \
--runnerUuid {YOUR_RUNNER_UUID} \
--OAuthClientId {YOUR_CLIENT_ID} \
--OAuthClientSecret {YOUR_CLIENT_SECRET} \
--runtime linux-shell \
--workingDirectory ../temp
Restart=always
User=root
 
[Install]
WantedBy=multi-user.target

6. Reload & Enable Service

sudo systemctl daemon-reload
sudo systemctl enable bitbucket-runner
sudo systemctl start bitbucket-runner
sudo systemctl status bitbucket-runner

7. Verify Runner in Bitbucket

• Go to Repository → Repository Settings → Runners.
• The runner should be listed and online.

8. Logs & Troubleshooting

• View logs in real-time:

journalctl -u bitbucket-runner -f

• If Java is missing, systemd will fail — check with:

java -version

• If the runner doesn’t appear online, verify your network/firewall allows outbound connections to Atlassian.

✅ Your self-hosted Bitbucket runner is now installed, registered, and running automatically on boot for both Ubuntu and Amazon Linux 2.