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

{% hint style="info" %}
The environment can be configured in several ways which are described in [Environment Configuration](/features/cover-cli/environment-configuration.md)
{% endhint %}

### General Environment Variables

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

<table><thead><tr><th width="247">Environment Variable</th><th>Notes</th></tr></thead><tbody><tr><td><code>DIFFBLUE_LICENSE_KEY</code></td><td>The Diffblue license key provided in your welcome email.</td></tr><tr><td><code>DIFFBLUE_OFFLINE_LICENSE_ACTIVATION_FILE_CONTENTS</code></td><td>The contents of the <code>ls_activation.lic</code> offline license file.<br><strong>Note: this is only available for offline Enterprise licenses.</strong></td></tr></tbody></table>

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

<table><thead><tr><th width="260">Environment Variable</th><th>Notes</th></tr></thead><tbody><tr><td><code>DIFFBLUE_HEAD_BRANCH</code></td><td>The git name of the branch that the tests will be written for and committed to.</td></tr><tr><td><code>DIFFBLUE_HEAD_SHA</code></td><td>The SHA of the latest commit in the branch to write tests for.</td></tr><tr><td><code>DIFFBLUE_BASE_BRANCH</code></td><td>The name of the branch the change request (or <code>DIFFBLUE_HEAD_BRANCH</code>) was forked from.</td></tr><tr><td><code>DIFFBLUE_BASE_SHA</code></td><td>The SHA of the latest commit before this branch was forked.</td></tr><tr><td><code>DIFFBLUE_REPOSITORY_URL</code></td><td>The full path to the git remote repository (if not specified, this will be read from the local git configuration).</td></tr><tr><td><code>DIFFBLUE_ACCESS_TOKEN</code></td><td>The git credentials access token. This should give the user permissions to pull and push to the git repository.</td></tr><tr><td><code>DIFFBLUE_ACCESS_TOKEN_NAME</code></td><td>The name of the access token.</td></tr><tr><td><code>DIFFBLUE_COMMIT_AUTHOR</code></td><td>The author name that Diffblue Cover Pipeline will use in the git repository.</td></tr><tr><td><code>DIFFBLUE_COMMIT_EMAIL</code></td><td>The email that Diffblue Cover Pipeline will use in the git repository.</td></tr><tr><td><code>DIFFBLUE_BASELINE_MODE</code></td><td>When set to <code>true</code> 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.</td></tr><tr><td><code>DIFFBLUE_SKIP_CI</code></td><td>When set to <code>true</code> this will configure Diffblue Cover to exit with a success return code while performing no further actions.</td></tr><tr><td><code>DIFFBLUE_SKIP_PUSH</code></td><td>When set to <code>true</code> this will configure Diffblue Cover to not push changes back to the repository; they will still be committed locally.</td></tr></tbody></table>

### 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 [Quick Start - General](/features/cover-pipeline/cover-pipeline-for-ci/quick-start-guide-general.md#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.


---

# 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-cli/commands-and-arguments/environment-configuration-ci.md?ask=<question>
```

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.