Environment configuration for CI

This page describes how to configure Diffblue Cover CLI using environment variables. This is predominantly related to Diffblue Cover Pipeline and CI configuration.

The environment can be configured in several ways which are described in Environment Configuration

General Environment Variables

This section describes environment variables that are supported in Diffblue Cover CLI and not specific to CI environments.

Environment Variable	Notes
DIFFBLUE_LICENSE_KEY	The Diffblue license key provided in your welcome email.
DIFFBLUE_OFFLINE_LICENSE_ACTIVATION_FILE_CONTENTS	The contents of the ls_activation.lic offline license file. Note: this is only available for offline Enterprise licenses.

Pipeline & CI Environment Variables

This section describes all the Cover Pipeline and continuous integration related environment variables and configuration.

To use Cover's generic CI functionality the CI environment variable must be set to true. Note that most CI environments (including GitHub, GitLab, and Jenkins) configure this by default.

The following table lists all the environment variables related to CI.

Environment Variable	Notes
DIFFBLUE_HEAD_BRANCH	The git name of the branch that the tests will be written for and committed to.
DIFFBLUE_HEAD_SHA	The SHA of the latest commit in the branch to write tests for.
DIFFBLUE_BASE_BRANCH	The name of the branch the change request (or DIFFBLUE_HEAD_BRANCH) was forked from.
DIFFBLUE_BASE_SHA	The SHA of the latest commit before this branch was forked.
DIFFBLUE_REPOSITORY_URL	The full path to the git remote repository (if not specified, this will be read from the local git configuration).
DIFFBLUE_ACCESS_TOKEN	The git credentials access token. This should give the user permissions to pull and push to the git repository.
DIFFBLUE_ACCESS_TOKEN_NAME	The name of the access token.
DIFFBLUE_COMMIT_AUTHOR	The author name that Diffblue Cover Pipeline will use in the git repository.
DIFFBLUE_COMMIT_EMAIL	The email that Diffblue Cover Pipeline will use in the git repository.
DIFFBLUE_BASELINE_MODE	When set to true this will configure Diffblue Cover two write tests for the whole project, not just changes local to this branch. This is best used when setting up a new project, or with major changes in the code or version of Diffblue Cover.
DIFFBLUE_SKIP_CI	When set to true this will configure Diffblue Cover to exit with a success return code while performing no further actions.
DIFFBLUE_SKIP_PUSH	When set to true this will configure Diffblue Cover to not push changes back to the repository; they will still be committed locally.

Repository Access Configuration

Cover is designed to work with your existing git configuration. This means:

1. If DIFFBLUE_REPOSITORY_URL is not specified, Cover will use the remote URL from your local git configuration.

2. If DIFFBLUE_ACCESS_TOKEN and DIFFBLUE_ACCESS_TOKEN_NAME are not provided, Cover assumes that access is already configured (e.g., via SSH) and will use the existing git configuration for pushing changes.

This flexibility allows Cover to integrate seamlessly with various CI environments and git configurations.

Branch and Commit Behavior

Head Branch and Commit

1. When neither DIFFBLUE_HEAD_BRANCH nor DIFFBLUE_HEAD_SHA are specified then Cover will proceed as 2. below assuming that DIFFBLUE_HEAD_BRANCH is the current git branch.

2. When only DIFFBLUE_HEAD_BRANCH is specified (without DIFFBLUE_HEAD_SHA):

   • Cover will attempt to determine the HEAD commit of the specified branch.

   • Cover first looks for a local branch with the given name.

   • If not found locally, Cover checks for a remote-tracking branch.

   • If still not found, Cover tries to fetch the remote branch.

   • If successful, Cover uses the HEAD commit of the found branch.

   • If unsuccessful, an error will be thrown.

3. When both DIFFBLUE_HEAD_BRANCH and DIFFBLUE_HEAD_SHA are specified:

   • Cover uses the provided SHA directly.

   • Cover verifies that the SHA exists in the repository.

   • If the SHA doesn't exist, Cover will attempt to fetch it.

Base Branch and Commit

1. When only DIFFBLUE_BASE_BRANCH is specified:

   • Cover follows a similar process as with the head branch to find the base commit.

   • Cover looks for local, then remote-tracking, then remote branches.

   • The HEAD of the found branch is used as the base commit.

2. When only DIFFBLUE_BASE_SHA is specified:

   • Cover uses this SHA directly as the base commit.

   • Cover verifies the SHA exists in the repository and fetches it if necessary.

3. When both DIFFBLUE_BASE_BRANCH and DIFFBLUE_BASE_SHA are specified:

   • Cover uses the provided SHA as the base commit.

   • The branch name is used for reference but doesn't affect the chosen commit.

4. When neither is specified:

   • Cover will fall back to writing tests for the whole repository as in Baseline mode (see Mode Configuration).

Finding Common Ancestor

• If both base and head commits are successfully determined, Cover finds their common ancestor.

• This common ancestor is used as the actual base for patch mode operations.

• If no common ancestor is found within a reasonable search depth, an error is thrown.