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.

ArgoCD

CI/CD

Helm

Kustomise

BitbucketRunner

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

1. System Requirements

2. Install Java (required for runner)

Ubuntu

Amazon Linux 2

3. Download the Bitbucket Runner

4. Register the Runner

5. Create Systemd Service

6. Reload & Enable Service

7. Verify Runner in Bitbucket

8. Logs & Troubleshooting

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

​1. System Requirements

​2. Install Java (required for runner)

​Ubuntu

​Amazon Linux 2

​3. Download the Bitbucket Runner

​4. Register the Runner

​5. Create Systemd Service

​6. Reload & Enable Service

​7. Verify Runner in Bitbucket

​8. Logs & Troubleshooting

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

1. System Requirements

2. Install Java (required for runner)

Ubuntu

Amazon Linux 2

3. Download the Bitbucket Runner

4. Register the Runner

5. Create Systemd Service

6. Reload & Enable Service

7. Verify Runner in Bitbucket

8. Logs & Troubleshooting