> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pensar.dev/console/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pensar.dev/console/_mcp/server.

# Bitbucket

> Connect your Bitbucket workspace to Pensar Console

# Bitbucket Integration

Pensar Console integrates with Bitbucket Cloud to scan and secure your repositories. The integration uses OAuth to provide secure access to your Bitbucket workspace.

## Prerequisites

Before connecting Bitbucket, ensure you have:

1. **A Bitbucket account** with access to the repositories you want to scan
2. **Admin access** to the Bitbucket workspace you want to connect

## Connecting Bitbucket

### From Workspace Settings

1. Navigate to **Settings** → **Integrations** → **Source control** in your Pensar Console workspace
2. Find the **Bitbucket** row
3. Click **Connect**
4. Enter your **Bitbucket workspace slug** in the form (find it in your Bitbucket URL: `bitbucket.org/<workspace-slug>/…`), then click **Connect to Bitbucket**
5. You'll be redirected to Bitbucket's authorization page
6. Review the permissions and click **Grant access**
7. You'll be automatically redirected back to Pensar Console

> **Note**
>
> The workspace slug is required before the OAuth redirect — it tells Pensar which Bitbucket workspace to clone repositories from.

### From Onboarding

When creating a new workspace, you can connect Bitbucket during the onboarding process by clicking **Connect your Bitbucket workspace**, entering your workspace slug, and following the same steps.

> **Note**
>
> Pensar will automatically set up webhooks in your Bitbucket workspace to receive notifications about repository events.

## Permissions

When you authorize Pensar, the following permissions are granted:

| Permission              | Purpose                                            |
| ----------------------- | -------------------------------------------------- |
| **Read repositories**   | Access repository contents for security scanning   |
| **Write repositories**  | Create commits for auto-remediation                |
| **Read pull requests**  | View pull request information                      |
| **Write pull requests** | Create and manage pull requests for security fixes |
| **Read webhooks**       | View existing webhook configurations               |
| **Write webhooks**      | Set up webhooks for real-time notifications        |

## Adding Repositories

After connecting Bitbucket, attach repositories directly to your workspace:

1. Go to **Attack Surface** → **Repositories** in Pensar Console
2. Click **Add repository**
3. Your Bitbucket repositories appear in the picker — select one or more
4. Click **Attach & continue**

Each repository you attach is connected to the workspace and **recon / attack-surface analysis launches automatically** — there is no separate project to create.

## Managing the Integration

### Viewing Connection Status

1. Navigate to **Settings** → **Integrations** → **Source control**
2. Find the **Bitbucket** row
3. If connected, you'll see a confirmation with your workspace name

### Unlinking Bitbucket

To remove the Bitbucket integration:

1. Navigate to **Settings** → **Integrations** → **Source control**
2. Find the **Bitbucket** row
3. Click **Unlink**

> **Warning**
>
> Unlinking Bitbucket will prevent Pensar from scanning Bitbucket repositories. Any repositories attached to your workspace from Bitbucket will no longer be able to perform scans.

## Linking a pull request you opened

Put the finding's label in the pull request title or description, for example `VULN-000044`. Pensar tracks that pull request on the finding, including when it already tracks one it opened. Editing the title or description to add the label does the same thing. Removing the label leaves the link in place. Bitbucket does not say which fields an update changed, so once a finding has moved on from a pull request, later updates to that pull request don't move it back. An issue update can also set `pullRequest` to an http(s) URL, or to `null` to clear it. The URL is not specific to Bitbucket.

On the finding, **Link pull request** on the patch row accepts a URL for the same result.

## Troubleshooting

### Authorization Failed

If the OAuth authorization fails:

1. Ensure you have admin access to the Bitbucket workspace
2. Double-check the workspace slug you entered matches your Bitbucket URL
3. Try clearing your browser cache and cookies
4. Attempt the connection again from **Settings** → **Integrations** → **Source control**

### Repositories Not Appearing

If your repositories don't appear in the **Add repository** picker:

1. Verify you have at least read access to the repositories in Bitbucket
2. Check that the correct workspace is connected
3. Try refreshing the page

### Webhook Issues

If you're not receiving real-time updates:

1. Navigate to your Bitbucket workspace settings
2. Go to **Webhooks**
3. Verify a Pensar webhook exists and is active
4. If the webhook is missing, disconnect and reconnect the integration

## Need Help?

If you encounter issues setting up your Bitbucket integration, please contact our support team at [team@pensar.dev](mailto:team@pensar.dev).