Integrate a new Bitbucket Data Center/Server source

info

Throughout this page, "Bitbucket Data Center" refers to both Bitbucket Data Center and Bitbucket Server. In the app, you'll see "Data Center" as the label, which also includes Server functionality. We use "Data Center" in our wording because Bitbucket Server is deprecated and Data Center is the latest supported version by Atlassian.

caution

This integration does not support projects and repositories hosted on Bitbucket Cloud (bitbucket.org).
We are actively working on Bitbucket Cloud integration, which will be released soon. In the meantime, check out our Bitbucket Pipelines integration to keep your Bitbucket Cloud workspace secure.

Overview

GitGuardian can integrate with your Bitbucket Data Center through two mechanisms called project-level and instance-level integrations.

info

Both mechanisms require a personal access token for GitGuardian with the following scopes: Read permissions for projects and Admin permissions for repositories. This allows GitGuardian to create webhooks for receiving information on repository updates.
You will need Owner or Manager rights in GitGuardian to set up an integration or customize your settings.

GitGuardian requires a 3-hour window before synchronizing Bitbucket instance information. This could translate, at worst, to a 3-hour delay before a newly created project is monitored.

In order to keep your integration safe, SSL verification is required for integrating Bitbucket instances. All messages between GitGuardian and your Bitbucket instance will be authenticated by HMAC SHA-256.

Setup

Create a Personal Access Token

tip

We strongly recommend that you use a bot user in order to generate personal access tokens. This is because a personal access token is closely linked to the Bitbucket account that created it. If the Bitbucket account is deleted, the token it generated is also deleted.

1. Navigate to your Bitbucket user settings (typically on your upper right hand corner, under Manage Account)
2. Go to Personal access tokens section
3. Create a personal access token with a simple name such as "GitGuardian" and Read permissions on projects and Admin permissions on repositories. Set the "Automatic Expiry" option to "No".
   The personal token enables GitGuardian to create webhooks through your Bitbucket's API.
   

Please refer to the Bitbucket server documentation for more information about personal access tokens.

We advise that you never revoke the token before removing your Bitbucket integration on GitGuardian dashboard.

Instance-level integration

This integration mode will automatically monitor all projects and repositories on the instance. When a new project is created on the instance, it will be automatically monitored by GitGuardian.

Requirements

• Self-managed Bitbucket Server/Data Center: minimum assured compatible version 7.6+
• An Administrator (SYSADMIN global permission) token with Read permissions for projects and Admin permissions for repositories

Guidelines

1. Navigate to Settings > Integrations > Sources.
2. Click on Configure for Bitbucket.
3. Click on Start for the instance level option: "Monitor the entire Bitbucket instance"
4. Submit your Bitbucket instance url and the personal access token created.
   
   
   caution

   Bitbucket instance URL must be prefixed with https://, instances without a secure connection won't be monitored.
   The URL used should be of type scheme+basename (eg: https://bitbucket.gitguardian.example).

5. GitGuardian will start monitoring your Bitbucket instance. You can view the projects and repositories monitored in your Bitbucket settings page by clicking on See my Bitbucket perimeter.

Events subscription details

Our integration will subscribe to the following events:

• Repository update events
• Push events

Troubleshooting

• You can submit new personal access tokens if you want to monitor more Bitbucket instances.
• GitGuardian automatically detects if the Personal access token becomes invalid (by expiring or being revoked) and will send an email to notify you. All of your existing data will remain accessible.
• In case you have a lot of repositories, they may take a short time to show up on your perimeter page while GitGuardian sets up the necessary webhooks on each of them.

Project-level integration

This integration will only monitor projects selected by the user. When a new repository is added to a monitored project, it will be automatically monitored. However, new projects added to the instance will not be automatically monitored.

Requirements

• Self-managed Bitbucket Server/Data Center: minimum assured compatible version 7.6+
• A token with Read permissions for projects and Admin permissions for repositories. A project-level integration can be created by any user with Administrator permissions on a Bitbucket project. It does not require the user to be an Administrator of the instance.

Guidelines

1. Navigate to Settings > Integrations > Sources.
2. Click on Configure for Bitbucket.
3. Click on Start for the project level option: "Monitor only certain Bitbucket projects"
4. Submit your Bitbucket instance url and the personal access token created.
   
   
   caution

   Bitbucket instance URL_ must be prefixed with https://, instances without a secure connection won't be monitored.

5. GitGuardian will display the projects available for monitoring. Clicking Install, GitGuardian will install hooks and allow all repositories of that project to be monitored.
   
6. You can view the projects and repositories monitored in your Bitbucket settings page by clicking on See my Bitbucket perimeter.

Events subscription details

Our integration will subscribe to the following events:

• Repository update events
• Push events

Troubleshooting

• You can submit new personal access tokens if you want to monitor more Bitbucket instances or projects.
• GitGuardian automatically detects if the Personal access token becomes invalid (by expiring or being revoked) and will send an email to notify you. All of your existing data will remain accessible.
• In case you have a lot of repositories, they may take a short time to show up on your perimeter page while GitGuardian sets up the necessary webhooks on each of them.

Automatic historical scan

By default, GitGuardian performs a historical scan for each newly created Bitbucket repository added to your perimeter.

You can deactivate this behavior in your Bitbucket settings if you are a Manager of the workspace.

Customize your monitored perimeter

Once you have set up your Bitbucket integration, you have the possibility to configure which repositories to monitor in the Bitbucket settings section of your workspace.

If you deselect a repository from your monitored perimeter:

• GitGuardian will no longer receive any content of its commits
• and therefore you won't receive any alerts related to this repository.

Possible adjustments of Bitbucket Server settings

The Bitbucket Server Config properties allow you to modify some default behaviors of Bitbucket Server so that it can handle monitoring of a greater number of repositories.

Reduce the delay of webhooks (so that GitGuardian incidents do not appear late):

• plugin.webhooks.io.threads can be increase from the default 3 if the Bitbucket host has enough threads.
• plugin.webhooks.http.connection.host.max can be increased from the default 5.