Skip to main content

​
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.