Configuration

There are four key components for configuring Cover Pipeline for GitLab:

• Labels: Pre-defined Diffblue Cover project labels to determine test requirements on merge requests (full baseline, update, or skip).

• Integration Config: Direct license key and access token config using the Diffblue Cover integration page on GitLab.

• Pipeline Config: Configure the Diffblue Cover section of your pipeline including Cover version, build config, and Cover commands to execute on merge requests.

• Masked Variables: Define the Diffblue Cover license key and GitLab access token using GitLab masked variables. This avoids the need to configure the integration directly from the GitLab Integrations page.

Labels

When writing tests, Diffblue Cover will respond to specific project labels:

• Diffblue Cover: Baseline Used to mark a merge request as requiring a full suite of tests to be written. This overrides the default behavior where Cover will only write tests related to the code changes already in the merge request. The baseline label is applied automatically when running Diffblue Cover for the first time on a project (to create the initial baseline test suite). On subsequent runs, you can select this label within a merge request, if required - useful when you want to refresh your entire test suite, such as when new product enhancements are released (to update the entire test suite with the latest enhancements).

• Diffblue Cover: Skip Used to mark a merge request as requiring no tests to be written. The skip label is useful when performing merge requests that have no impact on unit tests, such as updates to comments only.

These labels are created automatically in GitLab when running Diffblue Cover for the first time on a project.

Integration config

You can configure the Diffblue license key and associated GitLab access token directly, using the Diffblue Cover integration page on GitLab. Note that, if preferred, you can use GitLab masked variables to define these properties - see Masked variables.

1. From your project in GitLab go to Settings > Integrations, find Diffblue Cover, and click Configure.

2. In the configuration screen, update the following (some items may be pre-selected):

• Check/tick the Active box.

• Enter your Diffblue Cover License key provided in your welcome email or by your organization. If needed, click the Try Diffblue Cover link to sign up for a free trial.

• Enter details of your GitLab access token (Name and Secret) to allow Diffblue Cover to access your project. In general, use a GitLab Project Access Token with a Developer role, plus api and write_repository scopes/permissions. If necessary you can use Group Access or Personal Access Tokens, again with api and write permissions. See the GitLab docs links below for full details on how to create an access token.

Using an access token with excessive permissions is a security risk. If you use a Personal access token, consider creating a dedicated user with access limited to just the project, minimizing the impact of the token being leaked.

1. When you're done, click Save changes to apply your updates. Your Diffblue Cover integration is now now Active and ready for use in your projects.

Pipeline config

Update or create the .gitlab-ci.yml file for your project to configure the Diffblue Cover section of your CI/CD pipeline.

1. From your project in GitLab go to Build > Pipeline editor and click Configure pipeline to create/edit the .gitlab-ci.yml file.

2. In the editor, click Browse templates and search for the Diffblue Cover pipeline template file. Copy the contents of this file (sample below) to your project .gitlab-ci.yml pipeline file, and update if needed. Configurable properties are listed below - for everything else, please leave these set to the values defined in the Diffblue template.

Property	Description
image	Select the Cover CLI docker image to use with your CI tool. Tag variations are provided for each supported JDK version - see https://hub.docker.com/r/diffblue/cover-cli for details. To use the latest version of Diffblue Cover, use one of the latest-jdk tags. To use a specific release version, use one of the yyyy.mm.dd-jdk tags.
script (build command)	Diffblue Cover requires the project to be built before creating any tests. Either specify the build command here (Maven and Gradle examples provided in the template) or provide pre-built artifacts via a job dependency.
script (dcover commands)	Diffblue Cover commands and options to run. Core example provided in the template: dcover – the core Diffblue Cover command. ci – enable the GitLab CI/CD integration. activate - activate the license key. validate - remove non-compiling and failing tests. create - create new tests for the project. --maven – use the Maven build tool. Configurable components: Additional optional arguments can be used with the validate and create commands - see the Commands & Arguments topic for details. The --maven options can be changed to --gradle to specify the Gradle build tool, if appropriate. Cover Reports commands and arguments are not currently supported for use with Cover Pipeline for GitLab.

For reference, the Diffblue Cover pipeline template is shown below. Note that this is a sample only - use the file provided in the GitLab templates repo to ensure that you have the latest version.

# This template is provided and maintained by Diffblue.
# You can copy and paste this template into a new `.gitlab-ci.yml` file.
# This template is designed to be used with the Cover Pipeline for GitLab integration from Diffblue.
# It will download the latest version of Diffblue Cover, build the associated project, and
# automatically write Java unit tests for the project.
# Note that additional config is required:
# https://docs.diffblue.com/features/cover-pipeline/cover-pipeline-for-gitlab
# You should not add this template to an existing `.gitlab-ci.yml` file by using the `include:` keyword.
#
# To contribute improvements to CI/CD templates, please follow the Development guide at:
# https://docs.gitlab.com/ee/development/cicd/templates.html
# This specific template is located at:
# https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Diffblue-Cover.gitlab-ci.yml

variables:
  # Configure the following via the Diffblue Cover integration config for your project, or by
  # using CI/CD masked Variables.
  # For details, see https://docs.diffblue.com/features/cover-pipeline/cover-pipeline-for-gitlab

  # Diffblue Cover license key: DIFFBLUE_LICENSE_KEY
  # Refer to your welcome email or you can obtain a free trial key from
  # https://www.diffblue.com/try-cover/gitlab

  # GitLab access token: DIFFBLUE_ACCESS_TOKEN, DIFFBLUE_ACCESS_TOKEN_NAME
  # The access token should have a role of Developer or better and should have
  # api and write_repository permissions.

  # Diffblue Cover requires a minimum of 4GB of memory.
  JVM_ARGS: -Xmx4g

stages:
  - build

diffblue-cover:
  stage: build

  # Select the Cover CLI docker image to use with your CI tool.
  # Tag variations are produced for each supported JDK version.
  # Go to https://hub.docker.com/r/diffblue/cover-cli for details.
  # Note: To use the latest version of Diffblue Cover, use one of the latest-jdk<nn> tags.
  # To use a specific release version, use one of the yyyy.mm.dd-jdk<nn> tags.
  image: diffblue/cover-cli:latest-jdk17

  # Diffblue Cover currently only supports running on merge_request_events.
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'

  # Diffblue Cover log files are saved to a .diffblue/ directory in the pipeline artifacts,
  # and are available for download once the pipeline completes.
  artifacts:
    paths:
      - "**/.diffblue/"

  script:

    # Diffblue Cover requires the project to be built before creating any tests.
    # Either specify the build command here (one of the following), or provide
    # prebuilt artifacts via a job dependency.

    # Maven project example (comment out the Gradle version if used):
    - mvn test-compile --batch-mode --no-transfer-progress

    # Gradle project example (comment out the Maven version if used):
    # - gradle testClasses

    # Diffblue Cover commands and options to run.
    #   dcover – the core Diffblue Cover command
    #   ci – enable the GitLab CI/CD integration via environment variables
    #   activate - activate the license key
    #   validate - remove non-compiling and failing tests
    #   create - create new tests for your project
    #   --maven – use the maven build tool
    # For detailed information on Cover CLI commands and options, see
    # https://docs.diffblue.com/features/cover-cli/commands-and-arguments
    - dcover
        ci
        activate
        validate --maven
        create --maven

    # Diffblue Cover will also respond to specific project labels:
    #   Diffblue Cover: Baseline
    #     Used to mark a merge request as requiring a full suite of tests to be written.
    #     This overrides the default behaviour where Cover will only write tests related
    #     to the code changes already in the merge request. This is useful when running Diffblue
    #     Cover for the first time on a project and when new product enhancements are released.
    #   Diffblue Cover: Skip
    #     Used to mark a merge request as requiring no tests to be written.

Masked variables

You can configure the Diffblue license key and associated GitLab access token using GitLab masked variables. Note that, if preferred, you can configure these properties directly, using the Diffblue Cover integration page on GitLab - see Integration config.

You only need to create these variables once - group variables can be used across all projects, project variables can be used within an individual project.

To add or update variables in the project or group settings (also see the Variables GitLab docs topic if needed):

1. In your group or project go to Settings > CI/CD and expand the Variables section.

2. Select Add variable and create each variable:

   • Key: Name of the variable. The three Diffblue variables to create are DIFFBLUE_LICENSE_KEY, DIFFBLUE_ACCESS_TOKEN_NAME, and DIFFBLUE_ACCESS_TOKEN. Note that offline licenses can also optionally be configured via environment variables, see below.

   • Value: Value for the variable:

     • DIFFBLUE_LICENSE_KEY - enter your Diffblue Cover License Key provided in your welcome email or by your organization.

     • DIFFBLUE_ACCESS_TOKEN_NAME, and DIFFBLUE_ACCESS_TOKEN - enter details of your GitLab access token (Name and Secret) to allow Diffblue Cover to access your project. In general, use a GitLab Project Access Token with a Developer role, plus api and write_repository permissions. If necessary you can use Group Access or Personal Access Tokens, again with api and write permissions. See the GitLab docs links below for full details on how to create an access token.

     

     • Optional: Note that if you have an offline license and wish to configure the offline license activation file this can be done by using the environment variable DIFFBLUE_OFFLINE_LICENSE_ACTIVATION_FILE_CONTENTS containing the contents of your offline license activation file ls_activation.lic

   • Type: Set to Variable.

   • Environment scope: Optional. All, or specific environments.

   • Protect variable Optional. If selected, the variable is only available in pipelines that run on protected branches or protected tags.

   • Mask variable Select this option. This will mask the variable’s Value in job logs.

After you create a variable, you can use it in your .gitlab-ci.yml file or in job scripts.

Using an access token with excessive permissions is a security risk. If you use a Personal access token, consider creating a dedicated user with access limited to just the project, minimizing the impact of the token being leaked.

Log files

Diffblue Cover log files are saved to a .diffblue/ directory in the pipeline artifacts (as defined in the .gitlab-ci.yml file), and are available for download once the pipeline completes. These logs include user logs (also output during the run and visible in the job output) and support logs (if you ever require Diffblue support).