Evidence extension adapters

kiket-extension.yaml layout, CLI scaffold, install flow, and how extension repos differ from .kiket/ process config.

Status: Shipped (2026-05-22) — platform install path + CLI scaffold

What an extension repo contains

Kiket evidence adapters live in kiket-ext-* repositories. Each adapter declares a platform manifest at the repo root:

kiket-ext-github/
  kiket-extension.yaml   ← platform contract (not process config)
  src/                   ← TypeScript normalization entrypoint
  package.json
  tests/

Do not put the manifest under .kiket/. That folder name is reserved for operational process configuration in customer or definition repos (workflows/, checks/, evidence/, simulations/). Extension repos are a different artifact.

Manifest format

kiket-extension.yaml uses the Kiket extension API:

apiVersion: kiket.dev/v1
kind: Extension
metadata:
  key: kiket-ext-github
  name: GitHub Evidence Adapter
  version: 1.0.0
  description: Normalize GitHub webhook events into Kiket evidence.
spec:
  sourceSystem: github
  ingestionScopes:
    - raw-events:write
    - evidence:write
  sourceEventTypes:
    - pull_request
    - pull_request_review
  evidenceTypes:
    - pull_request
    - pull_request_review
  retentionHints:
    rawDays: 30
    evidenceDays: 365

metadata.key matches the extension key used in Settings → Extensions and POST /platform/extensions.

Scaffold and validate locally

kiket extension init --template github
kiket extension validate

kiket extension init writes kiket-extension.yaml and src/adapter.ts. Normalization lives in the extension repo (src/normalize.ts, exported via src/adapter.ts). The platform API stores raw events only; the extension runner normalizes and submits via the SDK to POST /api/v1/platform/raw-events/{rawEventId}/submit with the installation-scoped runner API key (raw-events:submit scope). The key is returned once from POST /api/v1/platform/extensions as runnerApiKey.

For custom external runners, set KIKET_EXTENSION_RUNNER_API_KEY to that key and KIKET_PLATFORM_BASE_URL in the runner process. Catalog-hosted first-party extensions normalize in-process on the API (no separate runner). See extension runtime registry.

For customer-owned extensions and the public registry, see extension runtime registry (uniform Model A).

Install and connect

Install — Settings → Extensions (catalog) or POST /platform/extensions with the extension key.
Connect — Settings → Evidence sources: register webhook credentials and map the source system.
Model — Link evidence requirements in .kiket/ process config (in your workspace repo or a definition pack), not inside the extension repo.

Shipped integration guides:

What was removed (Kiket 1.x)

Legacy extension repos used Ruby app.rb, .kiket/manifest.yaml, custom_data modules, and analytics dashboards. That host model is gone. Adapters submit raw events and evidence through /platform/* only — they do not mutate cases or findings directly.