relicta

README

Cryptographically-attested release governance for AI-native engineering. EU AI Act Annex IV ready.

When AI coding agents merge 60% of your PRs, your auditor will ask: "How do you know which commits the AI authored, and what's your evidence the change-management process governed those decisions?"

Relicta produces that evidence. Every release proposal flows through a cryptographically hash-chained audit trail with actor-typed governance (human / ci / agent), per-actor autonomy budgets, and exportable evidence bundles for EU AI Act Article 12 + Annex IV, SOC 2 CC6.1/CC7.1/CC7.4/CC8.1, ISO/IEC 27001 / 42001, HIPAA, and PCI-DSS.

What Relicta is (and isn't)

	Relicta	Vanta / Drata	Microsoft AGT	semantic-release
Posture scanning of CI/Git data	—	✅	—	—
Runtime agent execution control	—	—	✅	—
Release-decision attestation	✅	—	partial (Article 12 mapping only)	—
EU AI Act Annex IV technical documentation	✅	—	—	—
Hash-chained audit trail	✅	—	—	—
Per-actor autonomy budgets	✅	—	—	—
Pushes evidence to Vanta / Drata	✅	—	—	—
Semantic versioning + conventional commits	✅	—	—	✅
MIT-licensed CLI	✅	—	✅	✅

Position: Relicta is the upstream provenance source Vanta and Drata cannot generate from CI/Git data alone. Microsoft AGT governs what agents do in execution; Relicta proves how release decisions were governed.

Features

EU AI Act Compliance (NEW — August 2026 ready)

• Article 12 Record-Keeping: One log entry per governance decision with use period, reference data (policy + risk-model versions), input data (commits + files + blast), verifiers, and audit chain anchors. JSONL streaming format + CSV regulator export. 6-month retention enforced per Article 26(6).
• Annex IV Technical Documentation Generator: Eight-section system documentation (general description, detailed elements, monitoring, risk management, lifecycle changes, harmonized standards, conformity scaffold, post-market monitoring) generated from existing CGP audit data. Markdown / PDF-ready. 10-year retention per Article 11.

Core Governance

• Change Governance Protocol (CGP): Public SDK (pkg/cgp/) for risk assessment, actor trust scoring, and security impact analysis
• Hash-Chained Audit Trail: SHA-256 chain over JSON-canonical CGP decisions; integrity verified at report-generation time (99.1% test coverage)
• Actor-Typed Governance: First-class human / ci / agent / system actor kinds drive policy decisions
• Agent Autonomy Profiles: Per-actor budgets cap blast radius, risk score, dollar cost, allowed/denied tools, time windows, and require human cosigners for privileged operations
• Policy DSL: Declarative policy rules with what-if comparison and matrix testing
• Blast Radius Analysis: Quantify the scope and impact of changes before they ship
• Approval Workflow: Review and approve releases with full audit trails
• Release Attestation & Signing: Generate and verify cryptographic attestations for releases
• MCP Server: Claude / GPT / Cursor / Devin agents drive releases through the same governance gates as humans

See the CGP Guide for policy DSL, risk scoring, and approval workflows, the CGP Specification for the complete protocol definition, and the Skill Publishing Checklist for sharing the Relicta governance skill publicly.

Compliance Integrations (Push, don't replace)

• Vanta evidence push: relicta integrations vanta push --type article12|soc2 maps Relicta artefacts to Vanta custom evidence. Vanta released its remote MCP server and Claude plugin in April 2026 — Relicta complements with upstream cryptographic provenance Vanta cannot generate from Git data alone.
• Drata integration follows the same pattern (planned).

Release Automation

• Automatic Version Calculation: Semantic version bumps from conventional commits
• Smart Commit Intelligence: Infers intent from unstructured histories via heuristics and optional AI
• AI-Powered Release Notes: Professional changelogs (OpenAI, Anthropic, Gemini, Azure, Ollama)
• Communication Narratives: Audience-specific release communication (engineering, product, executive, external) with AI-powered generation and template fallback
• Pre-release Channels: Alpha, beta, and RC versions with channel promotion workflow (--channel flag)
• Plugin System: Extensible via gRPC plugins (verified: GitHub, GitLab, Slack, Jira, npm; community-listed entries pending audit)

Multi-Project Support

• Monorepo: Auto-detect Go, npm, pnpm, and Cargo workspaces with independent, lockstep, or hybrid versioning strategies
• Multi-repo: Repository groups with dependency ordering and CGP federation via group subcommands

Authentication & Access Control

• JWT Session Auth: Token-based session authentication
• OIDC/SSO: Okta, Azure AD, and Google Workspace integration
• Role-Based Access: Admin, Approver, and Viewer roles

Persistence

• File-based (default): Zero-dependency local state
• PostgreSQL (opt-in): Shared state for teams with db migrate and db status commands

Dashboard & API

• REST API v1: OpenAPI-specified endpoints with health and readiness probes
• Real-time Events: WebSocket and SSE streaming for live release status
• Standalone Frontend: Deployable dashboard UI

Observability

• Prometheus Integration: Metrics endpoint for release pipeline monitoring
• Webhook Receiver: Accepts events from Alertmanager, PagerDuty, and Datadog
• Deployment Health Monitoring: Track deployment outcomes post-release
• Release-Incident Correlation: Link production incidents back to specific releases

Installation

Homebrew (Recommended)

brew install relicta-tech/tap/relicta

Download Binary

Download the latest release for your platform:

# macOS (Apple Silicon)
curl -L https://github.com/relicta-tech/relicta/releases/latest/download/relicta_darwin_arm64.tar.gz | tar xz
sudo mv relicta /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/relicta-tech/relicta/releases/latest/download/relicta_darwin_amd64.tar.gz | tar xz
sudo mv relicta /usr/local/bin/

# Linux (x86_64)
curl -L https://github.com/relicta-tech/relicta/releases/latest/download/relicta_linux_amd64.tar.gz | tar xz
sudo mv relicta /usr/local/bin/

# Linux (ARM64)
curl -L https://github.com/relicta-tech/relicta/releases/latest/download/relicta_linux_arm64.tar.gz | tar xz
sudo mv relicta /usr/local/bin/

Using Go

go install github.com/relicta-tech/relicta/cmd/relicta@latest

From Source

git clone https://github.com/relicta-tech/relicta.git
cd relicta
make build
sudo mv bin/relicta /usr/local/bin/

GitHub Action (Recommended for CI/CD)

The easiest way to use Relicta in your CI/CD pipeline:

- uses: relicta-tech/relicta-action@v2
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}

No Go, Make, or build tools required! The action automatically downloads the correct binary, verifies checksums, and handles the entire release workflow. See the GitHub Action documentation for details.

Quick Start

New to Relicta? See the Quick Start Guide for a comprehensive walkthrough.

One-Command Release (Recommended)

Run the complete release workflow in a single command:

# Interactive release (prompts for approval)
relicta release

# CI/CD auto-approve
relicta release --yes

# Preview changes without releasing
relicta release --dry-run

# Pre-release to a channel
relicta release --channel beta

Step-by-Step Workflow

For more control, use individual commands:

1. Initialize Relicta in your project:

relicta init

1. Plan a release (analyzes commits since last tag):

relicta plan

1. Evaluate risk using the Change Governance Protocol:

relicta evaluate

1. Generate release notes (optionally with AI):

relicta notes --ai

1. Approve the release:

relicta approve

1. Publish the release:

relicta publish

Configuration

Create a .relicta.yaml in your project root:

versioning:
  strategy: conventional
  tag_prefix: v
  git_tag: true
  git_push: true

changelog:
  file: CHANGELOG.md
  format: keep-a-changelog
  repository_url: https://github.com/your-org/your-repo

ai:
  enabled: true
  provider: openai
  model: gpt-4
  tone: professional
  audience: developers

persistence:
  backend: file            # file | postgres
  connection_string: ""    # DATABASE_URL for postgres

channels:
  enabled: true
  default: stable
  allowed:
    - alpha
    - beta
    - rc
    - stable

communication:
  audiences:
    - engineering
    - product
    - executive
    - external
  ai_powered: true
  template_fallback: true

observability:
  prometheus:
    enabled: true
    endpoint: /metrics
  webhooks:
    alertmanager: true
    pagerduty: true
    datadog: true

repository_groups:
  - name: platform
    repos:
      - relicta-tech/relicta
      - relicta-tech/relicta-action
    strategy: lockstep

plugins:
  - name: github
    enabled: true
    config:
      draft: false
  - name: slack
    enabled: true
    config:
      webhook: ${SLACK_WEBHOOK_URL}

workflow:
  require_approval: true
  allowed_branches:
    - main

Commands

Command	Description
release	Run complete release workflow (plan, bump, notes, approve, publish)
init	Initialize Relicta with guided setup
plan	Analyze commits and plan the next release
bump	Apply version bump (create tag)
notes	Generate changelog and release notes
evaluate	Evaluate risk using CGP (Change Governance Protocol)
approve	Review and approve the release
publish	Execute the release (create tag, run plugins)
verify	Verify release attestations and signatures
promote	Promote a release between channels (e.g., beta to stable)
communicate	Generate audience-specific release narratives
rollback	Roll back to a previous version
group plan	Plan releases across a repository group
group release	Release across a repository group with dependency ordering
group status	View status of all repos in a group
db migrate	Run database migrations (PostgreSQL persistence)
db status	Show current migration status
server	Start standalone API server (dashboard backend)
mcp serve	Start MCP server for AI agent integration
eval run	Run AI eval harness against the embedded golden corpus (gates model bumps)
eval list	List embedded golden cases
integrations vanta push	Push Article 12 / SOC 2 evidence to Vanta as custom evidence
integrations drata push	Push Article 12 / SOC 2 evidence to Drata
plugin sandbox-status	Show plugin sandbox enforcement posture (memory, CPU, signature verification, platform caveats)
report --type eu-ai-act-article-12	EU AI Act Article 12 record-keeping log bundle (jsonl / csv / markdown)
report --type eu-ai-act-annex-iv	EU AI Act Annex IV technical documentation (8 sections, 10-year retention)

Global Flags

Flag	Short	Description
--config	-c	Path to config file (default: .relicta.yaml)
--dry-run		Preview changes without making modifications
--verbose	-v	Enable verbose output
--json		Output in JSON format
--ci		CI/CD mode: auto-approve, JSON output, non-interactive
--model		AI model to use (format: provider/model)
--redact		Redact secrets and API keys from output
--allow-untrusted-plugins		Load plugins on best-effort sandbox platforms (e.g. macOS); review relicta plugin sandbox-status first
--no-color		Disable colored output
--channel		Target release channel (alpha, beta, rc, stable)

Command-Specific Flags

Most commands support short flags for convenience. Here are the commonly used ones:

Command	Flag	Short	Description
plan	--analyze	-a	Include detailed commit analysis
plan	--from	-f	Starting point for analysis
bump	--level	-l	Override bump type (major/minor/patch)
notes	--ai	-a	Enable AI-powered notes generation
notes	--save	-s	Save notes to changelog file
approve	--yes	-y	Auto-approve without prompting
approve	--edit	-e	Edit release notes before approving
publish	--skip-push	-P	Skip pushing to remote
publish	--skip-tag	-T	Skip git tag creation
release	--yes	-y	Auto-approve releases
cancel	--force	-f	Force cancel without confirmation
clean	--keep	-k	Keep the last N release runs
clean	--older-than	-o	Remove runs older than duration
blast	--from	-f	Starting git reference
blast	--to	-t	Ending git reference
communicate	--audience	-a	Target audience for narrative
promote	--from	-f	Source channel
promote	--to	-t	Destination channel
serve	--port	-p	Port to listen on
serve	--address	-a	Address to listen on

Run relicta <command> --help for the complete list of flags for any command.

Environment Variables

Variable	Description
OPENAI_API_KEY	OpenAI API key for AI-powered features
ANTHROPIC_API_KEY	Anthropic API key for Claude-powered features
GEMINI_API_KEY	Google Gemini API key
OLLAMA_HOST	Ollama server address (default: http://localhost:11434)
GITHUB_TOKEN	GitHub token for creating releases
SLACK_WEBHOOK_URL	Slack webhook URL for notifications
DATABASE_URL	PostgreSQL connection string for persistent storage
RELICTA_SERVER_MODE	Enable standalone server mode (true/false)
RELICTA_ALLOWED_ORIGINS	Comma-separated CORS origins for the dashboard API

Conventional Commits

Relicta follows the Conventional Commits specification:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types and Version Bumps

Type	Version Bump	Description
feat	Minor	New features
fix	Patch	Bug fixes
perf	Patch	Performance improvements
BREAKING CHANGE	Major	Breaking changes
docs	-	Documentation only
style	-	Code style changes
refactor	-	Code refactoring
test	-	Test changes
chore	-	Maintenance tasks

Plugins

Relicta supports plugins for extending functionality:

GitHub Plugin

Creates GitHub releases with release notes:

plugins:
  - name: github
    config:
      draft: false
      prerelease: false

npm Plugin

Publishes packages to npm registry:

plugins:
  - name: npm
    config:
      access: public
      registry: https://registry.npmjs.org

Slack Plugin

Sends release notifications to Slack:

plugins:
  - name: slack
    config:
      webhook: ${SLACK_WEBHOOK_URL}
      notify_on_success: true
      notify_on_error: true

MCP Integration

Relicta includes a Model Context Protocol (MCP) server, enabling AI agents like Claude and GPT to manage releases directly. See the MCP Guide for detailed integration instructions.

Starting the MCP Server

# Stdio transport (default, for Claude Desktop)
relicta mcp serve

# HTTP transport (for custom integrations)
relicta mcp serve --port 8080

Available Tools

Tool	Description
relicta.status	Get current release state and pending actions
relicta.plan	Analyze commits and plan the next release
relicta.bump	Calculate and set the next version
relicta.notes	Generate changelog and release notes
relicta.evaluate	Evaluate risk using CGP (Change Governance Protocol)
relicta.approve	Approve the release for publishing
relicta.publish	Execute the release (create tags, run plugins)
relicta.rollback	Roll back to a previous version
relicta.promote	Promote a release between channels
relicta.communicate	Generate audience-specific release narratives
cgp_propose	Submit a change proposal for CGP evaluation
cgp_authorize	Authorize a change through CGP policy gates
cgp_status	Query CGP evaluation and authorization status

Resources

Resource	Description
relicta://state	Current release state machine status
relicta://config	Relicta configuration
relicta://commits	Recent commits since last release
relicta://changelog	Generated changelog
relicta://risk-report	CGP risk assessment

Claude Desktop Integration

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "relicta": {
      "command": "relicta",
      "args": ["mcp", "serve"]
    }
  }
}

Client SDK

For AI agent developers, Relicta provides a Go client SDK:

import "github.com/relicta-tech/relicta/internal/mcp"

// Create client with stdio transport
transport := mcp.NewStdioClientTransport(reader, writer)
client := mcp.NewClient(transport)

// Initialize and use
client.Initialize(ctx)

// Plan a release
plan, err := client.Plan(ctx, true, "")

// Get status
status, err := client.Status(ctx)

Features

• Streaming Support: Progress updates for long-running operations
• Multi-Repository: Manage releases across multiple repositories
• Plugin Integration: List, inspect, and execute plugins via MCP

Architecture

Relicta is built with Domain-Driven Design principles:

├── cmd/relicta/                  # CLI entry point
├── internal/
│   ├── application/              # Use cases
│   ├── domain/                   # Business logic
│   │   ├── changes/              # Commit analysis
│   │   ├── release/              # Release aggregate
│   │   ├── version/              # Semantic versioning
│   │   ├── communication/        # Audience-specific narratives
│   │   ├── multirepo/            # Multi-repo group coordination
│   │   └── workspace/            # Monorepo workspace detection
│   ├── analytics/                # Release analytics and metrics
│   ├── infrastructure/           # External adapters (persistence, APIs)
│   ├── observability/
│   │   └── providers/            # Prometheus, webhook receivers
│   ├── security/
│   │   └── oidc/                 # OIDC/SSO provider integration
│   ├── cli/                      # Command implementations
│   ├── mcp/                      # MCP server & client SDK
│   ├── cgp/                      # Change Governance Protocol (internal)
│   └── service/                  # Application services
├── pkg/
│   ├── cgp/                      # CGP public SDK
│   └── plugin/                   # Plugin interface
└── plugins/                      # Official plugins

Development

Prerequisites

• Go 1.25+
• Git

Build

make build

Test

make test

Lint

make lint

Pre-commit Hooks

Set up pre-commit hooks to catch issues before pushing (recommended):

make install-hooks

This installs a git hook that runs before each commit:

• Format check (gofmt) - Verifies code formatting
• Vet (go vet) - Runs Go static analysis
• Lint (golangci-lint + gocritic) - Static analysis and code quality
• Test compile - Compiles unit tests without executing them
• Coverage (coverctl) - Checks test coverage thresholds
• Security (nox) - Runs security scanning

To manually run fast pre-commit checks:

make check

To run full CI-equivalent checks locally:

make check-ci

To skip the hook temporarily (use sparingly):

git commit --no-verify

Contributing

1. Fork the repository
2. Set up pre-commit hooks: make install-hooks
3. Create a feature branch (git checkout -b feature/amazing-feature)
4. Commit your changes using conventional commits
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

License

MIT License - see LICENSE for details.