Bitbucket Integration

RunnerHub integrates with Bitbucket Cloud using OAuth 2.0, enabling automatic builds on push and pull request events.

How It Works

RunnerHub uses OAuth 2.0 to securely authenticate with Bitbucket:

You click "Connect Bitbucket" in RunnerHub
     ↓
Redirected to Bitbucket login
     ↓
Grant RunnerHub access to your workspace
     ↓
Bitbucket redirects back to RunnerHub
     ↓
RunnerHub shows your repositories
     ↓
You select a repository
     ↓
Webhook automatically configured
     ↓
Builds trigger on push/PR events

Installation

Step 1: Start the OAuth Flow

1. Go to your RunnerHub app
2. Click Repository → Connect
3. Select Bitbucket

You’ll be redirected to Bitbucket to log in and authorize.

Step 2: Authorize RunnerHub

On Bitbucket:

1. Log in with your Bitbucket credentials
2. Review the permissions requested by RunnerHub
3. Click Grant access

You’ll be redirected back to RunnerHub.

Step 3: Select a Repository

1. RunnerHub displays a list of repositories from your Bitbucket workspace
2. Find the repository you want to connect
3. Click Select

RunnerHub will:

• Store your Bitbucket access token (encrypted)
• Automatically configure a webhook on the repository
• Start listening for push and pull request events

Permissions

When you authorize RunnerHub, Bitbucket grants access to:

Permission	Purpose
account	Access your workspace information
repository	Read repository data and code
webhook	Configure webhooks on repositories

Permissions are workspace-scoped — RunnerHub can only access repositories you have access to.

How Builds Are Triggered

Builds start automatically on:

Event	Trigger
Push	New commits to any branch
Pull Request	PR opened or updated
Manual	Via RunnerHub dashboard
Scheduled	Cron-based triggers (app config)

Filter Branches:

In your pipeline YAML, specify which branches should trigger builds:

.runnerhub/runnerhub.yml

triggers:
  - event: push
    branches:
      - main
      - develop
      - release/*

Webhook Configuration

Webhooks are automatically configured when you connect a repository.

Webhook Details:

• Events: push, pull_request:created, pull_request:updated
• Active: Yes

To view the webhook manually:

1. Go to your Bitbucket repository
2. Settings → Webhooks
3. Find “RunnerHub” in the list

Note

RunnerHub manages the webhook automatically. You shouldn’t manually delete it — reconnect the repository if you need to reconfigure it.

Build Status Reporting

Commit Status

When a build completes, RunnerHub posts the status to your commit:

1. Go to your Bitbucket repository
2. Navigate to Commits
3. Click a commit hash
4. The build status appears under “Build status”

Status Options:

• INPROGRESS — Build running
• SUCCESSFUL — Build passed
• FAILED — Build failed
• STOPPED — Build was cancelled

Pull Request Status

When you open a pull request:

1. RunnerHub automatically starts a build
2. Build status appears in the PR description area
3. Click the status to see detailed logs in RunnerHub

Setting Required Build Status:

You can require builds to pass before PR merge:

1. Go to repository → Settings → Merge checks
2. Check “Build status must succeed”
3. Save

Token Management

RunnerHub handles OAuth token management automatically:

• Token Storage: Encrypted at rest
• Token Refresh: Automatic refresh before expiration
• Token Expiry: RunnerHub handles rotation transparently

If you experience build failures due to token issues:

1. Disconnect the repository: App → Repository → Disconnect
2. Reconnect: Click Connect and authorize again with Bitbucket

Troubleshooting

”Webhook Not Triggering Builds”

If builds don’t start after commits:

1. Verify webhook was created:

   • Go to repository → Settings → Webhooks
   • Look for “RunnerHub” webhook
   • Check that it’s Enabled (blue toggle)

2. Check webhook delivery logs:

   • Click the RunnerHub webhook
   • Scroll to “Recent deliveries”
   • Look for success/failure status
   • Click an entry to see request/response details

3. Reconnect the repository:

   • Go to your RunnerHub app
   • Click Repository → Disconnect
   • Wait a few seconds
   • Click Repository → Connect → Bitbucket → Select the same repository
   • RunnerHub will reconfigure the webhook

”Repository List Empty”

If you can’t see your repositories:

1. Verify Bitbucket OAuth:

   • Make sure you’re logged into Bitbucket
   • You must have Write or higher access to the repository
   • Go to your Bitbucket workspace settings to check your role

2. Re-authorize RunnerHub:

   • Disconnect the current OAuth session (see app settings)
   • Click Connect again
   • Complete the OAuth flow

3. Check workspace permissions:

   • Go to Bitbucket workspace settings → Members
   • Verify your account has access to the repositories

”Permission Denied Error”

If you get permission errors:

1. Check your Bitbucket workspace role:

   • You need Write access to configure webhooks
   • Contact your workspace admin if needed

2. Verify the OAuth scopes:

   • Disconnect the repository
   • Re-authorize and ensure you grant all requested permissions

”Build Logs Missing”

If RunnerHub created a build but logs aren’t showing:

1. Verify the webhook was received:

   • Go to Bitbucket repository → Settings → Webhooks → RunnerHub
   • Check “Recent deliveries” for a push event
   • Verify status code is 200

2. Check repository access:

   • In RunnerHub app settings, verify the clone URL
   • Try cloning manually: git clone <clone_url>

3. Check for network issues:

   • Verify your RunnerHub instance can reach Bitbucket
   • If self-hosted, check firewall rules

Security Considerations

Token Encryption

• Bitbucket OAuth tokens are encrypted at rest
• Never stored in plain text
• Only decrypted when authenticating with Bitbucket

Webhook Security

RunnerHub verifies webhook authenticity using Bitbucket’s:

• X-Request-UUID header for idempotency
• Webhook signature validation (if configured in Bitbucket)

Revoking Access

To remove RunnerHub’s access:

Option 1: Disconnect in RunnerHub

1. Go to your app
2. Click Repository → Disconnect
3. The webhook is removed from Bitbucket

Option 2: Revoke in Bitbucket

1. Go to Bitbucket Personal Settings → Authorized OAuth Apps
2. Find “RunnerHub”
3. Click “Revoke”
4. All RunnerHub repositories go offline immediately

Multiple Workspaces

You can connect the same Bitbucket repository to different RunnerHub workspaces:

• Each workspace maintains separate OAuth tokens
• Webhooks are independent
• Both workspaces will receive events

To set this up:

1. Authorize RunnerHub in each workspace separately
2. Connect the same Bitbucket repository to apps in different workspaces
3. Each workspace will trigger its own builds

Bitbucket Cloud vs Server

RunnerHub supports Bitbucket Cloud with OAuth. For Bitbucket Server or Data Center:

• You can still integrate using webhooks
• Manual webhook configuration required
• OAuth flow not available
• Contact support for Server/Data Center options

Best Practices

1. Enable Build Status Checks

Require builds to pass before merging:

1. Go to repository → Settings → Merge checks
2. Check “Build status must succeed”
3. Select “RunnerHub” as the required check
4. Save

2. Monitor Webhook Health

Periodically verify webhooks are working:

1. Go to repository → Settings → Webhooks → RunnerHub
2. Click “Recent deliveries”
3. Verify recent events show HTTP 200 status
4. If you see failures, reconnect the repository

3. Use Scheduled Builds

Beyond push triggers, set up scheduled builds:

1. Go to your RunnerHub app → Schedules
2. Create a new schedule
3. Set the time and days of week
4. Configure the branch to build

4. Review Commits with Status

When reviewing commits before merge:

1. Go to Commits tab
2. Look for RunnerHub build status badge
3. Click status to see full build logs
4. Merge only when status is SUCCESSFUL

Comparison with Other Providers

Feature	Bitbucket	GitHub	GitLab
Auth Type	OAuth 2.0	GitHub App	OAuth 2.0
Webhook	Automatic	Automatic	Automatic
Status Reports	Commit + PR	PR Checks	Commit + MR
Branch Filtering	Yes	Yes	Yes
Token Refresh	Automatic	N/A	Automatic
Self-hosted	Cloud only	App-based	Enterprise option

---

More Help

• Pipeline YAML Reference
• Bitbucket Cloud Webhooks

Tip

Bitbucket Cloud’s OAuth makes it easy to authorize RunnerHub without sharing credentials. Tokens are automatically refreshed, so you don’t need to manually update permissions.