Bitbucket Cloud

When you want to add new integrations to your Snyk account you need to first decide the level type at which you want to install the integration.

• Group level - Add integrations to your Snyk application that will be available for your Snyk AppRisk Essentials or Snyk AppRisk Pro. If you want to set up integrations for Snyk AppRisk, use the Integrations menu at the Group level.

• Organization level - Add integrations for your Snyk application that will be available for all Snyk products, except Snyk AppRisk.

Organization level - Snyk integrations

Snyk recommends installing or migrating to the Bitbucket Cloud Application for smoother integration and to ensure long-term support.

The Bitbucket Cloud (PAT) integration lets you:

• Continuously perform security scanning across all the integrated repositories

• Detect vulnerabilities in your open-source components

• Provide automated fixes and upgrades

How to set up the Bitbucket Cloud Integration

Admin permissions are required; however, Snyk's access is ultimately limited by the permissions assigned to the App Password.

1. To give Snyk access to your Bitbucket account, set up a dedicated service account in Bitbucket with admin permissions. See the Bitbucket documentation to learn more about adding users to a workspace. The newly created user must have Admin permissions to all the repositories you need to monitor with Snyk.

2. In Snyk, go to the Integrations page, open the Bitbucket Cloud card, and configure the Account credentials.

3. In the Account credentials > Creating an app password section in Snyk, use the link Create an App password to jump to your Bitbucket Cloud account.

4. Follow the Bitbucket procedure to set up an account with the following permissions:

   • Account: Email & Read

   • Workspace membership: Read

   • Projects: Read

   • Repositories: Read & Write

   • Pull requests: Read & Write

   • Webhooks: Read & Write

   See the Bitbucket documentation for more details about the procedure.

5. Enter the username and the App Password for the Bitbucket account you created and Save your changes. You can find your username under the Bitbucket Personal settings. Snyk connects to your Bitbucket Cloud account. When the connection succeeds, the confirmation message "Bitbucket Cloud settings successfully updated" appears.

How to add Bitbucket repositories to Snyk

After you connect Snyk to your Bitbucket Cloud account, you can select repositories for Snyk to monitor.

1. In Snyk, go to Integrations > Bitbucket Cloud card, and click Add your Bitbucket Cloud repositories to Snyk to start importing repositories to Snyk.

2. Choose the repositories you want to import to Snyk and click Add selected repositories.

After you add the selected repositories, Snyk scans them for dependency files in the entire directory tree, that is, package.json, pom.xml, and so on, and imports them to Snyk as Projects.

The imported projects appear on your Projects page and are continuously checked for vulnerabilities.

Bitbucket integration features

After the integration is in place, you will be able to use capabilities such as:

• Project-level security reports

• Project monitoring and automatic fix pull requests

• Pull request testing

Project-level security reports

Snyk produces advanced security reports that let you explore the vulnerabilities found in your repositories and fix them immediately by opening a fix pull request directly to your repository, with the required upgrades or patches.

The example that follows shows a Project-level security report.

An example of a Project-level security report

Project monitoring and automatic fix Pull Requests

Snyk scans your Projects on either a daily or a weekly basis. When new vulnerabilities are found, Snyk notifies you by email and by opening automated pull requests with fixes for your repositories.

The example that follows shows a fix Pull Request opened by Snyk.

Example of an automatic fix Pull Request opened by Snyk

To review and adjust the automatic fix pull request settings:

1. In Snyk, go to Organization settings > Integrations > Source control > Bitbucket Cloud, and click Edit Settings.

2. Scroll to the Automatic fix PRs section and configure the relevant options.

Configure Automatic fix PRs

Unlike manual pull requests opened from the Bitbucket interface, Snyk pull requests are not automatically assigned to the default reviewer set in your Bitbucket Cloud account.

For more information, see Snyk automated pull requests.

Pull request tests

Snyk tests any newly-created pull request in your repositories for security vulnerabilities and sends a build check to Bitbucket Cloud. You can see directly from Bitbucket Cloud whether or not the pull request introduces new security issues.

The example that follows shows a Snyk pull request build check on the Bitbucket Cloud Pull Request page.

Example of a Snyk pull request build check on the Bitbucket Cloud Pull Request page

To review and adjust the pull request tests settings:

1. In Snyk, go to Organization settings > Integrations > Source control > Bitbucket Cloud, and click Edit Settings.

2. Scroll to Default Snyk test for pull requests > Open Source Security & Licenses, and configure the relevant options.

Configuring the options for pull request Open Source Security & Licenses

Required permission scope for the Bitbucket Cloud integration

All the operations, whether triggered manually or automatically, are performed for a Bitbucket Cloud service account that has its token (App Password) configured in the Integration settings.

For Snyk to perform the required operations on monitored repositories, such as reading manifest files on a frequent basis and opening fix or upgrade PRs, the integrated Bitbucket Cloud service account needs Admin permissions on the imported repositories.

For detailed information on the permission scopes required, see Bitbucket permission requirements.

How to disconnect Snyk from Bitbucket Cloud

When you disconnect Snyk from your repository Projects, your credentials are removed from Snyk, and any integration-specific Projects that Snyk is monitoring are deactivated in Snyk. If you choose to re-enable this integration, you must re-enter your credentials and activate your Projects.

To disconnect this integration, in Organization settings > Integrations:

1. In your list of integrations, select the Bitbucket integration you want to deactivate and click Edit settings to open a page with the current status of your integration. The page includes sections that are specific to each integration, where you can manage your credentials, API key, Service Principal, or connection details.

2. Scroll to the relevant section and click Disconnect.

Migrate to the Bitbucket Cloud App

This section describes how to migrate your existing Bitbucket Cloud Personal Access Token (PAT) integration, displayed in Snyk as Bitbucket Cloud, to the Bitbucket Cloud App integration.

To migrate to the new app integration, you must remove all the previously imported Projects from Snyk, delete the PAT integration and its Projects, set up the new app integration, and reimport your Projects to Snyk from the new integration.

Before going through the migration process, you should note that the following Project-level information will not persist:

• Historic Project-related data, including trend numbers for fixing vulnerabilities

• Project-related metadata: ignores and tags

Migration process

The migration process includes the following steps:

1. Deleting the existing Projects that are connected to the Bitbucket Cloud PAT integration in Snyk.

2. Disconnecting the PAT integration in Snyk.

3. Removing the first-party extension for the PAT integration in Bitbucket (optional).

4. Connecting the Bitbucket Cloud App and importing Projects.

Delete existing Projects

Delete all the existing Projects in Snyk that were previously imported from the Legacy integration. To use the bulk delete action on the Projects page, change the grouping filter to Group by none. You can now select multiple Projects in the list individually or by selecting the checkbox at the top to Select all visible projects. To delete a Project, select the trash icon, Delete selected projects.

Change the Projects filter to Group by none

Bulk delete the selected Projects

Disconnect the PAT integration

To disconnect the Bitbucket Cloud PAT integration, navigate to the settings page of Bitbucket Cloud integration, scroll to the relevant section, and click Disconnect.

Remove the Snyk tab for the PAT integration in Bitbucket Cloud (optional)

The Bitbucket Cloud integration has an optional first-party interface app.

This app can be installed on your Bitbucket Cloud workspace to enrich the PAT integration with a first-party interface as the "Snyk" tab)

If you have used this app, before setting up the Snyk Bitbucket Cloud App in the next step, remove the previous interface app in Bitbucket Cloud. This functionality is supported out-of-the-box in the Snyk App integration. Go to your Workspace settings page in Bitbucket.org > Manage installed apps, expand the Snyk Security for Bitbucket Cloud app, and click Remove.

Remove the first-party Snyk Legacy interface app in Bitbucket

Set up the Bitbucket Cloud App integration

See the Bitbucket Cloud App integration topic for instructions.

Migration demo

In less than five minutes, Marco Morales, a Partner Solutions Architect at Snyk, talks about the Snyk Bitbucket Cloud App and goes through the process of migrating an existing Bitbucket Cloud integration to the Snyk Bitbucket Cloud App.

Go to timestamp 2:34 to jump right into the demo.

How to migrate to the new Snyk Bitbucket Cloud App integration

Group level - Snyk AppRisk integrations

The Integrations page shows all active integrations, including data from your existing Snyk Organizations that is automatically synced and provides access to the Integration Hub.

BitBucket setup guide

Bitbucket Server and Bitbucket Cloud do not support automatic language detection. You can manually add language tags to a Bitbucket Cloud repository. After manually setting up the languages in your Bitbucket project, Snyk can automatically detect and ingest all those languages in your Snyk AppRisk application.

Pulled entities

• Users

• Repositories

Integrate using Snyk AppRisk

• Profile name (mandatory): Input your integration profile name.

You can choose to integrate using an Access Token or a Broker Token.

Use an Access Token

Use an Access Token (mandatory) to create your BitBucket PAT from your BitBucket organization.

• API URL (mandatory) - Input the API URL.

• Username (mandatory): Input the BitBucket username of your organization.

• App password (mandatory): Create an API token from your BitBucket account, with the following permissions:

  • Account - Read

  • Projects - Read

Create a BitBucket app password by following these steps:

1. Open your BitBucket account

2. Click the Settings option

3. Click the Personal BitBucket settings option

4. Navigate to the App passwords sub-section from the ACCESS MANAGEMENT section.

Use a Broker Token

Use a Broker Token (mandatory) to create and add your Broker token if you use Snyk broker for AppRisk.

• Generate your Broker token by following the instructions from the Obtain your Broker token for Snyk Broker page.

• Copy and paste the Broker token on the integration setup menu from the Integration Hub.

Common options

The following options apply to both the Access Token and the Broker token.

• Service type (mandatory): Select the service type, Cloud, or On-premises.

• Add Backstage Catalog (optional): If you want to add your Backstage catalog, follow the instructions from the Backstage file for SCM Integrations page.

API version

You can use the BitBucket REST API V2 repository to access information about the API.