Bitbucket Data Center Integration - Backline Documentation

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.

Looking for Bitbucket Cloud? See the Bitbucket Cloud integration instead.

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

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 below.

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 below.

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:

helm upgrade backline backline/backline \
  --namespace backline \
  --reuse-values \
  --set gitproxy.enabled=true

Verify the pod is running:

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.

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.

Base64-encode your CA certificate

Encode the CA certificate (PEM) that signs your Bitbucket server’s certificate into a single line:

base64 -w0 ca.pem > ca.b64                 # Linux
# macOS / portable:
base64 < ca.pem | tr -d '\n' > ca.b64

Provide it to the agent

Upgrade your Backline release with the encoded CA via customCaCert:

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.

Verify and retry

Confirm the agent pod is Running, then retry Test Connection:

kubectl get pods -n backline -l app=gitproxy

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.

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

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.

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

Connecting Bitbucket Data Center

Navigate to Integrations

In Backline, go to the Integration Hub from the main menu.

Select Bitbucket Data Center

Find and click Connect on the Bitbucket Data Center integration card.

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)

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.

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:

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

Upgrading the On-Prem Agent

helm repo update
helm upgrade backline backline/backline \
  --namespace backline \
  --reuse-values

Troubleshooting

On-prem git pod is in CrashLoopBackOff

Verify gitproxy.enabled is set and the accessKey is configured:
```
helm get values backline -n backline
```

View the pod logs for specific error messages:

kubectl logs -n backline -l app=gitproxy --previous

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:

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

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. The agent rolls out automatically with the new setting.

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, then retry Test Connection.

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

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

For additional help, contact support@backline.ai.

​Overview

​What You Can Do

​Prerequisites

​Network Requirements

​Enabling On-Prem Git Support

​Routing through a corporate proxy

​Trusting an Internal CA

​Creating an HTTP Access Token

​Connecting Bitbucket Data Center

​After Connection

​Known Limitations

​Managing the Integration

​Testing Connections

​Upgrading the On-Prem Agent

​Troubleshooting

Overview

What You Can Do

Prerequisites

Network Requirements

Enabling On-Prem Git Support

Routing through a corporate proxy

Trusting an Internal CA

Creating an HTTP Access Token

Connecting Bitbucket Data Center

After Connection

Known Limitations

Managing the Integration

Testing Connections

Upgrading the On-Prem Agent

Troubleshooting