Link Spaces directly with Bitbucket repositories (repos) so you always know what work is related.

Workspace owners and admins can connect Spaces to their repos, allowing members to add their Bitbucket work to tasks.

Tasks in Spaces with a connected repo can be linked with commits, branches, and pull requests.

What you'll need

• The Bitbucket integration is available on every ClickUp plan.
• Only Workspace owners and admins can create Workspace connections. Multiple Workspace connections are allowed.
• Members and above can create personal connections. 
• Guests and limited members can't use the Bitbucket integration.
• Only repository admins can add Bitbucket repositories to ClickUp.
• Only Workspace owners and admins can update Workspace Settings in the App Center.
• Only Workspace owners and admins can add and link repositories to Spaces.

Connection types

The features and commands available depend on which type of connection you use.

ClickUp commands for Bitbucket are only available for personal connections. The data is not linked to Workspace connections. When a user has a personal connection enabled and runs a Bitbucket command, they will see a list of options, like repository lists, that they are authorized to view in Bitbucket.

Set up the integration

There are three steps to set up the Bitbucket integration in ClickUp:

1. Connect Bitbucket.
2. Attach Bitbucket repositories to your Workspace.
   

   Repos are needed so ClickUp can automatically link pull requests to their respective ClickUp tasks.

3. Link Bitbucket repos to ClickUp Spaces.

You can optionally set a custom branch name format. This format is used in the task app panel for creating branches directly from ClickUp.

Step 1: Connect Bitbucket

To connect Bitbucket from the App Center:

1. Search for and select Bitbucket.
2. Depending on the type of connection you want, select the Personal or Workspace tab.
3. Choose how you want to authorize:
   • Bitbucket account: Authorize using your bitbucket.org account.
   • Self-hosted version: Authorize using a custom Bitbucket URL.
     
4. Click Next.
5. Authorize ClickUp.
6. Click Done.

Step 2: Attach Bitbucket repositories to your Workspace

Only the connection owner can add repositories. 

Attaching a repo does not give ClickUp users access to your repo's codebase.

To add a repo to a Workspace:

1. In the App Center, search for and select Bitbucket.
2. In the upper-right, click Settings.
3. Under Connect Repositories to Spaces, click Add repo.
4. Select the repo you want to add.
5. Repeat the above steps to add more repos.

If you don't see the correct repos, ensure you have signed in to the right account. A Workspace owner or admin must select each repo to connect. Linked repos can be viewed in the App Center.

Step 3: Link Bitbucket repositories to ClickUp Spaces

After adding repos to your Workspace, an admin can add each repo to one or more Spaces. Each ClickUp Space can have multiple repos added.

You can add or remove repos from Spaces at any time.

To link a repo to a Space:

1. In the App Center, search for and select Bitbucket.
2. In the upper-right, click Settings.
3. Under Connect Repositories to Spaces, click the name of the repo you want to link.
4. Click + Add Space and select a Space.
5. Repeat this step to add more Spaces.

Set your branch name format

If your organization uses a specific format for branch names, you can set it from the Bitbucket page in the App Center. When people create branches from ClickUp tasks, it will use this format.

The default format is: :taskId:_:taskName:_:username:

For example: CU-ae27de_Auto-generated-naming_John-smith

The available options are shown in the following table:

To set your default name format from Bitbucket in the App Center:

1. Search for and select Bitbucket.
2. In the upper-right, click Settings.
3. Under Auto-generated branch name, enter your preferred branch name format.
4. Click Save.

Link tasks from Bitbucket

ClickUp automatically associates new Bitbucket activity with tasks if you include a valid ClickUp task ID in any part of the pull request title, pull request description, branch name, or commit message.

When a ClickUp task ID is included in a pull request, a comment with a link to the ClickUp task will be posted in the pull request. A link will not display when manually pasting a pull request into a ClickUp task.

The comment will be posted using the Bitbucket account of the person who set up the repository and Space mapping.

The task ID must be formatted using one of these options:

#{task_id}

CU-{task_id}

{custom_task_id}

#{custom_task_id}

For example:

#1abc2de

CU-1abc2de

eng-123

#eng-123

Link tasks from ClickUp

Manually link ClickUp tasks with Bitbucket commits, branches, and pull requests from ClickUp tasks. Ensure the task is located in a Space that is linked to a repo.

To link a task:

1. Open the task.
2. In the right sidebar, click the Bitbucket icon.
   

   On the right, you'll see suggested branch names and commit messages you can copy to your clipboard. You can also copy the task ID from here.

3. In the lower-right corner, click Add Bitbucket link.
   
4. Paste the link.
5. In the lower-right corner, click Add.

ClickUp task activity

The task activity feed sometimes collapses similar activity items to ensure you see the most important details.

You can take the following actions to locate Bitbucket activity:

• Click More updates to reveal activity that has been hidden.
• When a branch is merged, commits display as a single activity item in the task's activity feed.
  • Click the link to all the commits to open a modal.
  • Click an individual commit to open it in Bitbucket.
• Filter task activity by Git items.
  

Missing activity 

If you can't locate certain activity, ensure that you're correctly referencing the ClickUp task ID to link activity in Bitbucket. You can use any of the following options to reference your ClickUp tasks on commits, branch names, and pull requests:

#{task_id}

CU-{task_id}

{custom_task_id}

For example:

#1abc2de

CU-1abc2de

prefix-1

You can manually link ClickUp tasks with Bitbucket commits, branches, and pull requests from the ClickUp task.

Bitbucket link previews

When you paste a Bitbucket link into a ClickUp task, Chat, or Doc, you'll see the option to paste it as a preview, mention, or URL.

Create Bitbucket issues, branches, and pull requests from ClickUp

Create new branches and pull requests directly from tasks. Ensure the task is located in a Space that is linked to a repository.

To create a branch, or pull request:

1. Open a task and click the Bitbucket icon.
2. On the right, you'll see suggested branch names and commit messages you can copy to your clipboard. You can also copy the task ID from here.
3. In the lower-right corner, click Add Bitbucket link.
4. Choose one of the following options:
   • New Bitbucket Branch
   • New Bitbucket Pull Request
5. Name the branch or pull request.
6. Select a repo and fill out the information. Add a source branch and destination branch if applicable.
7. Click Create.

Bitbucket app panel in tasks

After you paste your first Bitbucket link in a task description or comment, you'll see a new Bitbucket icon in the right sidebar of any tasks that live in Spaces that are connected to repositories. You can click this icon at any time to see every Bitbucket link posted in the task.

Bitbucket task activity uses the person's ClickUp username, or their Bitbucket username if they don't have a ClickUp account.

Update task statuses from Bitbucket

You can update the status of a ClickUp task when you link a commit, push a commit, or create a pull request. ClickUp automatically picks up new Bitbucket activity and associates it with tasks if you include a valid task ID in any part of the pull request title, pull request description, or commit message.

The task ID must be formatted using one of these options:

#{task_id}[status]

CU-{task_id}[status]

{custom_task_id}[status]

#{custom_task_id}[status]

To update a task status:

1. Add the ClickUp task ID in any part of the commit or pull request message.
2. Include the updated task status in square brackets.

For example: #ud5b[ready]

All formats listed in the Link tasks from Bitbucket section of this article can be used. To ensure proper formatting, do not add a space between the task ID and status information.

Manage Bitbucket issues, branches, pull requests, and commits from ClickUp

After you link issues, branches, pull requests, or commits, they display on the right side of your task when you click the Bitbucket icon. Use the ellipsis ... menu to copy the link or delete the item.

If you've joined the Workspace as a guest, you won't be able to use the Bitbucket integration. Contact your Workspace owner or admin to request an upgrade to a Workspace member.

Once you link a Bitbucket item, the following information is displayed in your ClickUp task:

Issue information

After an issue is linked, you can see the following details:

• The person who opened the issue, known as the author
• Any assigned reviewers
• Link created
• Repository
• The issue status.
• URL

Branch information

After a branch is linked, you can see the following details:

• The person who created the branch, known as the author
• Link creator
• Repository
• URL

Pull request information

After a pull request is linked, you can see the following details:

• The person who opened the pull request, known as the author
• Any assigned reviewers
• Assignees
• Line changes
• Link created
• Repository
• Source branch
• Target branch
• The pull request status
• URL

Commit information

After a commit is linked, you can see the following details:

• The person who created the commit, known as the author
• Line changes
• Link created
• Repository
• URL

Add your Bitbucket account to ClickUp

Set up a personal connection using your Bitbucket account.

To add your Bitbucket account from the App Center:

1. Search for and select Bitbucket.
2. Click Connect.
3. Sign in to Bitbucket and authorize ClickUp.
4. Click Done.

Connection issues

Sometimes, the wrong Bitbucket account is linked or there is an issue with the connection. To fix connection errors, try disconnecting and reconnecting your repositories or entire account.

These actions do not impact anyone's ability to access repos using their Bitbucket account through Bitbucket.

To disconnect a repository from the App Center:

1. Search for and select Bitbucket.
2. In the upper-right corner, click Settings.
3. Under Repositories, click the ellipsis ... menu to the right of the repository.
4. Click Delete from ClickUp.

The section below includes instructions for disconnecting your entire account.

Disconnect the Bitbucket integration

If you no longer need to access Bitbucket files in ClickUp, you can disconnect the integration from the App Center:

1. Search for and select Bitbucket.
2. Select the Workspace tab.
   

   Only owners and admins can disconnect Workspace connections.

3. Next to Connected, click the ellipsis ... menu.
4. Select Disconnect.
5. To confirm, click Disconnect.