Creating Plugins
Build custom validation plugins for Karandash. Plugins extend Karandash with custom rules, reporters, platform integrations, and more.
Plugin Types
Karandash supports four plugin formats. Choose the one that fits your language and runtime requirements.
| Plugin type | JVM (fat JAR) | Native binary |
|---|---|---|
| Kotlin/JVM JAR | via ServiceLoader |
via subprocess bridge (requires Java 17+) |
JavaScript (.mjs) |
via QuickJS | via QuickJS |
WASM (.wasm) |
via Chicory | via Chasm |
Native shared library (.dylib/.so/.dll) |
via JNA | via dlopen |
SDK Interfaces
All plugin types implement interfaces from io.karandash.sdk. Add the SDK as a dependency:
// build.gradle.kts
dependencies {
implementation("ru.kode.karandash:sdk:VERSION")
}
Core interfaces
| Interface | Purpose | Config block |
|---|---|---|
RuleModule |
Validates merge requests, returns findings | rules: |
ReporterModule |
Formats and outputs validation results | reporters: |
PlatformServiceModule |
Fetches MR data, posts comments, mutates state | platforms: |
All interfaces extend Module, which extends Plugin. Every plugin must supply id, name, and version from Plugin, and implement initialize(context: PluginContext): Boolean and optionally shutdown() from Module.
Plugin
interface Plugin {
val id: String // Reverse-domain: "com.example.my-rule"
val name: String // Human-readable: "My Custom Rule"
val version: String // Semver: "1.0.0"
}
Module
interface Module : Plugin {
val type: ModuleType
val description: String get() = name
val dslName: String get() = id // camelCase config key
val configKey: String get() = dslName // kebab-case YAML key
suspend fun initialize(context: PluginContext): Boolean
suspend fun shutdown() {}
suspend fun defaultConfig(): JsonElement = JsonObject(emptyMap())
suspend fun configSchema(): List<ConfigProperty> = emptyList()
}
PluginContext
PluginContext is passed to initialize() and provides runtime services:
interface PluginContext {
val pluginConfig: JsonElement // Config as a JSON element from the config file
val hostVersion: String // Karandash version string
val workingDirectory: String // Repo root path
val allowLocalhost: Boolean // True when --allow-localhost is set
fun log(message: String) // Info-level log
fun warn(message: String) // Warning-level log
fun env(name: String): String? // Read an allowlisted env var
@ExperimentalKarandashApi
suspend fun resolveContent(source: ContentSource): String // Inline / { file: } / { url:, auth: }
}
resolveContent works from initialize() onward (it throws ContentResolveException during plugin
bootstrap). Local files resolve against the config file's directory and must stay inside it (../ escapes,
absolute paths elsewhere and symlinks pointing out are refused). URLs are fetched with the strict SSRF policy:
cloud-metadata/link-local hosts are always refused, private/dotless hosts need allow-private-network: true or --allow-localhost, loopback needs --allow-localhost,
redirects are not followed, bodies over 1 MiB are refused, and auth: <name> takes its credentials from the
top-level auth: block (HTTPS only). Kotlin plugins running in the JAR subprocess or as C-ABI native
libraries only get Inline content; any other source fails with an explicit "not supported through the
bridge" error.
Always read environment variables through context.env(), never directly. It enforces a host-level allowlist - variables not on that allowlist are inaccessible.
RuleModule
interface RuleModule : Module {
override val type: ModuleType get() = ModuleType.RULE
suspend fun contributedRules(): Set<String> // Rule IDs this module handles
suspend fun ruleExplanation(ruleId: String): String? = null
suspend fun validate(
ruleId: String,
mr: MergeRequest,
configElement: JsonElement,
): List<Finding>
}
Return an empty list when there are no findings. Never throw from validate(); log warnings via context.warn() instead.
ReporterModule
interface ReporterModule : Module {
override val type: ModuleType get() = ModuleType.REPORTER
val formatId: String
val requiresPlatformContext: Boolean get() = false
suspend fun runtimeReporterConfig(
reportersConfig: JsonElement,
cliParams: JsonElement
): JsonElement = JsonObject(emptyMap())
suspend fun report(
findings: List<Finding>,
passed: Boolean,
config: JsonElement
): String?
}
Kotlin/JVM Plugin
JVM plugins are JAR files discovered via Java ServiceLoader.
1. Implement the interface
package com.example
import io.karandash.sdk.PluginContext
import io.karandash.sdk.config.ConfigProperty
import io.karandash.sdk.config.ConfigPropertyType
import io.karandash.sdk.module.RuleModule
import io.karandash.models.finding.Finding
import io.karandash.models.MergeRequest
import io.karandash.models.finding.Severity
import kotlinx.serialization.json.JsonElement
import kotlinx.serialization.json.JsonObject
import kotlinx.serialization.json.JsonPrimitive
class TicketReferenceRuleModule : RuleModule {
override val id = "com.example.rule.ticket-reference"
override val name = "Ticket Reference Rule"
override val version = "1.0.0"
private lateinit var context: PluginContext
override suspend fun contributedRules() = setOf("ticketReference")
override suspend fun initialize(context: PluginContext): Boolean {
this.context = context
return true
}
override suspend fun validate(
ruleId: String,
mr: MergeRequest,
configElement: JsonElement,
): List<Finding> {
val config = configElement as? JsonObject ?: JsonObject(emptyMap())
val pattern = (config["pattern"] as? JsonPrimitive)?.content ?: "[A-Z]+-\\d+"
val regex = Regex(pattern)
if (!regex.containsMatchIn(mr.title)) {
return listOf(
Finding(
rule = ruleId,
message = "Title must reference a ticket matching $pattern",
severity = Severity.ERROR
)
)
}
return emptyList()
}
override suspend fun defaultConfig(): JsonElement = JsonObject(
mapOf("pattern" to JsonPrimitive("[A-Z]+-\\d+"))
)
override suspend fun configSchema() = listOf(
ConfigProperty(
name = "pattern",
type = ConfigPropertyType.STRING,
description = "Regex pattern for ticket reference",
required = false
)
)
}
2. Register via ServiceLoader
Create the file src/main/resources/META-INF/services/io.karandash.api.Module containing the fully-qualified class name:
com.example.TicketReferenceRuleModule
3. Build a fat JAR
// build.gradle.kts
plugins {
kotlin("jvm")
id("com.github.johnrengelman.shadow") version "8.1.1"
}
dependencies {
compileOnly("ru.kode.karandash:sdk:VERSION")
}
tasks.shadowJar {
archiveClassifier.set("")
}
./gradlew shadowJar
# Output: build/libs/my-plugin-1.0.0.jar
4. Declare in config
plugins:
- path: "./plugins/my-plugin-1.0.0.jar"
rules:
ticketReference:
pattern: "PROJ-\\d+"
On the native binary the JAR runs in a JVM subprocess that serves every module type, and a class
implementing several interfaces registers once per type. Properties are read once at discovery and each
call runs in a fresh JVM, so keep state out of the module; the remaining gaps are listed in
JVM vs Native. The JVM CLI loads the class in
process and registers it under every type it implements as well. Example:
tools/examples/standalone-jvm-plugin/src/main/kotlin/com/example/karandash/ExampleCompositePlugin.kt.
JavaScript Plugin
JavaScript plugins run in a sandboxed QuickJS runtime. They work on both the JVM fat JAR and the native binary.
Rule plugin example
// ticket-reference.mjs
export const id = "com.example.rule.ticket-reference-js";
export const name = "Ticket Reference Rule (JS)";
export const version = "1.0.0";
export const type = "rule";
export const contributedRules = ["ticketReference"];
export function initialize(context) {
return true;
}
export function validate(ruleId, mr, config) {
const pattern = config.pattern ?? "[A-Z]+-\\d+";
const regex = new RegExp(pattern);
if (!regex.test(mr.title)) {
return [{
ruleId: ruleId,
message: `Title must reference a ticket matching ${pattern}`,
severity: "ERROR"
}];
}
return [];
}
export function defaultConfig() {
return { pattern: "[A-Z]+-\\d+" };
}
Declare in config
plugins:
- path: "./plugins/ticket-reference.mjs"
rules:
ticketReference:
pattern: "PROJ-\\d+"
JavaScript API contract
The mr object passed to validate() mirrors MergeRequest:
| Field | Type | Description |
|---|---|---|
mr.title |
string |
MR/PR title |
mr.description |
string \| null |
MR/PR description |
mr.author |
string |
Author username |
mr.sourceBranch |
string |
Source branch name |
mr.targetBranch |
string |
Target branch name |
mr.commits |
Commit[] |
List of commits |
mr.changedFiles |
ChangedFile[] |
Changed files |
mr.labels |
string[] |
Applied labels |
mr.isDraft |
boolean |
Draft status |
A finding object must have ruleId (string), message (string), and severity ("ERROR", "WARNING", or "INFO"). The filePath and line fields are optional for inline annotations.
WASM Plugin
WASM plugins are loaded via Chicory on the JVM fat JAR and Chasm (pure Kotlin, compiled in) on the native binary (Chasm 1.7.0 on the macOS x64 binary). Each .wasm file runs in its own isolated runtime instance.
ABI contract
Your WASM module must export these functions:
| Export | Signature | Description |
|---|---|---|
karandash_abi_version |
() -> i32 |
Must return 1 |
karandash_module_id |
(ptr: i32, len: i32) -> i32 |
Write plugin ID to memory, return bytes written |
karandash_validate |
(rule_ptr, rule_len, mr_ptr, mr_len, cfg_ptr, cfg_len, out_ptr, out_len: i32) -> i32 |
Run validation, write JSON findings to out buffer |
Memory exchange uses length-prefixed strings via linear memory. Input and output are JSON-encoded.
Rust example
// src/lib.rs
#[no_mangle]
pub extern "C" fn karandash_abi_version() -> i32 { 1 }
#[no_mangle]
pub extern "C" fn karandash_module_id(ptr: i32, len: i32) -> i32 {
let id = b"com.example.rule.ticket-reference-wasm";
let out = unsafe { std::slice::from_raw_parts_mut(ptr as *mut u8, len as usize) };
let copy_len = id.len().min(out.len());
out[..copy_len].copy_from_slice(&id[..copy_len]);
copy_len as i32
}
#[no_mangle]
pub extern "C" fn karandash_validate(
_rule_ptr: i32, _rule_len: i32,
mr_ptr: i32, mr_len: i32,
_cfg_ptr: i32, _cfg_len: i32,
out_ptr: i32, out_len: i32,
) -> i32 {
// Decode MR from linear memory (JSON), run validation,
// write JSON findings array to out_ptr/out_len.
// Return bytes written, or negative value for error.
let result = b"[]";
let out = unsafe { std::slice::from_raw_parts_mut(out_ptr as *mut u8, out_len as usize) };
let copy_len = result.len().min(out.len());
out[..copy_len].copy_from_slice(&result[..copy_len]);
copy_len as i32
}
cargo build --target wasm32-unknown-unknown --release
# Output: target/wasm32-unknown-unknown/release/my_plugin.wasm
Declare in config
plugins:
- path: "./plugins/my_plugin.wasm"
rules:
ticketReference:
pattern: "PROJ-\\d+"
Native Shared Library Plugin
Native plugins are shared libraries (.dylib on macOS, .so on Linux, .dll on Windows). They are loaded via dlopen on native binary and via JNA on the JVM fat JAR.
C ABI contract
Your library must export these symbols:
// Returns ABI version; must return 1
int32_t karandash_abi_version(void);
// Returns the module ID as a null-terminated UTF-8 string (static lifetime)
const char* karandash_module_id(void);
// Runs validation; mr_json and config_json are null-terminated JSON strings.
// Returns a null-terminated JSON array of findings.
// Caller must free the returned string with karandash_free_string().
const char* karandash_validate(
const char* rule_id,
const char* mr_json,
const char* config_json
);
// Frees memory allocated by karandash_validate
void karandash_free_string(const char* ptr);
C example
#include <stdlib.h>
#include <string.h>
#include <stdint.h>
int32_t karandash_abi_version(void) { return 1; }
const char* karandash_module_id(void) {
return "com.example.rule.ticket-reference-native";
}
const char* karandash_validate(
const char* rule_id,
const char* mr_json,
const char* config_json
) {
// Parse mr_json, run validation logic, return JSON findings array.
// Return strdup("[]") for no findings.
return strdup("[]");
}
void karandash_free_string(const char* ptr) {
free((void*)ptr);
}
Build
# macOS
clang -dynamiclib -o my-plugin.dylib my-plugin.c
# Linux
gcc -shared -fPIC -o my-plugin.so my-plugin.c
# Windows (MinGW)
gcc -shared -o my-plugin.dll my-plugin.c
Declare in config
plugins:
- path: "./plugins/my-plugin.dylib" # or .so / .dll
rules:
ticketReference:
pattern: "PROJ-\\d+"
Configuration Reference
External plugin declaration
plugins:
# Local file path
- path: "./plugins/my-plugin-1.0.0.jar"
# Registry reference
- id: "com.example.ticket-validator"
version: "1.2.0"
Using your rule in config
Once loaded, your rule module's contributed rule IDs appear under rules: using the rule ID returned by contributedRules():
rules:
ticketReference: # Matches contributedRules() = setOf("ticketReference")
pattern: "PROJ-\\d+"
Best Practices
- Return empty list on error: when validation cannot proceed, log via
context.warn()and returnemptyList(). Never throw fromvalidate(). - Read env vars via
context.env(): it enforces a host-level allowlist. Variables not on that allowlist are inaccessible. - Provide a config schema: implement
configSchema()so the LSP server can offer completions and validate your plugin's config block. - Use
defaultConfig(): return sensible defaults so your plugin works without explicit configuration. - Single responsibility: each plugin should validate one concern. Compose multiple plugins instead of building one that does everything.
- Test all paths: cover the happy path, missing config, invalid input, and empty MR data.
Plugin Security
JAR plugins are signature-verified before loading, on the JVM and native binaries alike, once any trusted key is present in ~/.karandash/keys: a JAR without a matching <name>.jar.sig is rejected. JS, WASM and native plugins are not signature-checked. The env() API enforces an allowlist - plugins cannot read arbitrary environment variables. JavaScript plugins run in a sandboxed QuickJS context with no access to the filesystem or network beyond the APIs explicitly provided by Karandash.
Example Projects
Complete, buildable example plugin projects for each language are in tools/examples/:
tools/examples/
├── standalone-jvm-plugin/ - Kotlin/JVM JAR plugin with Gradle build
├── standalone-js-plugin/ - JavaScript .mjs plugin
├── standalone-wasm-rust-plugin/ - WASM plugin written in Rust
├── standalone-cpp-plugin/ - Native shared library written in C++
└── standalone-go-plugin/ - Native shared library written in Go