Getting started: Black Duck Security App

Enable Bitbucket pipelines

The Black Duck Security App provides an interface to configure, generate and deploy a workflow file to selected repositories. Subsequently, it is necessary to ensure that Bitbucket pipelines are enabled.

Enable Bitbucket pipelines in the UI

To enable Bitbucket Pipelines for a specific repository in the Bitbucket web UI:

1. Log in to your Bitbucket account.

2. Navigate to target repository.

3. In the left-hand sidebar, navigate to Repository settings > Pipelines > Settings.

4. Toggle the option to Enable pipelines.

Bitbucket secrets and variables setup

The generated workflow file, by default references variables, secrets and a Bitbucket Token.

This section explains an overview for how to add variables, secrets and token at the workspace and repository level.

Before proceeding, ensure all requirements in the Black Duck Security Prerequisites are met.

Please refer to the appropriate platform documentation for an overview of the required secrets and variables:

• Black Duck® SCA
• Coverity
• Polaris

Workspace level configuration (recommended)

Variables specified for a workspace can be accessed from all repositories that belong to the workspace. You must be an administrator to manage workspace variables.

1. From the profile avatar menu select a workspace.

2. Select the Settings cog on the top navigation bar.

3. Select Workspace settings from the Settings dropdown menu.

4. From the sidebar menu, select Pipelines > Workspace variables

Workspace variables can be overridden by repository variables.

Workspace variables can be accessed by all users with the write permission for any repository (private or public) that belongs to the team or account.

You must be an administrator of a workspace or a repository to manage variables respectively.

Repository level configuration

Pipeline variables added at the repository level can be used by any user who has write access in the repository. To access and configure the repository variables, the user must be an admin of that repository.

From the repository, repository variables can be managed in Repository settings > Pipelines > Repository variables.

Configure Bitbucket token

Install and authorize

The Black Duck Security App for Bitbucket provides access to a central user interface where you can configure and deploy security scan workflows to selected repositories within your workspace.

Use the installer to select and configure the repositories to be onboarded from a Bitbucket workspace. On first use, the installer must be granted permission to access repositories in the selected workspace. The required permissions and configuration steps are explained below.

Install

Click the Blackduck Security Setup button to redirect to the configuration interface. Alternatively, visit the Onboarding URL and click the Bitbucket button to to log in and start onboarding.

Use the documentation link to access supporting documentation for the Black Duck Security App.

Authorize

When first accessing the Black Duck Security App, a prompt will be displayed to authorize the following permissions:

• Read your account information
• Read your workspace's project settings and read repositories contained within your workspace's projects
• Read and modify your repositories and their Pull Requests
• Read your team membership information

Click Grant access to proceed.

Onboarding process

Upon successful authentication, you'll be redirected to the Black Duck onboarding screen to select a workspace and the associated repositories where a workflow YAML file will be generated and committed as a Pull Request for running scans.

Take a moment to review the dashboard components:

1. Select repositories: Select the repositories within a workspace where configured scans will be deployed to.

2. Configure options: Configure scan options for specific Black Duck platforms such as Black Duck® SCA, Coverity and Polaris.

3. Review workflow.yml: Review a preview of the generated Bitbucket workflow that will be deployed to the selected repositories for performing a Black Duck security scan.

   Note: If a bitbucket-pipelines.yml exists, then the generated configuration will be merged into the existing yml file

4. Summary: Summarizes the count of repositories where the workflow will be deployed to. At this stage the workflow can be submitted for deployment.

Configure scan workflow

The Dashboard UI can be used to configure which repositories within a workspace a workflow will be deployed to. A workflow can be configured for the following Black Duck platforms:

• Black Duck® SCA

• Coverity

• Polaris

Step 1: Select repositories

Use the Select Repositories screen to configure which repositories within the workspace should be scanned.

1. Use the Workspace drop down list to select the workspace.

   Note: The app automatically discovers and displays repositories based on the selected workspace.
2. Select the repositories that the generated workflow should be configured and deployed to:

   Note: When a bitbucket-pipelines.yml file already exists in a repository, the generated workflow content will be merged into the existing pipeline.

   1. All repositories: Configure and deploy the workflow to all repositories within the workspace.

   2. Selected repositories: Select the repositories from a list. Use the following filter operations for assistance with repository selection:

      • Search: Filter by name or last updated time.

      • Sort: Click the Repository, Project or Last Updated column to order the repository list by name, project or date.

      • Pagination: Navigate the available repositories using the pagination buttons.

      • Show only selected: Display selected repositories in the list only.

One or more search filters can added to filter the repository list. This is achieved using the Add filters drop down list. The following filters can be combined and applied to repositories:

1. Language: Select one or more programming languages from this dropdown to filter the repository list by language.
2. Project: Select one or more projects from the dropdown list to filter repositories by project.
3. Visibility: Select either public or private to filter the repository list accordingly.

For the language filter to function correctly in the UI or for API integrations, repository administrators must manually assign a language in the repository’s settings:

1. Navigate to Repository Settings > Repository Details > Advanced

2. Select the appropriate language from the Language dropdown

3. Save changes

Only repositories with a manually defined language will appear under the language filter options. Repositories without a set language will be excluded from any specific language filter.

Step 2: Configure scan options

The Dashboard can be used to automatically generate a Bitbucket workflow file based on scan options specified in the Configure Options screen. The generated Bitbucket workflow will be deployed to the selected repositories.

The screen illustrated above highlights that the following options can be configured:

• Branches: Scans can be configured to trigger in response to push events and when a Pull Request is created or updated. Use the push events and pull request text boxes to specify which branches will initiate scans for each type of event.

• Runner: Choose the environment for the runner by specifying the tag name of the runner. If the runner is windows, the windows tag is required along with any other runner tag. Runner tags are comma-separated, for example: windows, my.runner.

• Platform: Select the Black Duck platform for scanning in the repository. Supported platforms include Coverity, Black Duck® SCA and Polaris. Upon selection, the Dashboard UI will dynamically update to display platform scan-specific options and instructions, such as which Bitbucket variables and secrets are required for the generated workflow to run successfully.

• Scan method: Choose between:

  • CLI (default): Generate a scan workflow that downloads the latest Bridge CLI and uses it directly to perform a security scan.

  • Bitbucket Pipe: Generate a scan workflow that uses Black Duck Security Scan Pipe.

    Important: Bitbucket Pipe workflows are supported by Atlassian for Linux platforms only (Bitbucket cloud and self-hosted runners).

Refer to the Black Duck platform documentation pages for further details of scan configuration options and prerequisites:

• Black Duck® SCA

• Coverity

• Polaris

Review workflow

The Review bitbucket-pipelines.yml screen allows a generated workflow to be previewed and edited before submission for deployment.

The Review bitbucket-pipelines.yml screen is illustrated below with an example generated workflow for Black Duck® SCA. Refer to the following documentation pages for sample workflow jobs generated for each Black Duck platform:

• Black Duck SCA

• Coverity

• Polaris

The remainder of this section explains the workflow review process.

The Review bitbucket-pipelines.yml screen displays a Bitbucket workflow containing a single scan job, specifically added for selected Black Duck platforms.

The workflow is automatically generated for deployment to the selected repositories and simplified to include only the minimum fields required (e.g., default values for the product scans are omitted unless specified). When a repository already contains a bitbucket‑pipelines.yml file, the new workflow content is merged into the existing file rather than replacing it.

Inline editing of the workflow is available by clicking the Edit button. The editor automatically validates the syntax, preventing saves if errors are detected. It also issues warnings for potential issues, such as hardcoded secrets or variables, which do not block saving.

Deploy workflow

The Summary screen displays the count of repositories where the bitbucket-pipelines.yml will be deployed by raising a Pull Request.

To submit a workflow for deployment across the selected repositories follow the steps below:

1. Review the deployment summary:

   Note: Check that the count of selected repositories and workflow filename (e.g., bitbucket-pipelines.yml) is as expected. Use the Previous button to navigate back to adjust if necessary.

2. The yml file will be committed as a Pull Request.

3. Click the "Submit" button and confirm deployment in the modal dialog.

4. Monitor the deployment progress in the onboarding status screen illustrated below, which will update every 10 seconds.

   Note: For repositories with branch protection rules the app automatically creates Pull Requests (PRs) to inject workflows. Review and manually merge Pull Requests using provided links to enable scans.

5. Review the Failed Repositories List for any deployment issues.

Troubleshooting and support

The table below summarizes common issues and their resolutions.