Bitbucket Integration

Bitbucket integration in Dokploy uses direct authentication with App Passwords or Repository Access Tokens (API tokens) to access your Bitbucket repositories.

Features

App Password authentication for simple setup
Repository Access Token (API token) support for enhanced security
Workspace-level repository access
Repository and branch browsing
Support for both personal and workspace repositories
No OAuth flow required

Prerequisites

A Bitbucket account (Bitbucket Cloud)
Access to the repositories you want to deploy
Workspace membership for team repositories

Authentication Methods

Bitbucket supports two authentication methods:

App Passwords (Recommended)
Repository Access Tokens

App Passwords provide user-level access with scoped permissions.Best for:

Personal repositories
Multi-workspace access
User-level deployments

Required Scopes:

repository:read - Read repository content
repository:write - Clone repositories

Repository Access Tokens (API tokens) provide workspace-level access.Best for:

Workspace repositories
Team deployments
Automated systems

Required Scopes:

repository:read
repository:write

Setup with App Passwords

Navigate to App Passwords

Log in to Bitbucket
Click your profile avatar → Personal settings
Under “Access management”, click App passwords
Click Create app password

Configure App Password

Fill in the app password details:Label: Choose a descriptive name (e.g., “Dokploy Production”)Permissions: Select the following scopes:

Repositories → Read
Repositories → Write

You can grant additional scopes, but these are the minimum required.

Create and Copy Password

Click Create
Copy the generated app password immediately

The app password is shown only once. Store it securely.

Note Your Username

You’ll need your Bitbucket username for configuration:

Found in your profile URL: https://bitbucket.org/{username}/
Or in Personal settings → Account settings

Setup with Repository Access Tokens

Navigate to Workspace Settings

Go to your Bitbucket workspace
Click Settings (workspace settings, not repository)
Under “Access tokens”, click Repository access tokens
Click Create Repository Access Token

Configure Token

Fill in the token details:Token name: Descriptive name (e.g., “Dokploy Deploy”)Scopes: Select:

Repositories → Read
Repositories → Write

Repositories: Choose which repositories to grant access to

All repositories in workspace
Specific repositories

Create and Copy Token

Click Create
Copy the generated token

Repository Access Tokens are shown only once.

Note Required Information

You’ll need:

API Token: The token you just copied
Atlassian Email: Your Atlassian account email
Workspace Name: The workspace slug (from URL)

Configuring in Dokploy

With App Password

Navigate to Git Providers

In Dokploy dashboard:

Go to Settings → Git Providers
Click Add Git Provider
Select Bitbucket

Enter App Password Configuration

Fill in the Bitbucket details:Provider Name: A friendly name (e.g., “Bitbucket Personal”)Bitbucket Username: Your Bitbucket usernameApp Password: The app password you generatedWorkspace Name (optional): Leave empty to use username, or specify workspace slug

Workspace name is the slug in your workspace URL: bitbucket.org/{workspace-slug}

Test Connection

Click Test Connection to verify:

Credentials are correct
API access is working
Repositories are accessible

The test displays the number of accessible repositories.

Save Provider

Click Save to store the configuration.

With Repository Access Token

Navigate to Git Providers

In Dokploy dashboard:

Go to Settings → Git Providers
Click Add Git Provider
Select Bitbucket

Enter API Token Configuration

Fill in the Bitbucket details:Provider Name: A friendly name (e.g., “Bitbucket Team”)Atlassian Email: Your Atlassian account email addressAPI Token: The repository access tokenWorkspace Name: The workspace slug

For API tokens, Atlassian email is required for API authentication.

Test and Save

Click Test Connection
Verify repository count
Click Save

Using Bitbucket in Applications

Deploying from Bitbucket

Create or Edit Application

When creating/editing an application:

Set Source Type to “Git”
Select your Bitbucket provider

Select Repository

Choose from accessible repositories:

Repositories appear as repository names
Both personal and workspace repos are shown
Only repos with granted access are available

Configure Deployment

Owner: Workspace slug or usernameRepository Slug: Automatically filled from selectionBranch: Select the branch to deployAuto Deploy (optional): Configure automatic deployments

Repository Structure

Bitbucket repositories include:

{
  name: "my-app",
  url: "https://bitbucket.org/workspace/my-app",
  slug: "my-app",  // Used for git operations
  owner: {
    username: "workspace"  // Workspace slug
  }
}

Authentication Details

App Password Authentication

For Git Operations:

https://{username}:{app_password}@bitbucket.org/{owner}/{repo}.git

For API Calls:

Authorization: Basic base64({username}:{app_password})

API Token Authentication

For Git Operations:

https://x-bitbucket-api-token-auth:{api_token}@bitbucket.org/{owner}/{repo}.git

For API Calls:

Authorization: Basic base64({atlassian_email}:{api_token})

Bitbucket requires the Atlassian email for API authentication with tokens, but uses a special format for git operations.

API Integration

Repository Listing

Fetches repositories with pagination:

GET https://api.bitbucket.org/2.0/repositories/{workspace}?pagelen=100
Authorization: Basic {credentials}

Pagination:

100 repositories per page (maximum)
Uses next field for pagination
Automatically fetches all pages

Response:

{
  "values": [
    {
      "name": "my-app",
      "slug": "my-app",
      "links": {
        "html": {
          "href": "https://bitbucket.org/workspace/my-app"
        }
      },
      "workspace": {
        "slug": "workspace"
      }
    }
  ],
  "next": "https://api.bitbucket.org/2.0/repositories/workspace?page=2"
}

Branch Listing

Fetches branches for a repository:

GET https://api.bitbucket.org/2.0/repositories/{owner}/{repo}/refs/branches?pagelen=100
Authorization: Basic {credentials}

Response:

{
  "values": [
    {
      "name": "main",
      "target": {
        "hash": "abc123..."
      }
    }
  ]
}

Repository Cloning

Clone command format:

# With App Password
git clone --branch {branch} --depth 1 \
  https://{username}:{app_password}@bitbucket.org/{owner}/{repo}.git \
  {outputPath}

# With API Token
git clone --branch {branch} --depth 1 \
  https://x-bitbucket-api-token-auth:{api_token}@bitbucket.org/{owner}/{repo}.git \
  {outputPath}

Workspace vs Personal Repositories

Personal Repositories

Use your username as workspace:

Workspace Name: your-username
Repositories: your-username/repo1, your-username/repo2

Workspace Repositories

Use workspace slug:

Workspace Name: team-workspace
Repositories: team-workspace/repo1, team-workspace/repo2

Mixed Access

With App Passwords, you can access:

Your personal repositories
All workspace repositories where you’re a member

Leave Workspace Name empty to use your username, or specify a workspace to filter repositories.

Troubleshooting

Authentication Fails

Symptoms: “Invalid credentials” or “Unauthorized” errorsFor App Passwords:

Check Username: Must be exact Bitbucket username
Verify App Password: Ensure copied correctly (no extra spaces)
Review Scopes: Ensure Read and Write repository scopes are enabled

Test Manually:

curl -u username:app_password \
  https://api.bitbucket.org/2.0/user

For API Tokens:

Check Email: Must be exact Atlassian account email
Verify Token: Ensure token is not expired or revoked
Review Scopes: Check token has required permissions

Test Manually:

curl -u email:api_token \
  https://api.bitbucket.org/2.0/user

No Repositories Listed

Symptoms: Test connection succeeds but no repositories shownSolutions:

Check Workspace: Verify workspace name is correct slug
Review Membership: Ensure you’re a member of the workspace
Create Test Repo: Create a repository to verify access

Test API Call:

curl -u credentials \
  "https://api.bitbucket.org/2.0/repositories/{workspace}"

Check Token Scope: For API tokens, verify repo access is granted

Clone Failures

Symptoms: “Repository configuration failed” during deploymentSolutions:

Verify Repository Slug: Must match exactly (case-sensitive)
Check Owner: Should be workspace slug, not display name

Test Git Access:

# App Password
git ls-remote https://username:password@bitbucket.org/owner/repo.git

# API Token
git ls-remote https://x-bitbucket-api-token-auth:token@bitbucket.org/owner/repo.git

Review Permissions: Ensure read access to repository

Rate Limiting

Symptoms: “Rate limit exceeded” errorsSolutions:

Check Usage: Bitbucket limits vary by plan
Throttle Deployments: Space out deployments
Review Limits:
- Free: 1000 requests/hour
- Paid: Higher limits based on plan
Use Separate Tokens: Different apps for different purposes

Workspace Name Confusion

Symptoms: Wrong repositories shown or access deniedSolutions:

Find Workspace Slug: Check URL when viewing workspace:
```
https://bitbucket.org/{workspace-slug}/
```
Not Display Name: Use slug, not the display name
Leave Empty: For personal repos, leave workspace name empty
Test Both: Try with and without workspace name

Security Best Practices

1. Credential Management

Protect your Bitbucket credentials:

Never Commit: Don’t commit app passwords or tokens to repositories
Rotate Regularly: Regenerate credentials periodically
Use Separate Credentials: Different tokens for dev/staging/prod
Revoke Unused: Delete old or unused app passwords and tokens

2. Scope Limitation

Grant minimum necessary permissions:

Read Only When Possible: If no push required, use read-only scopes
Repository-Specific: Use Repository Access Tokens for specific repos
Avoid Admin: Don’t grant admin scopes unless absolutely needed

3. App Password vs API Token

Use App Passwords for:

Personal projects
Individual developers
Multi-workspace access

Use API Tokens for:

Team deployments
Workspace-level automation
Service accounts
Specific repository access

4. Access Monitoring

Review Access: Regularly audit workspace members
Monitor Usage: Check Bitbucket access logs
Track Deployments: Monitor Dokploy deployment logs
Revoke on Leave: Remove access when team members leave

Advanced Configuration

Multiple Bitbucket Providers

Configure separate providers for: Different Workspaces:

Provider 1:
  Name: Team A Workspace
  Workspace: team-a
  Credentials: App Password

Provider 2:
  Name: Team B Workspace
  Workspace: team-b
  Credentials: API Token

Different Credential Types:

Provider 1:
  Name: Personal Repos
  Auth: App Password
  Workspace: (empty)

Provider 2:
  Name: Company Repos
  Auth: API Token
  Workspace: company-workspace

Submodule Support

Enable submodules in your application settings:

Toggle Enable Submodules
Ensure submodule repositories are accessible with same credentials
Submodules must use HTTPS URLs

Clone with submodules:

git clone --branch main --depth 1 --recurse-submodules \
  https://credentials@bitbucket.org/owner/repo.git

Repository Filtering

For workspaces with many repositories:

Use different providers for different projects
Organize by team or product
Use workspace filtering

Comparison with Other Providers

Feature	Bitbucket	GitHub	GitLab
OAuth Flow	❌ No	✅ Yes	✅ Yes
App Passwords	✅ Yes	❌ No	❌ No
API Tokens	✅ Yes	✅ Yes	✅ Yes
Webhooks	🔜 Soon	✅ Yes	🔜 Soon
Auto Refresh	❌ N/A	✅ Yes	✅ Yes
Self-Hosted	❌ No	❌ No	✅ Yes

Limitations

Current limitations of Bitbucket integration:

No Webhook Support: Automatic deployments require manual triggers
No Server Version: Bitbucket Server/Data Center not supported (only Cloud)
No OAuth: Uses direct authentication instead of OAuth flow
Manual Token Rotation: App passwords and tokens don’t auto-refresh

Future Enhancements

Planned improvements:

Webhook Support: Automatic deployments on push
Bitbucket Server: Support for self-hosted Bitbucket
Deploy Keys: SSH-based authentication
Pull Request Previews: Preview deployments for PRs

Next Steps

Deploy an Application

Create your first deployment from Bitbucket

GitHub Integration

Compare with GitHub integration

GitLab Integration

Compare with GitLab integration

Git Providers Overview

Compare all Git provider options

Git Providers

Notifications

Authentication

​Features

​Prerequisites

​Authentication Methods

​Setup with App Passwords

​Setup with Repository Access Tokens

​Configuring in Dokploy

​With App Password

​With Repository Access Token

​Using Bitbucket in Applications

​Deploying from Bitbucket

​Repository Structure

​Authentication Details

​App Password Authentication

​API Token Authentication

​API Integration

​Repository Listing

​Branch Listing

​Repository Cloning

​Workspace vs Personal Repositories

​Personal Repositories

​Workspace Repositories

​Mixed Access

​Troubleshooting

​Security Best Practices

​1. Credential Management

​2. Scope Limitation

​3. App Password vs API Token

​4. Access Monitoring

​Advanced Configuration

​Multiple Bitbucket Providers

​Submodule Support

​Repository Filtering

​Comparison with Other Providers

​Limitations

​Future Enhancements

​Next Steps

Deploy an Application

GitHub Integration

GitLab Integration

Git Providers Overview

Features

Prerequisites

Authentication Methods

Setup with App Passwords

Setup with Repository Access Tokens

Configuring in Dokploy

With App Password

With Repository Access Token

Using Bitbucket in Applications

Deploying from Bitbucket

Repository Structure

Authentication Details

App Password Authentication

API Token Authentication

API Integration

Repository Listing

Branch Listing

Repository Cloning

Workspace vs Personal Repositories

Personal Repositories

Workspace Repositories

Mixed Access

Troubleshooting

Security Best Practices

1. Credential Management

2. Scope Limitation

3. App Password vs API Token

4. Access Monitoring

Advanced Configuration

Multiple Bitbucket Providers

Submodule Support

Repository Filtering

Comparison with Other Providers

Limitations

Future Enhancements

Next Steps