Onboard Bitbucket repositories to an existing Polaris application

Black Duck Polaris Platform

This procedure describes how to onboard one or more Bitbucket repositories to a single existing Polaris application. Each Bitbucket repository you select is mapped to a new Polaris project within that application.

Before you begin, review Integrate Bitbucket with Polaris. If you're using Bitbucket Data Center, that topic explains how to make sure Polaris has network access to your Bitbucket instance.

Important:

Bulk SCM integration with Bitbucket Cloud requires a Polaris Premium subscription.

Note: SCA Fix Pull Requests are supported for repositories hosted in Bitbucket Cloud and Bitbucket Data Center. For Bitbucket Data Center integrations, Polaris creates the pull request over the Secure Tunnel that connects it to your repository. See SCA Fix Pull Requests.

Bitbucket Data Center: Create an HTTP access token

Authentication between Bitbucket Data Center and Polaris uses an HTTP access token (personal access token) that you create in Bitbucket. Follow the steps below or the instructions in the Bitbucket Data Center documentation: HTTP access tokens > Create HTTP access tokens.

  1. Log in to Bitbucket Data Center.
  2. Select the profile icon (near the upper-right corner of the screen) and open Manage account.
  3. On the left tab, click HTTP access tokens and click Create token.
  4. Name your token.
  5. Set Project permissions to PROJECT_ADMIN.
    Note: The required repository permissions (Repository Admin) are automatically inherited from the project permissions.
  6. Set the token's expiration date. To avoid issues, we recommend Do not expire.
Important: Store your token in a secure location. Each time you modify an integration, you will need to reenter the token to save your changes.

Creating an API token

When integrating SCM repositories, you will need an API token you create in Bitbucket Cloud (Premium).

Authentication between Bitbucket Cloud and Polaris is managed with an API token that you create in Bitbucket Cloud. For additional information: Create an API token.

Important: Must be created in Bitbucket Cloud (Premium). Standard and Free versions does not allow users to create webhooks.
Important: Token must be created by a Bitbucket Cloud Organization Owner or users with the "Manage organization webhooks" permission, who are authorized to manage organization webhooks. Although other Bitbucket Cloud users may be able to select the scope requirements when creating a token, the token will not work due to permission requirements in Bitbucket to manage organization webhooks.
Note: App passwords have been deprecated for Bitbucket Cloud. Existing projects integrated using App Password will continue to work until the password expires or Atlassian ends support. After your App Password stops working or if creating a new integration, use API tokens.
  1. Select the Settings gear icon in the upper-right corner of the top navigation bar.
  2. Under Personal settings, select Atlassian account settings.
  3. From the Atlassian Account page, select the Security tab on the top navigation bar.
  4. Select Create and manage API tokens.
  5. Select Create API token with scopes.
  6. Give the API token a name and an expiry date. 365 days is recommended, select Next.
  7. Select Bitbucket as the app and select Next.
  8. Select the scopes:
    • read:user:bitbucket
    • read:webhook:bitbucket
    • read:workspace:bitbucket
    • read:project:bitbucket
    • read:repository:bitbucket
    • read:pullrequest:bitbucket
    • write:pullrequest:bitbucket
    • write:webhook:bitbucket


  9. Select Next.
  10. Select the Create token button.

    The page will display the New API token.

  11. Copy the generated API token and store it in a secure location.
    Important: Store your token in a secure location. Each time you modify a project's SCM integration, you'll need to reenter the token to save your changes.

Onboard Bitbucket repositories to an existing application

  1. On the Portfolio page, select an application by clicking its name.
  2. On the Application page, select + Create > New Project(s) with SCM.
  3. Connect to your SCM:
    1. Select the type of server hosting your repositories:
      • Cloud-hosted — for Bitbucket Cloud
      • Self-hosted — for Bitbucket Data Center
    2. Select Bitbucket.
    3. (Bitbucket Cloud only) Enter your Email (Bitbucket Account Email).
    4. (Bitbucket Data Center only) Enter the SCM URL of your Bitbucket Data Center instance.
    5. (Bitbucket Data Center only) If you're using the Secure Tunnel, check URL is in a private network and select a secure tunnel from the pull-down menu.
    6. Enter your Bitbucket access token under Repository Access Token.
      Note: The access token provided here will be used to complete the onboarding process and will be subject to rate limits enforced by Bitbucket.
    7. Click Test Connection.

      You should receive a Connection Successful message and the Quick Start options should be visible. If your connection test is unsuccessful, check the following:

      • That your network connection is stable.
      • That the Repository Access Token is accurate.
      • That the Repository Access Token is still valid and has not expired.
      • That you selected the correct provider for your SCM.
      • That you have authorized the access token for use outside SSO (if applicable).
      • That the teleport agent (for example, Bridge) in the private network is running and pointing at the secure tunnel. See Add and manage secure tunnels in the Polaris UI.
  4. Under the Repository Mapping heading, select Bitbucket projects or repositories to import as new Polaris projects from the pulldowns. If an arrow is next to a name, click it to view repositories within it.
    Note: Bitbucket Data Center does not support group-level webhook auto-discovery. Webhooks must be configured at the project or repository level in Bitbucket Data Center.
  5. Click Import Repositories.

    On your Portfolio page, a progress bar will track the percentage of completion.

    If the onboarding fails, an email notification will be sent to the user who initiated the onboarding. Organization Admins can monitor activity in audit logs (My Organization > Audit Logs).

    Click Cancel to cancel the import. Any repository in the process of being imported at the time of cancellation will complete in the background after the cancel is accepted, and all further onboarding will be stopped immediately. For example, if you import ten repositories and cancel at 50%, five repositories would be imported and five repositories would not.

Next steps