Bitbucket Integration

Overview

The Bitbucket integration connects your Bitbucket Cloud workspace to Fencer via OAuth2. Once connected, you can add repositories for code scanning, receive automatic scans on push and pull request events, and see scan results reported as commit statuses directly on your Bitbucket commits and pull requests.

Prerequisites

• An active Fencer organization with a valid subscription.
• The Administrator role in your Fencer organization.
• Admin access to the Bitbucket workspace you want to connect.

How it works

When you connect Bitbucket, Fencer initiates an OAuth2 authorization flow. You enter your Bitbucket workspace slug, then authorize Fencer on Bitbucket. After authorization, Fencer stores encrypted OAuth tokens and creates a connection linked to your workspace.

Repositories are added individually — you search for and select repositories from your workspace, and Fencer registers a webhook on each one. The webhook listens for push and pull request events to trigger code scans automatically, and for pull request comments, which start AI PR reviews. Scan results are reported back to Bitbucket as build statuses on the relevant commit, so you can see pass/fail results directly in pull requests.

Usage / Configuration

Connecting Bitbucket

1. Go to Admin > Integrations.
2. Under Available Integrations, click the Bitbucket (Code) card, then click Continue.
3. Enter your Workspace slug (e.g., my-workspace). You can find it in your workspace URL, for example bitbucket.org/your-workspace.
4. Click Connect Bitbucket. A popup opens and redirects you to Bitbucket for OAuth authorization.
5. On Bitbucket, review the permissions and click Grant access.
6. The popup closes and you are taken to the new connection’s edit page.

Adding Repositories

After connecting, you need to add repositories individually:

1. Go to Admin > Integrations and click Edit on your Bitbucket connection.
2. Click Add repositories and search for repositories in your workspace.
3. Click Add next to a repository. Fencer fetches the repository details (default branch, visibility) and registers a webhook.
4. An initial code scan is triggered automatically for the newly added repository.

Under Connected repositories, you can also mark each repository in or out of scope, or Suspend and Resume its scans.

Removing Repositories

1. Go to Admin > Integrations and click Edit on your Bitbucket connection.
2. Under Connected repositories, click Remove repository on the repository and confirm with Remove.
3. Fencer deletes the webhook on Bitbucket and soft-deletes the repository from your organization. Existing scan results are preserved.

Code Scanning on Push and Pull Requests

Code scans are triggered automatically when Bitbucket delivers webhook events:

• repo:push — triggers a scan for the pushed branch and commit.
• pullrequest:created and pullrequest:updated — triggers a scan for the pull request source branch.

Fencer reports build statuses back to Bitbucket as the scan progresses:

• INPROGRESS — the scan is queued or running.
• SUCCESSFUL — the scan completed and passed all of the repository’s Checks settings, configured on the repository’s settings page under Posture > Code.
• FAILED — the scan tripped one of those checks (for example Fail on new vulnerabilities if), or the scan crashed or timed out.
• STOPPED — the scan was cancelled.

A push to a branch outside the repository’s branch scope gets a SUCCESSFUL status explaining that automatic scans were not run.

These statuses appear on the commit in Bitbucket, including in the pull request view. When Post findings on pull requests is on in the repository’s Checks settings (the default), Fencer also adds a Fencer Security Scan Code Insights report with an annotation for each vulnerability. Post findings as can post that list as a pull request comment instead of the report.

Fix Pull Requests

When you open a pull request from an AI fix for a vulnerability, Fencer creates a new branch on your Bitbucket repository with the patch applied and opens a pull request against the branch the vulnerability was found on.

Identity Sync

The Bitbucket integration syncs your workspace members as identities in Fencer. After connecting, Fencer fetches all workspace members and creates vendor identity records including display names, usernames, and account IDs.

Re-authorizing a Connection

If your OAuth tokens expire or become invalid, the connection edit page will show a warning. To re-authorize:

1. Go to Admin > Integrations and click Edit on your Bitbucket connection.
2. Click the Reconnect Bitbucket link to go through the OAuth flow again in a popup.
3. Fencer updates the stored tokens without recreating the connection or losing your configured repositories.

Disconnecting

1. Go to Admin > Integrations and find your Bitbucket connection.
2. Click Remove on the connection and confirm with Remove.
3. Fencer removes all registered webhooks, clears stored OAuth tokens, and soft-deletes all associated repositories.

Examples

Typical workflow with a pull request

1. A developer opens a pull request on a connected Bitbucket repository.
2. Bitbucket sends a pullrequest:created webhook event to Fencer.
3. Fencer triggers a code scan for the PR source branch and commit.
4. A build status of INPROGRESS appears on the commit in Bitbucket.
5. The scan completes and the build status updates to SUCCESSFUL or FAILED with a link to the scan details in Fencer.
6. The developer clicks the status link to review any findings.

Troubleshooting

• “Failed to register Bitbucket webhook for this repository.”: Bitbucket refused to create the webhook, so the repository was not added. Confirm the account you authorized still has admin access to the workspace, re-authorize if its token has expired, and add the repository again.
• Build statuses not appearing: Verify the connection is still authorized by checking the token status on the edit page. Re-authorize if needed.
• Repository not found during search: Confirm the repository exists in the configured workspace and that the authorized user has at least member-level access.
• OAuth tokens expired: The edit page shows a warning when token validation fails. Use the re-authorize flow to refresh your credentials.

Related pages

• Integrations Overview
• Code Scanning
• Identity Management