# Installation and initial setup Diffblue Cover is provided as an Action in the [GitHub Marketplace](https://github.com/marketplace/actions/diffblue-cover-pipeline). Implementing Diffblue Cover into your GitHub Actions workflow is a straightforward process. In brief, we’ll: 1. Clone a sample project and configure the GitHub Repository Secrets required for the Diffblue Cover Pipeline. 2. Set up a workflow that will use the Diffblue Cover Pipeline GitHub Action.\ 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 Diffblue Cover Pipeline Action. 3. Create the full baseline unit test suite for the sample project. {% hint style="info" %} To get familiar with setting up Cover Pipeline for GitHub on a project, we'll use the Spring PetClinic sample project here to activate and configure the Diffblue Cover Action, and write unit tests for the project. {% 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 Repository Secrets 1. Clone the sample project from the `https://github.com/diffblue/demo-spring-petclinic` Diffblue repo to your GitHub account. 2. Configure your Diffblue License key and your GitHub access token - go to **Settings > Secrets and variables > Actions > Repository secrets** * Add a **New repository secret** and set **Name** to `DIFFBLUE_LICENSE_KEY` and set **Secret** to your Diffblue Cover license key (see [Licensing](/get-started/licensing.md), if needed). * 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 [GitHub access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) docs topic.
* 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` {% 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 %} ## 2. Set up a workflow This section describes how to create a workflow using the Diffblue Cover GitHub Action. 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 Diffblue Cover Pipeline Action. Here we'll create a pull request workflow for the project, to use Diffblue Cover Pipeline from the GitHub Marketplace. The workflow will build the project, write Java unit tests for the project, and commit the changes to the branch. 1. From the project in GitHub (either the sample Spring PetClinic project, or your own project) go to **Actions > New Workflow > Set up a workflow yourself**. 2. In the editor, paste in the Diffblue Cover workflow - you can copy this from the [GitHub Marketplace](https://github.com/marketplace/actions/diffblue-cover-pipeline). For reference, the default workflow is duplicated below. {% code fullWidth="false" %} ```yaml 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/** ``` {% endcode %} {% hint style="info" %} When implementing the Diffblue Cover Pipeline and workflows with your own project and existing workflow file(s), 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 pull request. So **before** you click **Commit**, update the following: * Update the **Commit message** with an appropriate description such as "`Update .github-ci.yml file`". * Check **Create a new branch for this commit and start a pull request** to create a new branch **and** create a new pull request. * Update the **Branch** field with an appropriate name such as "`add-diffblue-cover-pipeline`". * Click **Propose changes** to start the pull request.
## 3. Create the baseline unit test suite 1. On the **Create pull request** screen, update **Title** with an appropriate pull request title such as `Add Cover workflow and create baseline unit test suite`.
2. When you're ready, click **Create pull request**. 3. The pull request workflow 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 pull request workflow 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 [GitHub workflow](/features/cover-pipeline/cover-pipeline-for-github/github-workflow.md).
## Next steps This topic demonstrates some of the key features of Cover Pipeline for GitHub and how to use the Diffblue Cover Action within a workflow. The wider and deeper functionality, provided through `dcover` commands in the workflow template, can be implemented to extend your unit test capabilities even further. When implementing the Diffblue Cover Pipeline with your own project and existing workflow file, add the template content to your file and modify as needed - see [Configuration](/features/cover-pipeline/cover-pipeline-for-github/configuration.md) for details. Note that only specific `dcover` commands and arguments are currently supported for use with Cover Pipeline for GitHub, as detailed in [Configuration](/features/cover-pipeline/cover-pipeline-for-github/configuration.md). Once you're familiar with the topics covered under [Cover Pipeline for GitHub](/features/cover-pipeline/cover-pipeline-for-github.md), check out the [Related topics](/features/cover-pipeline/cover-pipeline-for-github/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-github/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.