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

## 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).