Skip to main content

Bitbucket connector settings reference

This topic describes the settings and permissions for the Bitbucket connector. Harness supports both Cloud and Data Center (On-Prem) versions of Bitbucket. The following settings are applicable to both versions.

Overview settings

  • Name: The unique name for this connector. Harness generates an Id (Entity Identifier) based on the Name. You can edit the Id during initial connector creation. Once you save the connector, the Id is locked.
  • Description: Optional text string.
  • Tags: Optional labels you can use for filtering. For details, go to the Tags reference.

Details settings

The Details settings specify which BitBucket account or repository you want this connector to connect to, whether to connect over HTTP or SSH, and the URL to use.

URL Type

Select Account to connect an entire Bitbucket account. This option lets you use one connector to connect to all repositories in the specified Bitbucket account. Make sure you have at least one repo in the account; you need a repo to test the connection and save the connector.

Select Repository to connect to a single, specific repo in a Bitbucket account.

Connection Type

Select the protocol, HTTP or SSH, to use for cloning and authentication. The Connection Type determines the URL format required for the Bitbucket Account/Repository URL field. It also determines the Authentication method you must use in the Credentials settings.

Bitbucket Account/Repository URL

Enter the URL for the Bitbucket account or repository that you want to connect to. The required value is determined by the URL Type, Connection Type, and your Bitbucket account type (Cloud or Data Center).

In the Bitbucket Account URL field, provide only the account-identifying portion of the Bitbucket URL, such as https://bitbucket.org/my-bitbucket/. Do not include any repo name or project name.

The URL format depends on the Connection Type and your Bitbucket account type (Cloud or Data Center). The following table provides format examples for each combination.

Connection TypeBitbucket CloudBitbucket Data Center (On-Prem)
HTTPhttps://bitbucket.org/USERNAME/ or https://bitbucket.orghttps://bitbucket.YOUR-ORG-HOSTNAME/scm/
SSHgit@bitbucket.org:USERNAME/git@bitbucket.YOUR-ORG-HOSTNAME/

HTTP and SSH examples of Bitbucket Cloud account URLs.

HTTP and SSH examples of Bitbucket Data Center account URLs.
On-Prem Accounts

There are several possible URL formats for Bitbucket Data Center (On-Prem) accounts, such as bitbucket.myorg.com or bitbucket.my.org.com, as well as variations of repo URLs. Your URL might not match the examples above, and you might need to modify the URL.

For SSH URLs, you may need to use a DOMAIN-NAME:PORT format for the authority portion, such as bitbucket.myorg.com:8080. This depends on your server and firewall configuration. If the connection test fails, make sure you've used the appropriate URL format.

Bitbucket connector Details settings configured to connect to an On-Prem account using an SSH URL with a port number.

If your On-Prem repo URL has an extra segment before the project ID or a multi-segment project ID, such as bitbucket.myorg.com/scm/DESCRIPTOR/PROJECT-ID/REPO-NAME.git, some API functionality can fail if you use the full URL. To fix this, exclude the extra segment when you enter the URL in the Bitbucket Repository URL field.

Test Repository

This field is only required if the URL Type is Account. Provide a path to a repo in your Bitbucket account that Harness can use to test the connector. Harness uses this repo path to validate the connection only. When you use this connector in a pipeline, you'll specify a true code repo in your pipeline configuration or at runtime.

For Bitbucket Cloud accounts, the Test Repository path format is: REPO-NAME.git.

Test Repository field populated with the path to a Bitbucket Cloud repo.

For BitBucket Data Center (On-Prem) accounts, you must include the project ID, such as PROJECT-ID/REPO-NAME.git.

Test Repository field populated with the path to a Bitbucket Data Center repo.

Credentials settings

Provide authentication credentials for the connector.

Authentication

The Connection Type you chose in the Details settings determines the Authentication method.

The HTTP Connection Type requires Username and Password authentication for all accounts and repos, including read-only repos.

In the Username field, enter the Bitbucket account username as specified in your Bitbucket Account settings. You can use either plaintext or a Harness encrypted text secret.

Bitbucket Personal settings screen, highlighting the Account settings page and the Username field.

In the Password field, provide a Bitbucket account-level access token, HTTP access token, or app password. Passwords are stored as Harness encrypted text secrets.

You must provide an account-level app password or token. Repo-level tokens are not supported.

If you use a Google account to log in to Bitbucket, you must use an App password.

Bitbucket accounts with two-factor authentication must use access tokens.

Enable API access

You must enable API access to use Git-based triggers, manage webhooks, or update Git statuses with this connector. If you are using the Harness Git Experience, this setting is required. API access requires username and password authentication.

In the Username field, enter the Bitbucket account username as specified in your Bitbucket Account settings. You can use either plaintext or a Harness encrypted text secret.

Bitbucket Personal settings screen, highlighting the Account settings page and the Username field.

In the Personal Access Token field, provide a Bitbucket account-level App password, Access token, or HTTP access token. Passwords are stored as Harness Encrypted Text secrets.

You must provide an account-level app password or token. Repo-level tokens are not supported.

warning

For HTTP Connection Types, use the same password you used earlier, and make sure the Username fields are both plain-text or both encrypted. Don't use a plain-text username for one field and a secret for the other.

For On-Prem repos, if the repo URL has an extra segment before the project ID, such as bitbucket.myorg.com/scm/DESCRIPTOR/PROJECT-ID/REPO-NAME.git, some API functionality can fail if you use the full URL. To fix this, remove the extra segment from the Bitbucket Repository URL.

Connectivity Mode settings

Select whether you want Harness to connect directly to your Bitbucket account or repo, or if you want Harness to communicate with your Bitbucket account or repo through a delegate. If you plan to use this connector with Harness Cloud build infrastructure, you must select Connect through Harness Platform.

tip

The Secure Connect option is for secure connect with Harness Cloud.

Delegates Setup

If you select Connect through a Harness Delegate, you can select Use any available Delegate or Only use Delegates with all of the following tags.

If you want to use specific delegates, you must identify those delegates. For more information, go to Use delegate selectors.

Kubernetes delegate with self-signed certificates

If your codebase connector allows API access and connects through a Harness Delegate that uses self-signed certificates, you must specify ADDITIONAL_CERTS_PATH in the delegate pod, as described in Configure a Kubernetes build farm to use self-signed certificates.

Troubleshooting

Here are some troubleshooting suggestions for BitBucket Connectors.

Connection test failing

If the connection test returns a not authorized error, make sure you used the Username specified in the Bitbucket Account settings.

Bitbucket Personal settings screen, highlighting the Account settings page and the Username field.

The connection test may also fail if the token doesn't have sufficient privileges.

Status doesn't update in BitBucket Cloud PRs

There are two potential causes for this:

  • Harness uses the pipeline's codebase connector to send status updates to BitBucket. Check the pipeline's codebase configuration to confirm that it is using your BitBucket code repo connector.
  • BitBucket Cloud limits the key size for sending status updates to PRs, and this can cause incorrect status updates in PRs due to some statuses failing to send. If you encounter this issue with BitBucket Cloud, contact Harness Support to troubleshoot this issue by enabling a feature flag, CI_BITBUCKET_STATUS_KEY_HASH.

Some API functions fail for On-Prem repos

If your On-Prem repo URL has an extra segment before the project ID or a multi-segment project ID, such as bitbucket.myorg.com/scm/DESCRIPTOR/PROJECT-ID/REPO-NAME.git, some API functionality can fail if you use the full URL. To fix this, remove the extra segment from the Bitbucket Repository URL.