Skip to content

feat: add bitbucket developer docs #295

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Saurabhkmr98 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

feat: add bitbucket developer docs #295

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/.vitepress/config.mts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -387,6 +387,7 @@ export default extendConfig(
text: "Integrations",
collapsed: true,
items: [
{ text: "Bitbucket", link: "/self-hosting/govern/integrations/bitbucket" },
{ text: "GitHub", link: "/self-hosting/govern/integrations/github" },
{ text: "GitLab", link: "/self-hosting/govern/integrations/gitlab" },
{ text: "Sentry", link: "/self-hosting/govern/integrations/sentry" },
Expand Down
123 changes: 123 additions & 0 deletions docs/self-hosting/govern/integrations/bitbucket.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
---
title: Configure Bitbucket for Plane integration
description: Connect Bitbucket to your self-hosted Plane instance. Sync pull requests and commits with Plane work items for development workflow tracking.
keywords: plane bitbucket integration, bitbucket cloud, bitbucket data center, bitbucket sync, pull request tracking
---

# Configure Bitbucket for Plane integration <Badge type="info" text="Pro" />

This guide walks you through setting up a Bitbucket application to enable Bitbucket integration for your Plane workspace on a self-hosted instance. Since self-hosted environments don't come pre-configured for Bitbucket, you'll need to create an OAuth consumer or application link, configure authentication, and set the necessary permissions to ensure seamless integration.

This guide covers configuration for both:

- **[Bitbucket Cloud](/self-hosting/govern/integrations/bitbucket#bitbucket-cloud)**
The standard cloud-hosted Bitbucket service at bitbucket.org

- **[Bitbucket Data Center](/self-hosting/govern/integrations/bitbucket#bitbucket-data-center)**
Self-hosted Bitbucket instances for organizations with specific compliance or security requirements

In this guide, you'll:

1. [Create and configure a Bitbucket application](/self-hosting/govern/integrations/bitbucket#create-bitbucket-application)
2. [Configure your Plane instance](/self-hosting/govern/integrations/bitbucket#configure-plane-instance)

::: warning
**Activate Bitbucket integration**

After creating and configuring the Bitbucket application and configuring the instance as detailed on this page, you'll need to [setup the Bitbucket integration](https://docs.plane.so/integrations/bitbucket) within Plane.
:::

## Create Bitbucket Application

:::tabs key:bitbucket-edition

== Bitbucket Cloud {#bitbucket-cloud}

Follow these steps to register an OAuth consumer in your Bitbucket workspace, set the callback URL and scopes, and then configure your Plane instance so it can sync pull requests and commits.

#### Bitbucket Cloud

@coderabbitai coderabbitai Bot Jun 22, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Use h3 headings here.

These #### headings jump too far from the surrounding ## sections and will fail the heading-increment lint rule. Drop them to ### (or remove the duplicate headings and rely on the tab labels).

Suggested fix 
-#### Bitbucket Cloud
+### Bitbucket Cloud
@@
-#### Bitbucket Data Center
+### Bitbucket Data Center

Also applies to: 75-75

🧰 Tools
🪛 markdownlint-cli2 (0.22.1)

[warning] 38-38: Heading levels should only increment by one level at a time
Expected: h3; Actual: h4

(MD001, heading-increment)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/self-hosting/govern/integrations/bitbucket.md` at line 38, The document
uses h4 headings (####) that skip the h3 level, violating the heading-increment
lint rule which requires headings to increment by only one level at a time.
Change all h4 headings (####) to h3 headings (###) to maintain proper hierarchy
between the surrounding h2 sections (##). This includes the "Bitbucket Cloud"
heading and the heading on line 75 mentioned in the comment, and any other
similar h4 headings in the document that jump directly from h2 sections.

Source: Linters/SAST tools


1. Log in to Bitbucket Cloud and navigate to your workspace.

2. Go to **Workspace Settings → Apps & Features → OAuth Consumers**.

3. Click **Add consumer** to begin the setup.

4. Provide a **Name** for your OAuth consumer.

5. Enter the following **Callback URL**, replacing `[YOUR_DOMAIN]` with your actual domain:
```bash
https://[YOUR_DOMAIN]/silo/api/oauth/bitbucket/auth/callback
```

6. Set permissions by selecting the required **Scopes**. The table below explains each scope:

| Category | Permission | Explanation |
| ---------------- | ------------ | ------------------------------------------------------------------------ |
| Account | `email` | Read the user's primary email address. |
| Account | `read` | Read the user's account information and workspace memberships. |
| Repositories | `read` | Read access to repositories, including source code and metadata. |
| Repositories | `write` | Write access to repositories, required for creating and updating refs. |
| Pull requests | `read` | Read pull requests, comments, and activity on repositories. |
| Pull requests | `write` | Create and update pull requests and post comments. |
| Projects | `read` | Read project metadata and repository associations. |
| Issues | `read` | Read issues and their comments on repositories. |
| Issues | `write` | Create and update issues and post comments. |
| Webhooks | `read` | Read webhook subscriptions on repositories and workspaces. |
| Webhooks | `write` | Create and manage webhook subscriptions. |

7. Click **Save** to finalize the setup.

== Bitbucket Data Center {#bitbucket-data-center}

These instructions cover registering an application link on your self-hosted Bitbucket Data Center instance, setting the redirect URL, and assigning the required permissions for Plane to access your repositories.

#### Bitbucket Data Center

1. Log in to your Bitbucket Data Center instance as an administrator.

2. Go to **Settings → Application Links**.

3. Click **Create link** to begin configuring a new application link.

4. Enter the URL of your Plane instance and click **Continue**.

5. Enter the following **Redirect URL**, replacing `[YOUR_DOMAIN]` with your actual domain:
```bash
https://[YOUR_DOMAIN]/silo/api/oauth/bitbucket-dc/auth/callback
```

6. Set the required **Application Permissions**:

| Resource | Permission Level | Explanation |
| ------------- | ---------------- | ------------------------------------------------------------------------ |
| Projects | `Admin` | Required to read project metadata and manage webhook subscriptions. |
| Repositories | `Read` | Read access to repository metadata, branches, and commits. |
| Repositories | `Write` | Write access to create refs and update repository content. |
| Repositories | `Admin` | Required to manage repository-level webhooks. |

7. Click **Save** to create the application link.

:::

## Configure Plane instance

:::tabs key:bitbucket-edition

== Bitbucket Cloud {#bitbucket-cloud}

1. Copy the **Key** and **Secret** from the newly created OAuth consumer.

2. Add these environment variables with the values to your Plane instance's `.env` file.

```bash
BITBUCKET_CLIENT_ID=<key>
BITBUCKET_CLIENT_SECRET=<secret>
BITBUCKET_WEBHOOK_SECRET=<random-string>
```

3. Save the file and restart the instance.

4. Once you've completed the instance configuration, [activate the Bitbucket integration in Plane](https://docs.plane.so/integrations/bitbucket?edition=bitbucket-cloud).

:::
Loading