Getting Started

Quickstart: your first control

Annotate → build → Declared record, then a test → Verified record. Both tiers work today.

1. Annotate a compliance-relevant method

Pick a method that already implements something a control cares about, and add @ComplianceControl with the control id and the framework criterion it satisfies:

public class ConsentService {

    @ComplianceControl(
        id = "consent.capture",
        framework = "GDPR:Art.30"
    )
    public void recordConsent(String userId) {
        // your existing implementation
    }
}

2. Run your build

Run mvn verify or gradle build reportVerifiedEvidence as you normally would. The plugin’s goals are bound to your build, so there’s no separate Codevidence step.

3. Find the Declared record

One JSON file per annotated method, under target/codevidence/ (Maven) or build/codevidence/ (Gradle):

{
  "schemaVersion": "0.1",
  "kind": "declared",
  "control": { "id": "consent.capture", "framework": "GDPR:Art.30" },
  "artifact": {
    "sha256": "a1b2c3...",
    "class": "com.acme.checkout.ConsentService",
    "method": "recordConsent",
    "descriptor": "(Ljava/lang/String;)V"
  },
  "provenance": {
    "commit": "a3f9e21",
    "commitSource": "git-rev-parse",
    "buildId": "local-2026-08-28T14:32:00Z-9f1c2a",
    "buildEnvironment": "local",
    "timestamp": "2026-08-28T14:32:00Z",
    "serviceId": "checkout-service"
  }
}

It hashes the exact compiled artifact and records how the commit was resolved — see evidence records & provenance.

4. Verify it with a test

A Declared record says the method is annotated. To confirm it actually behaves as claimed, write a @VerifiesControl test that calls a typed assertion (setup here):

@VerifiesControl(id = "consent.capture")
@Test
void consentIsRecordedWithLawfulBasis() {
    var service = new ConsentService();
    service.recordConsent("user-42");

    ComplianceAssertions.assertConsentRecorded("user-42", "consent");
}

After the test phase, the plugin writes a Verified record to target/codevidence/verified/ with status: "passed" (or "failed", still recorded), linked back to consent.capture. That’s the whole loop, both tiers.

5. (Optional) sync it to the portal

Set CODEVIDENCE_API_KEY and re-run the build. Each record is also POSTed to app.codevidence.com/api/v1/evidence, and your team can sign in to see consent.capture mapped to recordConsent and its verifying test. Without the key, everything above still works — records just stay local.

export CODEVIDENCE_API_KEY=cev_acme_xxxxxxxx
mvn verify