LogoLogo
diffblue.comFree trial
  • Discover Diffblue Cover
  • Get Started
    • What is Diffblue Cover?
    • Get started
      • Free trial
      • Get started - Cover Plugin
      • Get started - Cover CLI
      • Get started - Cover Pipeline
      • Get started - Cover Reports
    • Specs & Reqs
    • Reference Deployments
    • Licensing
      • Online license activation
      • Offline license activation
      • Diffblue License Manager
    • Update Cover
    • FAQs
    • Diffblue Learning
      • Get started
        • Just the basics
        • Free trial
        • Cover Plugin (IDE)
        • Cover CLI (Command Line)
      • Developer
        • Unit tests (IDE)
        • Unit tests (CLI)
        • Test coverage
      • DevOps
        • GitHub
        • GitLab
        • Other CI
      • Administrator
        • Admin - IntelliJ
        • Admin - CLI
        • Admin - Reports
      • Test coverage
        • Developer
        • Senior developer
        • Cover Reports Administrator
  • EVALUATION & ONBOARDING
    • Proof of Value
    • Jumpstart
      • Prerequisites for onboarding
      • Phase 1: Up and running
        • Module 1: Create your Cover unit test baseline
        • Module 2: Cover Pipeline CI integration
      • Phase 2: Developer productivity
        • Module 3: Getting started using Cover
        • Module 4: Introduction to Cover Reports
      • Phase 3: Advanced topics
        • Module 5: Speed up your test execution
        • Module 6: Getting more from Cover
  • Features
    • Cover Plugin
      • Writing tests
        • Gutter icons
        • Menu options
        • Run configurations
        • Cover Plugin tool window
        • Test Review
        • Test examples
        • Creating partial tests
        • Creating skeleton tests
        • Covering all enum values
        • Test insertion order
        • Diffblue Sandbox
        • Environment Check Cache
      • Project configuration
        • General dependencies
        • Test framework dependencies
      • Cover Plugin settings
        • Test Naming
        • Test Formatting
        • Spring configuration options
        • Method Annotations
        • Test Directory
        • Reset Cover Plugin settings
      • Cover Plugin admin
        • Core Maintenance
        • Cover Plugin toolbar menu
        • Cover Plugin status bar widget
        • Telemetry
        • Memory management
        • Using SonarQube with Cover Plugin
        • Log files
        • Troubleshooting
    • Cover CLI
      • Writing tests
        • Command summary
        • Test examples
        • Creating partial tests
        • Customizing test inputs
        • Customizing test setup
        • Test naming
        • Test formatting
        • Test insertion order
        • Patch files
        • Diffblue Sandbox
        • Operational behaviors
        • Test validation
      • Project configuration
        • Preflight checks
        • General dependencies
        • Test framework dependencies
        • Compiling your project successfully
          • Building a Maven project
          • Building a Gradle project
        • Configuring Cover to work with your project's build system
          • Quick guide
          • Configuration file in detail
          • Getting Started with Ant Projects
          • Default configuration
        • Mocking using Mockito
        • Spring profiles
        • Runtime environment
      • Commands & Arguments
        • Environment configuration for CI
        • Packages, classes, and methods
        • Quoting command line arguments
        • Argument files
      • Cover CLI admin
        • Core Maintenance
        • Telemetry
        • Memory management
        • Using Cover CLI in Eclipse
        • Using SonarQube with Cover CLI
        • Log files
        • Troubleshooting
      • Environment Configuration
    • Cover Pipeline
      • Cover Pipeline for CI
        • Quick Start - General
        • Quick Start - Jenkins
        • Quick Start - Azure Pipelines
        • Quick Start - AWS Codebuild
        • Integrating Diffblue Cover into CI on pull requests
        • Installation - VMs or CI run
      • Cover Pipeline for GitLab
        • Introduction
        • Installation and initial setup
        • GitLab workflow
        • Configuration
        • Troubleshooting
        • Related topics
      • Cover Pipeline for GitHub
        • Introduction
        • Installation and initial setup
        • GitHub workflow
        • Configuration
        • Troubleshooting
        • Related topics
    • Cover Reports
      • Cover Reports Contributor
        • Java project config (JaCoCo)
        • Generate and upload reports bundles
        • Authenticated uploads
      • Cover Reports User
        • Navigation
        • Dashboards
        • Telemetry data
        • Export API
        • Considerations
      • Cover Reports Administrator
        • Install and update Cover Reports
        • Configuration options
        • Database backup
        • SSO with Cover Reports
        • Uninstall Cover Reports
    • Cover Optimize
      • Get started - Cover Optimize
      • Cover Optimize & Gradle
      • Cover Optimize & Maven
      • Patch files
    • Cover Refactor
      • Get started - Cover Refactor
    • Cover Annotations
      • Mocking Annotations
      • Custom Input Annotations
      • Interesting Value Annotations
    • Output Codes
      • E - Environment Codes
      • L - License Codes
      • R - Reason Codes
      • T - Testability Codes
      • V - Validation Codes
      • Working with output codes
        • Working with code E020
        • Working with codes E057 to E065
        • Working with code E085
        • Working with code R005
        • Working with code R006
        • Working with code R008
        • Working with code R011
        • Working with code R012
        • Working with code R013
        • Working with code R026
        • Working with code R031
        • Working with code V003
    • Tutorials
      • How to measure test quality
      • How to improve code coverage
      • How to test a new feature
      • How to find regressions
      • How to use Diffblue Cover in test driven development (TDD)
      • How to write tests for Kotlin projects
      • Examples of tests created by Diffblue Cover
      • Best practices for testing private methods
  • Updates & Upgrades
    • Update Cover
    • Cover Editions
    • What's new
    • Release archive
      • 2025-05-01
      • 2025-04-02
      • 2025-04-01
      • 2025-03-02
      • 2025-03-01
      • 2025-02-02
      • 2025-02-01
      • 2025-01-02
      • 2025-01-01
      • 2024-12-02
      • 2024-12-01
      • 2024-11-02
      • 2024-11-01
      • 2024-10-02
      • 2024-10-01
      • 2024-09-02
      • 2024-09-01
      • 2024-08-02
      • 2024-08-01
      • 2024-07-04
      • 2024-07-03
      • 2024-07-01
      • 2024-06-02
      • 2024-06-01
      • 2024-05-02
      • 2024-05-01
      • 2024-04-02
      • 2024-04-01
      • 2024-03-02
      • 2024-03-01
      • 2024-02-02
      • 2024-02-01
      • 2024-01-02
      • 2024-01-01
      • 2023-12-02
      • 2023-12-01
      • 2023-11-03
      • 2023-11-02
      • 2023-11-01
      • 2023-10-02
      • 2023-10-01
      • 2023-09-02
      • 2023-09-01
      • 2023-08-02
      • 2023-08-01
      • 2023-07-03
      • 2023-07-02
      • 2023-07-01
      • 2023-06-02
      • 2023-06-01
      • 2023-05-02
      • 2023-05-01
      • 2023-04-02
      • 2023-04-01
      • 2023-03-02
      • 2023-03-01
      • 2023-02-02
      • 2023-02-01
      • 2023-01-02
      • 2023-01-01
      • 2022-12-02
      • 2022-12-01
      • 2022-11-02
      • 2022-11-01
      • 2022-10-03
      • 2022-10-02
      • 2022-10-01
      • 2022-09-02
      • 2022-09-01
      • 2022-08-05
      • 2022-08-03
      • 2022-08-02
      • 2022-08-01
      • 2022-07-02
      • 2022-07-01
      • 2022-06-02
      • 2022-06-01
      • 2022-05-02
      • 2022-05-01
      • 2022-04-02
      • 2022-04-01
      • 2022-03-02
      • 2022-03-01
      • 2022-02-02
      • 2022-02-01
      • 2022-01-02
      • 2022-01-01
      • 2021-06-02
      • 2021-02-01
  • Legal
    • Diffblue Legal
      • Diffblue End User License Agreement (EULA)
      • Cover Third Party Notices and/or Licenses
      • Privacy Notice
Powered by GitBook
On this page
  • Labels
  • Integration config
  • Pipeline config
  • Masked variables
  • Log files

Was this helpful?

Export as PDF
  1. Features
  2. Cover Pipeline
  3. Cover Pipeline for GitLab

Configuration

PreviousGitLab workflowNextTroubleshooting

Last updated 1 month ago

Was this helpful?

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

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

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

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

  • 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 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. Copy the Diffblue Cover pipeline template below Into 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.

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:

  • 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.

# 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.

  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.

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

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

Tag variations are provided for each supported JDK version - see 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.

Additional optional arguments can be used with the validate and create commands - see the topic for details.

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

Environment scope: Optional. All, or specific .

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

After you create a variable, you can use it in your file or in .

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 ).

Variables
environments
protected branches
protected tags
.gitlab-ci.yml
job scripts
Diffblue support
Try Diffblue Cover
Labels:
Integration Config:
Pipeline Config:
Masked Variables:
Commands & Arguments
https://hub.docker.com/r/diffblue/cover-cli