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
  • Environment config
  • Workflow config
  • Log files

Was this helpful?

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

Configuration

PreviousGitHub workflowNextTroubleshooting

Last updated 8 months ago

Was this helpful?

There are three key components for configuring Cover Pipeline for GitHub:

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

  • : Direct license key and access token config.

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

Note that the Quick Start - General describes how to configure Diffblue Cover in CI without using the Diffblue Cover Pipeline Action. Further details on appropriate environment configuration that can be used in GitHub CI can also be found in Environment configuration for CI.

Labels

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

  • Diffblue Cover: Baseline Used to mark a pull 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 pull 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 pull 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 pull request as requiring no tests to be written. The skip label is useful when performing pull requests that have no impact on unit tests, such as updates to comments only.

These labels are created automatically in GitHub when running Diffblue Cover for the first time on a project, and can be selected as part of the pull request as needed.

Environment config

To configure the Diffblue license key and associated GitHub access token and permissions:

  1. In GitHub, go to Settings > Secrets and variables > Actions > Repository secrets

  2. Add a New repository secret and set Name to DIFFBLUE_LICENSE_KEY and set Secret to your Diffblue Cover license key (see Licensing, if needed).

  3. Optional: For offline license activation please add another New repository secret with Name set to DIFFBLUE_OFFLINE_LICENSE_ACTIVATION_FILE_CONTENTS and Secret set to the contents of your offline license activation file ls_activation.lic. This will then need to be passed through to the Diffblue Cover Action workflow as shown below.

  1. Finally, make sure that your repository allows actions to be executed - in the repository go to Settings > Action permissions:

Note that GitHub fine-grained access tokens are in Beta and not supported. If you must use a fine-grained access token then the following are required:

  • Contents: write

  • Pull requests: write

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.

Workflow config

Property
Description

Run Diffblue Cover uses:

Run Diffblue Cover working-directory:

This can be used to specify a different location in the repository to run Diffblue Cover.

Run Diffblue Cover args:

Diffblue Cover commands and options to run. Default arguments are shown commented out in the template:

ci – enable the Diffblue Cover Action.

activate - activate the license key.

build - build the project using standard Maven or Gradle commands.

validate - remove non-compiling and failing tests.

create - create new tests for the project.

name: Example Workflow

# Diffblue Cover Pipeline responds to pull request
on:
  pull_request:

# Avoid running the same workflow on the same branch concurrently
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}

jobs:
  DiffblueCover:
    runs-on: ubuntu-latest
    steps:

      # Checkout the repository with permission to push
      - name: Checkout
        uses: actions/checkout@v4

      # Run Diffblue Cover
      - name: Diffblue Cover
        uses: diffblue/cover-github-action@main
        env:
          JVM_ARGS: -Xmx4096m
        with:
          # The access token used to push commits and call GitHub APIs.
          #
          # Must have access to the project with at least Write role, and scopes
          # including code, commit-statuses, pull-requests, workflows and actions.
          access-token: ${{ secrets.DIFFBLUE_ACCESS_TOKEN }}

          # The license key provided in your welcome email or provided by your organization.
          # Alternatively obtain a free trial key from https://www.diffblue.com/try-cover/github.
          license-key: ${{ secrets.DIFFBLUE_LICENSE_KEY }}

          # Working directory where the project can be found, if not at the root.
          # working-directory: path/to/project

          # The Diffblue Cover commands and options to use.
          # Below is the default behavior, uncomment these and edit to customize
          # how Diffblue Cover is run on your project.
          #args: >-
          #  ci
          #  activate
          #  build
          #  validate
          #  create

      # Collect Diffblue Cover outcome files
      # This step saves Diffblue Cover run outcome files for later use. These include summary
      # information on Diffblue Cover's results, reports files, and logs. The information
      # contained in these files can be used for project analysis, metrics, improving analysis
      # or troubleshooting problems.
      # Note that this job will always run even when the Run Diffblue Cover job fails. This
      # ensures troubleshooting logs and output are available.
      - name: Diffblue Artifacts
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: logs
          path: |
            **/.diffblue/**

Log files

Add another New repository secret and set Name to DIFFBLUE_ACCESS_TOKEN and set Secret to the GitHub access token used to allow Diffblue Cover to access your project. In general, use a GitHub Classic access token with full repo permissions. For more information on GitHub access tokens, see the docs topic.

Update or create a workflow YAML file for your project to configure the Diffblue Cover section of your CI/CD pipeline. Copy the contents of the Diffblue Cover Action workflow available from the (sample below) to your project YAML 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.

Select the version of Diffblue Cover to use in your workflow. Tag variations are provided for each supported JDK version - see for details. To use the latest version of Diffblue Cover, use one of the @main tags. To use a specific release version, use one of the @yyyy.mm.dd tags.

Additional optional arguments can be used with the various commands - see for details. Note that Cover Reports arguments are not currently supported for use with Cover Pipeline for GitHub.

For reference, the default Diffblue Cover Action workflow is provided below (uses the latest version of Diffblue Cover and JDK 17) . Note that this is a sample only - use the files provided in the to ensure that you have the latest version.

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

GitHub access tokens
GitHub Actions Marketplace
GitHub Marketplace Diffblue Cover Action
Diffblue support
Commands & Arguments
https://github.com/diffblue/cover-github-action/
Labels:
Environment Config
Workflow Config
How to pass the GitHub repository secret through to the Diffblue Cover Action