> ## Documentation Index
> Fetch the complete documentation index at: https://docs.backline.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bitbucket Data Center Integration

> Connect your self-hosted Bitbucket Data Center instance to Backline

## Overview

Backline integrates with Bitbucket Data Center (self-hosted) to automatically create pull requests that remediate known vulnerabilities in your on-prem repositories. A lightweight Backline agent runs inside your network and handles all communication using outbound-only connections — no inbound firewall rules are required.

<Note>
  Looking for Bitbucket Cloud? See the [Bitbucket Cloud integration](/integrations/bitbucket) instead.
</Note>

## What You Can Do

With the Bitbucket Data Center integration, Backline can:

* Access repositories within a Bitbucket Data Center project
* Analyze code dependencies and identify vulnerabilities
* Create pull requests with automated security fixes
* Post review comments with detailed remediation guidance
* Monitor CI/CD status on pull requests
* Track remediation status across your repositories

## Prerequisites

Before connecting Bitbucket Data Center, ensure you have:

* A Bitbucket Data Center instance accessible over your internal network
* The Backline Helm chart already installed in your Kubernetes cluster
* A Bitbucket user with project and repository read/write access
* An HTTP access token for that user

## Network Requirements

The Backline on-prem agent requires the following network access:

| Direction    | Destination                       | Port        | Protocol | Purpose                           |
| ------------ | --------------------------------- | ----------- | -------- | --------------------------------- |
| **Outbound** | `app.backline.ai`                 | 443         | HTTPS    | Communication with Backline cloud |
| **Outbound** | Your Bitbucket Data Center server | 443 or 7990 | HTTPS    | Git API operations                |
| **Inbound**  | None                              | —           | —        | No inbound connections required   |

<Note>
  The agent connects to your Bitbucket Data Center server **directly** (not through Backline cloud). If your cluster routes outbound traffic through a corporate proxy, set the proxy in your Backline values and list your Bitbucket host (or internal domain) under `proxy.noProxy` so the agent reaches it directly — otherwise the connection fails with `Bad Gateway`. See [Routing through a corporate proxy](#routing-through-a-corporate-proxy) below.
</Note>

<Note>
  If your Bitbucket Data Center server uses a TLS certificate signed by an **internal or corporate CA**, the agent must be given that CA to trust it — otherwise the connection fails with `x509: certificate signed by unknown authority`. See [Trusting an Internal CA](#trusting-an-internal-ca) below.
</Note>

## Enabling On-Prem Git Support

Bitbucket Data Center requires an additional component in your Backline deployment that handles communication with your git server. Enable it by upgrading your existing Backline release:

```bash theme={null}
helm upgrade backline backline/backline \
  --namespace backline \
  --reuse-values \
  --set gitproxy.enabled=true
```

Verify the pod is running:

```bash theme={null}
kubectl get pods -n backline -l app=gitproxy
```

You should see output similar to:

```
NAME                        READY   STATUS    RESTARTS   AGE
gitproxy-6d4f8b7c9-x2k5n   1/1     Running   0          30s
```

## Routing through a corporate proxy

If your cluster reaches the internet through a corporate HTTP(S) proxy, set it in your Backline values so the worker, gitproxy and janitor use it. List your **internal** Bitbucket host (or domain) and in-cluster addresses under `noProxy` so the agent reaches them **directly** — otherwise requests to your internal server are sent to the egress proxy and fail with `Bad Gateway`.

```bash theme={null}
helm upgrade backline backline/backline \
  --namespace backline \
  --reuse-values \
  --set gitproxy.enabled=true \
  --set proxy.httpProxy=http://proxy.company.com:3128 \
  --set proxy.httpsProxy=http://proxy.company.com:3128 \
  --set proxy.noProxy="bitbucket.company.com,.company.com,.svc,.cluster.local,10.0.0.0/8"
```

The settings are applied to the worker, gitproxy and janitor components. Leave them unset to connect directly.

## Trusting an Internal CA

If your Bitbucket Data Center server's TLS certificate is signed by an **internal or corporate CA** (not a public one), the agent must be given that CA — otherwise connections fail with `x509: certificate signed by unknown authority`. A CA *certificate* is public (not a secret), so it's safe to provide.

<Steps>
  <Step title="Base64-encode your CA certificate">
    Encode the CA certificate (PEM) that signs your Bitbucket server's certificate into a single line:

    ```bash theme={null}
    base64 -w0 ca.pem > ca.b64                 # Linux
    # macOS / portable:
    base64 < ca.pem | tr -d '\n' > ca.b64
    ```
  </Step>

  <Step title="Provide it to the agent">
    Upgrade your Backline release with the encoded CA via `customCaCert`:

    ```bash theme={null}
    helm repo update
    helm upgrade backline backline/backline \
      --namespace backline \
      --reuse-values \
      --set gitproxy.enabled=true \
      --set-file customCaCert=ca.b64
    ```

    You can also place the base64 string under `customCaCert` in your values file instead of using `--set-file`.
  </Step>

  <Step title="Verify and retry">
    Confirm the agent pod is Running, then retry **Test Connection**:

    ```bash theme={null}
    kubectl get pods -n backline -l app=gitproxy
    ```
  </Step>
</Steps>

## Creating an HTTP Access Token

Backline needs a user account with access to the project you want to manage, and an HTTP access token for authentication.

<Steps>
  <Step title="Grant Project Permissions">
    Ensure the user has the following project-level permissions:

    * **Project read** — to list and access repositories
    * **Repository write** — to create branches and push changes
  </Step>

  <Step title="Generate an HTTP Access Token">
    Log in as the user, navigate to **Manage account → HTTP access tokens**, and create a new token. Grant the token **Repository write** permission.
  </Step>
</Steps>

<Tip>
  We recommend creating a dedicated user for Backline with access only to the specific project you want to manage.
</Tip>

## Connecting Bitbucket Data Center

<Steps>
  <Step title="Navigate to Integrations">
    In Backline, go to the Integration Hub from the main menu.
  </Step>

  <Step title="Select Bitbucket Data Center">
    Find and click **Connect** on the **Bitbucket Data Center** integration card.
  </Step>

  <Step title="Enter Connection Details">
    Fill in the connection form:

    * **Server URL** — The base URL of your Bitbucket Data Center instance (e.g., `https://bitbucket.company.com`)
    * **Username** — The Bitbucket username
    * **Access Token** — The HTTP access token created in the previous step
    * **Project Key** — The Bitbucket project key containing your repositories (e.g., `PROJ`)
  </Step>

  <Step title="Connect">
    Click **Connect**. Backline will automatically test the connection to your Bitbucket Data Center instance before saving the integration. If the test fails, you'll see an error with details about what went wrong.
  </Step>
</Steps>

## After Connection

Once connected, Backline will be able to access repositories in the specified project. When vulnerabilities are detected by your connected security scanners, Backline can generate remediation plans and create pull requests with fixes for those repositories.

## Known Limitations

* **CI Job Logs** — Bitbucket Data Center does not store CI/CD job logs natively (logs reside in external CI systems like Bamboo or Jenkins). Backline can still monitor CI status and identify failed jobs, but individual job log retrieval is not available.
* **PR Branch Alignment** — Automatic merging of the target branch into a PR's source branch is not supported. Bitbucket Data Center does not provide a REST API for this operation.

## Managing the Integration

### Testing Connections

To verify that a connection is still valid:

1. Open the integration details by clicking **Configure** on the Bitbucket Data Center integration card
2. Click the **three dots menu** on the connection
3. Select **Test Connection** to validate connectivity and credentials

### Upgrading the On-Prem Agent

```bash theme={null}
helm repo update
helm upgrade backline backline/backline \
  --namespace backline \
  --reuse-values
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="On-prem git pod is in CrashLoopBackOff">
    * Verify `gitproxy.enabled` is set and the `accessKey` is configured:
      ```bash theme={null}
      helm get values backline -n backline
      ```
    * View the pod logs for specific error messages:
      ```bash theme={null}
      kubectl logs -n backline -l app=gitproxy --previous
      ```
  </Accordion>

  <Accordion title="Test Connection fails">
    * Verify the on-prem agent is running: `kubectl get pods -n backline -l app=gitproxy`
    * Test outbound connectivity to Backline cloud from the agent:
      ```bash theme={null}
      kubectl exec -n backline deploy/gitproxy -- \
        wget -q --spider https://app.backline.ai/health
      ```
    * Confirm the **Server URL** is correct and reachable from the agent's network
    * Check that the **Username** and **Access Token** are valid
    * Ensure the user has access to the specified **Project Key**
  </Accordion>

  <Accordion title="Test Connection fails with a Bad Gateway error">
    `Bad Gateway` means the agent's request to your Bitbucket server is being routed through your cluster's outbound proxy, which can't reach an internal server.

    Your Bitbucket server should be reached **directly**. Add its host (or your internal domain) to `proxy.noProxy` in your Backline values and upgrade — see [Routing through a corporate proxy](#routing-through-a-corporate-proxy). The agent rolls out automatically with the new setting.
  </Accordion>

  <Accordion title="Test Connection fails with a certificate error">
    `x509: certificate signed by unknown authority` means your Bitbucket server's TLS certificate is signed by an internal/corporate CA that the agent doesn't trust (it ships only standard public CAs).

    Provide your CA to the agent following [Trusting an Internal CA](#trusting-an-internal-ca), then retry **Test Connection**.
  </Accordion>

  <Accordion title="Pull requests are not being created">
    * Verify the user has repository write permissions
    * Check that the repository is within the configured project
    * Review the on-prem agent logs: `kubectl logs -n backline -l app=gitproxy --tail=200`
  </Accordion>

  <Accordion title="Connection was working but stopped">
    * Check that the on-prem agent is still running
    * Verify the HTTP access token has not expired
    * Confirm no network changes have blocked outbound connectivity to `app.backline.ai`
  </Accordion>
</AccordionGroup>

For additional help, contact [support@backline.ai](mailto:support@backline.ai).