# Installation and initial setup Implementing Diffblue Cover into your pipeline is a straightforward process. In brief, we’ll: 1. Find and configure the Diffblue Cover integration. 2. Set up a pipeline for the sample project using the GitLab pipeline editor and the Diffblue Cover pipeline template.\ Note that the [Quick Start - General](/features/cover-pipeline/cover-pipeline-for-ci/quick-start-guide-general.md) describes how to configure Diffblue Cover in CI without using the integration or pipeline template. 3. Create the full baseline unit test suite for a sample project. {% hint style="info" %} To get familiar with setting up Cover Pipeline for GitLab on a project, we'll use the Spring PetClinic sample project here to activate and configure the Diffblue Cover integration, set up a pipeline, and write a baseline unit test suite. {% endhint %} ## eLearning **Short on time?** If you'd like a fast-track experience check out our getting started video. \[5 min] {% embed url="" %} ## 1. Configure Diffblue Cover 1. Clone the sample project from the `https://github.com/diffblue/demo-spring-petclinic` Diffblue repo to your GitLab account. 2. From the project in GitLab (either the sample Spring PetClinic project, or your own project) go to **Settings > Integrations**, find **Diffblue Cover**, and click **Configure**. 3. 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**](https://www.diffblue.com/try-cover/gitlab) 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. [](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) [![](/files/DyspZobigEuYPnO9qZg1)](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html) [![](/files/Hi7Sw3G16K6i9VYpCAuj)](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) {% hint style="info" %} 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. {% endhint %}
4. When you're done, click **Save changes** to apply your updates. Your Diffblue Cover integration is now **Active** and ready for use in your project. ## 2. Set up a pipeline Here we'll create a merge request pipeline for the project that will download the latest version of Diffblue Cover, build the project, write Java unit tests for the project, and commit the changes to the branch. 1. From the project in GitLab go to **Build > Pipeline editor** and click **Configure pipeline** to create/edit the `.gitlab-ci.yml` file. 2. Copy the sample template below and paste this into the editor over-writing the default template created by GitLab. {% hint style="info" %} When using the Diffblue Cover pipeline template below with your own project and existing pipeline file, add the Diffblue template content to your file and modify as needed - see [Configuration](/features/cover-pipeline/cover-pipeline-for-gitlab/configuration.md) for details. {% endhint %} 3. When we commit these changes we'll use the commit to create a new branch **and** create a new merge request. So **before** you click **Commit**, update the following: * Update the **Commit message** with an appropriate description such as "`Update .gitlab-ci.yml file`". * Update the **Branch** field with an appropriate name such as "`add-diffblue-cover-pipeline`". * Check/tick **Start a new merge request**. 4. When you're ready, click **Commit changes** and go to [#3.-create-the-baseline-unit-test-suite](#3.-create-the-baseline-unit-test-suite "mention") below. For reference, an example Diffblue Cover pipeline template is shown below. {% code fullWidth="false" %} ```yaml # 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 tags. # To use a specific release version, use one of the yyyy.mm.dd-jdk tags. image: diffblue/cover-cli:latest-jdk17 # Diffblue Cover currently test creation 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. # If a simple maven or gradle build is insufficient for your project, please # build the project here and remove the build argument from the next step # custom built command here # 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 # build - build the project # validate - remove non-compiling and failing tests # create - create new tests for your project # For detailed information on Cover CLI commands and options, see # https://docs.diffblue.com/features/cover-cli/commands-and-arguments - dcover ci activate build validate create # 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. ``` {% endcode %} ## 3. Create the baseline unit test suite 1. On the **New merge request** screen, update **Title** with an appropriate merge request title such as `Add Cover pipeline and create baseline unit test suite`.
2. When you're ready, click **Create merge request**. 3. The merge request pipeline will now run Diffblue Cover to create the baseline unit test suite for the project. Once complete, go to the `src/test` folders in the project repo to see the unit tests created by Diffblue Cover (suffixed with `*DiffblueTest.java`). ## Subsequent code changes When performing subsequent code changes to a project, the merge request pipeline will run Diffblue Cover but will only update the associated tests. The resulting diff can then be analyzed to check the new behavior, catch regressions, and spot any unplanned behavioral changes to the code. This workflow is illustrated further in [GitLab workflow](/features/cover-pipeline/cover-pipeline-for-gitlab/gitlab-workflow.md).
## Next steps This topic demonstrates some of the key features of Cover Pipeline for GitLab and how to use the integration within a pipeline. The wider and deeper functionality, provided through `dcover` commands in the pipeline template, can be implemented to extend your unit test capabilities even further. When using the Diffblue Cover pipeline template with your own project and existing pipeline file, add the Diffblue template content to your file and modify as needed - see [Configuration](/features/cover-pipeline/cover-pipeline-for-gitlab/configuration.md) for details. Note that only specific `dcover` commands and arguments are currently supported for use with Cover Pipeline for GitLab, as detailed in [Configuration](/features/cover-pipeline/cover-pipeline-for-gitlab/configuration.md). Once you're familiar with the topics covered under [Cover Pipeline for GitLab](/features/cover-pipeline/cover-pipeline-for-gitlab.md), check out the [Related topics](/features/cover-pipeline/cover-pipeline-for-gitlab/related-topics.md) to expand your knowledge further. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://cover-docs-preview.diffblue.com/features/cover-pipeline/cover-pipeline-for-gitlab/installation-and-initial-setup.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.