Bitbucket Data Center

This guide explains how to connect Bitbucket Data Center to an Faheem Code Enterprise Replicated installation. The integration lets users sign in with Bitbucket Data Center, open repositories, and invoke Faheem Code from pull request comments.

Prerequisites

• A Bitbucket Data Center administrator who can create an OAuth 2.0 Application Link.
• A currently supported Bitbucket Data Center version with OAuth 2.0 Application Links enabled. If the application link flow does not show incoming OAuth 2.0 settings, verify your Bitbucket Data Center version and application link settings.
• Repository administrator access for users who will install repository webhooks from Faheem Code.
• Network access from Faheem Code to Bitbucket Data Center for API calls, and from Bitbucket Data Center back to the Faheem Code app URL for webhook delivery.
• If Bitbucket Data Center uses an internal or self-signed certificate, upload the issuing CA in the Faheem Code Enterprise Admin Console under Additional Trusted CA Certificates before deploying.

Create a Bitbucket OAuth application link

In Bitbucket Data Center, create an OAuth 2.0 Application Link for Faheem Code. The exact menu labels can vary by Bitbucket version, but this is usually under Administration > Application Links.

Screenshot: Bitbucket Data Center Application Links settings.

Use this callback URL, where <your-auth-hostname> is your installation's Authentication hostname (auth.<example-user-domain> by default):

https://<your-auth-hostname>/realms/faheemcode/broker/bitbucket_data_center/endpoint

Replace only the hostname. Leave the rest of the path unchanged, for example:

https://auth.faheem-code.example.com/realms/faheemcode/broker/bitbucket_data_center/endpoint

Faheem Code requests the REPO_ADMIN OAuth scope so it can list repositories and install or refresh repository webhooks from the Faheem Code UI. Copy the client ID and client secret. You will paste them into the Faheem Code Enterprise Admin Console.

Note

REPO_ADMIN is required so Faheem Code can list repositories in the UI and create or refresh the Faheem Code Resolver repository webhook. Faheem Code does not perform other repository administration actions.

Screenshot: Bitbucket Data Center incoming OAuth link form.

Create a bot token

This step is strongly recommended but technically optional. When a bot token is configured, Faheem Code posts comments and reactions as the bot account instead of as the user.

Create a dedicated Bitbucket Data Center user for Faheem Code. For example, create a user named faheemcode with an email address such as faheem-code-bot@company.com. Grant this user access to all repositories where Faheem Code should post comments or reactions. Then create an HTTP access token for that user with Repository permissions set to Repository write. Store the token securely. You will need to paste the HTTP access token into the Faheem Code Enterprise Admin Console.

Screenshot: Bitbucket Data Center HTTP access token setup.

Configure the Admin Console

Open the Replicated Admin Console for your Faheem Code Enterprise installation and go to the application configuration page.

In Bitbucket Data Center Authentication:

1. Enable Bitbucket Data Center Authentication.
2. Enter the Bitbucket Data Center Domain.
3. Enter the Bitbucket Data Center Client ID.
4. Enter the Bitbucket Data Center Client Secret.
5. Enter the Bitbucket Data Center Bot Token if you have one.
6. Save and deploy the updated configuration.

Warning

The Bitbucket Data Center Domain must be a bare hostname, for example bitbucket.example.com. Do not include https://.

Sign in with Bitbucket Data Center

After the deployment is completed, users choose Sign in with Bitbucket Data Center on your app's login page.

On first sign-in, users may be asked to accept Faheem Code terms and complete an offline access flow. After sign-in, Faheem Code stores the user's Bitbucket Data Center token so it can list repositories and run resolver jobs as that user.

Install repository webhooks

To trigger Faheem Code on Bitbucket repositories, repository administrators can install the Faheem Code bot onto a repository from Settings > Integrations within the Faheem Code app. For each repository that should support @faheem-code pull request comments, click Install. If a webhook already exists, click Reinstall to refresh it.

Faheem Code creates or updates a repository webhook named Faheem Code Resolver. The webhook URL is connection-specific:

https://app.<example-user-domain>/integration/bitbucket-dc/connections/<connection-id>/events

Faheem Code subscribes the webhook to repository and pull request events, including pull request comment add, edit, and delete events. The signing secret is generated and stored by Faheem Code.

Trigger Faheem Code from Bitbucket Data Center

Open a pull request and add a comment containing @faheem-code. Inline pull request comments are also supported.

Faheem Code starts a resolver job when:

• The repository webhook is installed and active.
• The webhook delivery signature is valid.
• The mentioning Bitbucket user has signed in to Faheem Code with Bitbucket Data Center.
• The mentioning user has access to the repository.

The resolver context includes the pull request title, description, current comments, and the triggering comment. Faheem Code replies back to the pull request when the job starts and when it completes.

Troubleshooting

Symptom	Check
The Bitbucket Data Center login option is not visible	Confirm Bitbucket Data Center Authentication is enabled in the Admin Console and the deployment has been applied.
OAuth redirects fail	Confirm the callback URL exactly matches https://<your-auth-hostname>/realms/faheemcode/broker/bitbucket_data_center/endpoint.
Login tries to reach an invalid https://https://... URL	Remove https:// from the Bitbucket Data Center Domain field in the Admin Console.
Repository webhook install fails	Confirm the user has repository admin access and the OAuth app grants REPO_ADMIN.
Webhook delivery reaches Faheem Code but no job starts	Confirm the comment contains @faheem-code, the webhook is installed for that repository, and the mentioning Bitbucket user has signed in to Faheem Code.
Faheem Code cannot list Bitbucket repositories or install webhooks	Confirm the Faheem Code cluster can reach the Bitbucket Data Center URL.
Bitbucket webhook deliveries do not reach Faheem Code	Confirm the Bitbucket Data Center network can reach the Faheem Code app URL.
Bitbucket API calls fail with TLS errors	Upload the Bitbucket Data Center CA certificate in Additional Trusted CA Certificates and redeploy.