Bitbucket Data Center Integration

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 every repository the token can write to on your Bitbucket Data Center server, or only the projects you name
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 repository write access to the repositories Backline should manage
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 write access to the repositories you want to manage, and an HTTP access token for authentication.

Grant Project Permissions

Ensure the user has Repository write (REPO_WRITE) on every repository Backline should manage (project-level Repository write covers a whole project). Repositories the user can only read are skipped.

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 a dedicated user for Backline with write access only where Backline should open pull requests. To narrow a connection further, name project keys on it.

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 Keys (optional) — Comma-separated project keys (e.g., PAY, CORE) to limit this connection to those projects. Leave empty to cover every project the token can write to.

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.

Bitbucket Data Center 8.0 or newer is required. Connections that cover the whole server or several projects need the current Backline on-prem agent. The agent updates automatically; until it has, the connection test reports that the agent is outdated, so retry a few minutes later. A connection limited to a single project works on any agent version.

After Connection

Once connected, Backline covers every repository the token can write to on the server, or only those in the named projects. New projects and repositories the token gains write access to are picked up at the next daily refresh. Connections created before project keys became optional keep the project they named until you clear the Project Keys field. 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

Changing the Project Filter

Open the integration details by clicking Configure on the Bitbucket Data Center integration card
Click the three dots menu on the connection and select Edit Connection
Edit Project Keys (or clear it to cover the whole server) and save. You don’t need to re-enter the token. Backline re-lists the repositories right away and keeps the previous filter if the listing fails or finds no repositories.

Connecting a Second Server

Each Bitbucket Data Center server is its own connection. Click Configure on the Bitbucket Data Center integration card, then click Add Connection at the bottom of the integration details and enter the second server’s details. Connections are listed by server URL, and each can be edited, tested or disconnected from its own row. A connection’s server URL cannot be changed to a different server, nor from http:// to https:// (that would rebuild every repository URL). Disconnect the connection and add a new one instead.

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 write access to at least one repository the connection covers (all projects, or the named Project Keys)

Test Connection reports that the on-prem agent is outdated

The message “the on-prem Backline agent is outdated and cannot complete this request; the agent updates automatically, please retry in a few minutes” means the connection covers the whole server or several projects, and the agent in your cluster does not support that yet. It can also appear when you connect or change Project Keys; nothing is saved in that case. The agent updates on its own; retry after a few minutes, or run the upgrade under Upgrading the On-Prem Agent.

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 connection covers the repository’s project (the Project Keys field is empty or names that 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.

Get Started

Settings

Integrations

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

Changing the Project Filter

Connecting a Second Server

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

​Changing the Project Filter

​Connecting a Second Server

​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

Changing the Project Filter

Connecting a Second Server

Testing Connections

Upgrading the On-Prem Agent

Troubleshooting