Skip to main content

​
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
Contact support@backline.ai to have your tenant configured for Bitbucket Data Center support.

​
Network Requirements

The Backline on-prem agent requires the following network access:
DirectionDestinationPortProtocolPurpose
Outboundadapter.backline.ai443HTTPSCommunication with Backline cloud
OutboundYour Bitbucket Data Center server443 or 7990HTTPSGit API operations
InboundNone——No inbound connections required

​
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

​
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.
1

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
2

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

1

Navigate to Integrations

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

Select Bitbucket Data Center

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

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)
4

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:
  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

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

​
Troubleshooting

  • 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
  • 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://adapter.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
  • 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
  • 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 adapter.backline.ai
For additional help, contact support@backline.ai.