> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ahmadraza.in/llms.txt
> Use this file to discover all available pages before exploring further.

# BitbucketRunner

# 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

```bash theme={null}
sudo apt update -y
sudo apt install -y openjdk-11-jdk
java -version
```

### Amazon Linux 2

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
./start.sh --setup
```

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

```bash theme={null}
./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:

```bash theme={null}
sudo nano /etc/systemd/system/bitbucket-runner.service
```

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

```ini theme={null}
[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

```bash theme={null}
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:

```bash theme={null}
journalctl -u bitbucket-runner -f
```

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

```bash theme={null}
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.