Bitbucket

Connecting Bitbucket to the Praetorian Guard Platform (PGP)

This guide explains how to connect a Bitbucket workspace to PGP so you can monitor its repositories for security vulnerabilities and sensitive data exposure.

The integration supports Bitbucket Cloud (bitbucket.org) only. Bitbucket Data Center and Bitbucket Server are not supported.

Prerequisites

Before you begin, ensure you have:

• Admin access to your Bitbucket workspace
• Permission to create workspace access tokens in Bitbucket
• Access to your PGP account

Configure a Workspace Access Token

PGP connects with a workspace access token. App passwords and Connected App (OAuth consumer) credentials are not supported for new connections.

Note: Atlassian makes workspace access tokens available only on some Bitbucket Cloud plans. See Atlassian's workspace access tokens documentation.

1. Create a workspace access token in Bitbucket:
   • Go to Bitbucket Settings → Workspace settings
   • Under Security, click Access tokens
   • Click Create access token
   • Fill in the following details:
     • Name: PGP
     • Permissions: Repository: Read
2. After creating the access token, copy it to a safe place as you will not be able to access it again
3. In PGP:
   • Navigate to Integrations
   • Find and click on "Bitbucket"
   • Enter the access token in Workspace Token
   • Enter your workspace URL in Bitbucket Workspace URL (e.g., https://bitbucket.org/your-workspace)
   • Click "Connect"

PGP only reads repositories, so the token needs no other permissions. Pull request and webhook permissions are not used.

What Is Imported

• Each repository in the workspace becomes a repository asset. Forked repositories are skipped. Public repositories are marked as public.
• Workspace members and their personal repositories are not imported.

Fix Pull Requests

When Constantine finds a vulnerability, it generates a validated patch. For Bitbucket repositories, the patch is shown on the risk in PGP, and you can review it and click Copy diff to apply it yourself. PGP cannot open pull requests in Bitbucket. Opening a pull request from PGP is available only for GitHub repositories.

Webhooks

The Bitbucket integration does not use webhooks, and you do not need to configure any in Bitbucket. PGP finds new repositories the next time the integration runs.

Verifying the Connection

To verify that your connection is working:

1. Navigate to Assets in PGP
2. Look for repositories from your Bitbucket workspace
3. Check the Integrations page to see your connected Bitbucket account

Troubleshooting

Common issues and solutions:

• "Enter a valid Bitbucket workspace URL": Use the form https://bitbucket.org/your-workspace.
• "Bitbucket rejected the supplied access token or Connected App credentials": Ensure your workspace access token is valid and hasn't expired or been revoked.
• "The Bitbucket credentials authenticated successfully but cannot access workspace '…'": Verify the token was created in that workspace and has Repository: Read.

If you continue to experience issues, contact PGP Support.

Multiple Workspaces

You can connect multiple Bitbucket workspaces to PGP. Repeat the connection process with a token from each workspace you want to monitor.

Managing Your Connection

To manage your Bitbucket connection:

1. Go to Settings → Integrations
2. Find your Bitbucket connection
3. Use the options menu (⋮) to:
   • View connection details
   • Update settings
   • Remove the connection

Additional Resources

• Bitbucket Workspace Access Tokens
• About Bitbucket Workspace Management

Need help? Contact our support team for assistance.