Getting Started

Installation

The Codevidence build plugin runs as steps in your normal Maven or Gradle build. It reads the .class files your compiler already produced and the outcomes of your @VerifiesControl tests — it does not compile anything itself and does not need your source.

Requirements

• JDK 17 or later
• Maven 3.6+ or Gradle 8+
• For Verified: JUnit 5 (Jupiter) tests

Maven

Add the plugin to your pom.xml. The two goals bind to their default phases — extract-evidence to process-classes, report-verified-evidence to verify:

<plugin>
    <groupId>com.codevidence</groupId>
    <artifactId>codevidence-maven-plugin</artifactId>
    <version>0.1.0</version>
    <configuration>
        <serviceId>checkout-service</serviceId>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>extract-evidence</goal>
                <goal>report-verified-evidence</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Gradle

Apply the plugin in build.gradle.kts. It registers extractEvidence (runs after classes) and reportVerifiedEvidence (runs after test):

plugins {
    id("com.codevidence.gradle-plugin") version "0.1.0"
}

codevidence {
    serviceId = "checkout-service"
}

Also for Verified

Add the assertions library as a test dependency:

<dependency>
    <groupId>com.codevidence</groupId>
    <artifactId>codevidence-assertions</artifactId>
    <version>0.1.0</version>
    <scope>test</scope>
</dependency>

Enable JUnit Platform extension auto-detection in src/test/resources/junit-platform.properties:

junit.jupiter.extensions.autodetection.enabled=true

And point the test runner at the raw-findings directory so the plugin can read assertion outcomes back after the (forked) test JVM exits:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <configuration>
        <systemPropertyVariables>
            <codevidence.rawFindingsDir>${project.build.directory}/codevidence/verified-raw</codevidence.rawFindingsDir>
        </systemPropertyVariables>
    </configuration>
</plugin>

For Gradle, set the same as a test system property: systemProperty("codevidence.rawFindingsDir", layout.buildDirectory.dir("codevidence/verified-raw").get().asFile.absolutePath).

Optional: sync to the Codevidence portal

Set CODEVIDENCE_API_KEY in your build/CI environment and the plugin also POSTs each record to https://app.codevidence.com/api/v1/evidence, where your team reviews controls against the code that implements them. Without a key, nothing is published — records stay local-file-only and the plugin makes no network call.

export CODEVIDENCE_API_KEY=cev_acme_xxxxxxxx

See build plugin configuration for the apiKey / evidenceEndpoint options and self-hosting.

What happens next

On your next build: the plugin scans compiled classes for @ComplianceControl and writes one Declared record per annotated method to target/codevidence/; after tests, it reads @VerifiesControl assertion outcomes and writes one Verified record each to target/codevidence/verified/. Nothing about how your production code runs changes.

Continue to the Quickstart to annotate your first method and see the record it generates.