ProcessGit

ProcessGit is a Git-based repository platform for executable processes and algorithms. It is a fork of Gitea (MIT licensed), extended with native support for process modeling standards, visual diagram editing, UAPF packaging, and a custom viewer/editor framework that lets repository authors ship their own HTML-based GUIs alongside data files.

Public demo / test instance: https://processgit.org

Important notice The public instance is fully functional but intended for testing, evaluation, and demonstration only. Data may be reset at any time. No availability or durability guarantees.

What is ProcessGit

ProcessGit is an AI-native process governance platform that combines Git-based version control with built-in AI capabilities for process classification, conformity analysis, and organizational knowledge management. It brings version control, review, releases, and traceability — the proven disciplines of source-code management — to process logic, workflows, and algorithmic definitions that traditionally live in documents, diagrams, or proprietary tools.

ProcessGit allows you to:

Store executable processes as versioned artifacts in Git
View and edit BPMN, CMMN, and DMN diagrams directly in the browser
Visualize N-Graph networks, Rulesets, XSD schemas, and XML classifications with built-in viewers
Import and export UAPF algorithm packages with schema validation
Ship custom HTML viewers/editors alongside any data file using a simple manifest
Expose repository data to AI agents via built-in MCP (Model Context Protocol) servers
Run AI-powered conformity analysis — cross-reference process definitions against regulatory requirements
Classify processes and documents using AI agents that query governed, authoritative data
Embed AI chat assistants directly in repositories with configurable LLM providers (Anthropic, OpenAI, Ollama)
Classify repositories by type (process, decision, reference, connector) and lifecycle status
Tag, release, and review process definitions through commits and pull requests
Treat organizational workflows as first-class governed assets

Instead of managing only source code, ProcessGit manages how work is done — and helps AI verify it's done right.

AI-Powered Process Analysis

ProcessGit is not just a repository — it is the governed execution environment from which AI systems retrieve authoritative process definitions, schemas, registers, and decision logic.

How It Works

Every ProcessGit repository can expose its structured data through MCP (Model Context Protocol) servers. AI agents connect to these endpoints and use standardized tools to search, query, validate, and perform conformity checks against the repository's governed data. The AI's outputs — classifications, conformity assessments, gap analyses — are grounded in versioned, peer-reviewed, auditable source material.

Key AI Capabilities

Capability	Description
Process Classification	AI agents analyze process definitions and recommend classifications against organizational schemas (e.g., document classification hierarchies, process catalogs)
Conformity Analysis	AI agents cross-reference process models (BPMN/DMN/CMMN) against regulatory requirement registers to identify compliance gaps, missing steps, and documentation deficiencies
Regulatory Validation	AI agents check whether processes include all legally required elements (notification steps, appeal instructions, deadline controls) with citations to specific legal provisions
Natural Language Querying	Embedded chat agents answer questions about processes, decisions, and classifications using the repository's actual versioned data

Why Governed Data Matters for AI

AI classification and conformity analysis is only as reliable as the data it operates on. ProcessGit ensures that:

Data is versioned: every change to a process definition or requirement register is tracked with author, timestamp, and rationale
Data is reviewed: changes go through pull request review before becoming authoritative
AI outputs are auditable: every AI query, tool invocation, and response is recorded in conversation history (stored on a git branch)
Data is authoritative: AI agents query the governed, released version of data — not drafts, not copies, not stale documents

Core Features

1. Built-in File Viewers & Editors

ProcessGit ships with a comprehensive set of viewers and editors that automatically activate when you navigate to a supported file. Instead of showing raw source, the platform renders an interactive graphical interface.

Complete Viewer Inventory

#	Viewer	File Extensions	Format	Capabilities	Library / Technology
1	BPMN 2.0 — Business Process Model and Notation	`.bpmn`, `.bpmn20.xml`, `*bpmn.xml`	XML	View + Edit + Properties panel	bpmn-js, bpmn-auto-layout
2	CMMN 1.1 — Case Management Model and Notation	`.cmmn`, `.cmmn11.xml`, `*cmmn.xml`	XML	View + Edit + Properties panel	cmmn-js
3	DMN 1.3 — Decision Model and Notation	`.dmn`, `.dmn11.xml`, `*dmn.xml`	XML	View + Edit + Properties panel (DRD, decision table, literal expression)	dmn-js
4	N-Graph — Network / Graph visualization	`.ngraph.json`, `.ngraph.xml`, `.ngraph`	JSON / XML	View only	Cytoscape.js
5	Ruleset — Business rules	`.ruleset.json`, `.ruleset.dmn`, `.ruleset`	JSON / DMN	View only (searchable table: Name, When, Then, Priority)	Custom HTML table
6	XML Classification — Structured XML viewer for schemas and registers	Detected by XML content sniffing	XML	Preview + Edit + Raw	Custom (classification & document metadata renderers)
7	XSD Visual — XML Schema Definition	`.xsd`	XML (XSD)	Visual graph editor (elements, complex types, relationships)	Custom SVG rendering with parse/serialize
8	Mermaid — Diagrams and charts	Embedded in Markdown (```mermaid blocks)	Markdown / Mermaid DSL	View (rendered inline in Markdown preview)	Mermaid.js
9	Markdown Editor — Rich text editing	`.md`, `.markdown`	Markdown	View + Edit (WYSIWYG with live preview)	Native (built-in EasyMDE / CodeMirror)
10	ProcessGit Custom Viewer — User-defined HTML GUIs	Matched by `processgit.viewer.json` manifest	HTML	Fully custom (sandboxed iframe)	PGV postMessage protocol

Detection & Rendering

File detection works by extension first, falling back to content sniffing (e.g. checking for xmlns:bpmn= in XML, or domain-specific root elements). BPMN files missing diagram layout information (bpmndi:BPMNDiagram) are auto-laid-out before rendering.

Three-mode toolbar — diagram files get a toolbar with Preview, Edit, and Raw tabs. Preview renders the graphical diagram (read-only, fitted to viewport). Edit opens a full modeler with a properties panel for BPMN/CMMN/DMN. Raw shows the underlying XML/JSON source. A Save button commits changes directly to the repository branch.

Template repositories — ProcessGit bootstraps starter templates (BPMN process, DMN decision, CMMN case, UAPF variants) that appear in the "New Repository" template dropdown.

2. UAPF Package Support — ProcessGit in the UAPF ecosystem

UAPF (Unified Algorithmic Process Format) is an open, layered standard for the full life of an algorithmic process — authored as governed code, packaged as a portable artifact, and executed end-to-end against host systems through a standard runtime contract. The standard is defined in three layers:

Layer	Defines	Repository
1 — Process Package	What a process is: BPMN/DMN/CMMN + resources + manifest, packaged as `.uapf`	UAPF-specification (SSOT)
2 — Integration Protocol	How a process runs against a host: capabilities, sessions, audit	UAPF-IP
3 — Runtime	The engine that executes a package over the protocol	uapf-engine

ProcessGit is the Git-versioned home of Layer 1 — where process packages are authored, reviewed, released and governed — and it is also their registry: the place a runtime fetches an executable package from.

Two endpoints per repository

Every ProcessGit repository exposes its process two ways, for two different consumers:

/{owner}/{repo}/mcp — the process as knowledge. An MCP server that lets AI agents read, search, validate and conformity-check the repository content.
/{owner}/{repo}/uapf-ip — the process as an executable package. A UAPF-IP package descriptor: package id/version, declared requires_capabilities, profiles_supported, guardrails reference and a distribution (archive) link. A conforming runtime uses this to discover a package and resolve package:// references without cloning the repository first.

A runtime (uapf-engine) pulls a package from a repo's /uapf-ip endpoint and executes it; AI agents and assistants invoke processes through the MCP binding (uapf-mcp). ProcessGit itself is the package source — it stores and serves, it does not execute.

Import / Export

Import: Upload a .uapf file through the repository UI. The package is validated against an embedded JSON Schema, extracted safely, and committed. Referenced manifest paths are verified; conflicts are rejected.

Export: Download repository contents (at any ref) as a .uapf archive, named {package}_{version}.uapf.

UAPF levels — repositories can be classified with a UAPF level (0–4), L0 = enterprise … L4 = task-level executable process.

API routes:

Method	Path	Description
`GET`	`/{owner}/{repo}/uapf-ip`	UAPF-IP package descriptor (capabilities, guardrails, distribution)
`GET`	`/{owner}/{repo}/mcp`	MCP server — repository content for AI agents
`POST`	`/{owner}/{repo}/uapf/import`	Upload and import a `.uapf` package
`GET`	`/{owner}/{repo}/uapf/export?ref=`	Download repo as `.uapf` package

Full standard and reference implementations: UAPF-specification · UAPF-IP · uapf-engine · uapf-mcp

3. Custom Viewers & Editors (`processgit.viewer.json`)

This is one of ProcessGit's most distinctive capabilities. Any repository can ship a custom HTML-based viewer/editor for its data files. When a user navigates to a matched file, ProcessGit loads the custom HTML GUI in a sandboxed iframe in the right pane instead of showing raw source.

This means domain experts can build tailored editing experiences — a register editor for XML data, a form-based configuration tool, a visual schema browser — and distribute them alongside the data, all within the same Git repository.

How It Works

Place a processgit.viewer.json manifest in any directory of your repository
Place your HTML viewer file(s) in the same directory
When a user browses to a file matching a viewer's primary_pattern, ProcessGit renders the custom HTML viewer instead of raw source

The platform provides a two-tab interface: GUI (the custom viewer) and Raw (the underlying source). A Save button is enabled when the viewer reports unsaved changes.

Manifest Format (`processgit.viewer.json`)

{
  "version": 1,
  "viewers": [
    {
      "id": "my-viewer",
      "primary_pattern": "data-file.xml",
      "type": "html",
      "entry": "viewer.html",
      "edit_allow": ["data-file.xml"],
      "targets": {
        "xsd": "schema.xsd",
        "xml": "data-file.xml"
      }
    }
  ]
}

Field	Required	Description
`version`	Yes	Manifest version (currently `1`)
`viewers`	Yes	Array of viewer bindings (at least one)
`viewers[].id`	Yes	Unique identifier for this viewer
`viewers[].primary_pattern`	Yes	Glob pattern to match the target file (Go `path.Match` semantics). Examples: `"data.xml"`, `"-register.xml"`, `"registers/.xml"`
`viewers[].type`	Yes	Must be `"html"` (v1 only supports HTML viewers)
`viewers[].entry`	Yes	Path to the HTML file relative to the manifest directory
`viewers[].edit_allow`	Yes	List of file paths the viewer is permitted to save back
`viewers[].targets`	No	Key-value map of related files the viewer may need (schemas, examples, etc.). Values are paths relative to the manifest directory

Building a Custom Viewer

Your viewer HTML runs inside a sandboxed iframe (allow-scripts allow-forms). It communicates with ProcessGit through the PGV (ProcessGit Viewer) postMessage protocol:

Lifecycle:

Viewer loads → Send PGV_READY to parent
Host responds → Sends PGV_INIT with a payload containing repo context, file paths, target URLs, and edit permissions
Viewer fetches data → Use PGV_FETCH to request file contents through the host's same-origin proxy (direct fetch from the iframe sandbox won't work for repo files)
User edits data → Send PGV_DIRTY with { dirty: true } to enable the Save button
User saves → Respond to PGV_SAVE_CLICKED by sending PGV_REQUEST_SAVE with the updated content

Message Reference:

Direction	Message Type	Payload	Purpose
Viewer → Host	`PGV_READY`	—	Signal the viewer is loaded and ready
Host → Viewer	`PGV_INIT`	`{ payload: ProcessGitViewerPayload }`	Deliver repo context, file paths, targets
Viewer → Host	`PGV_FETCH`	`{ url, reqId }`	Request a file through the host's same-origin proxy
Host → Viewer	`PGV_FETCH_RESULT`	`{ reqId, url, ok, text?, error? }`	Response to a fetch request
Viewer → Host	`PGV_DIRTY`	`{ dirty: boolean }`	Toggle the Save button state
Viewer → Host	`PGV_SET_CONTENT`	`{ path, content }`	Stage content for saving
Host → Viewer	`PGV_SAVE_CLICKED`	—	User clicked Save; viewer should trigger save
Viewer → Host	`PGV_REQUEST_SAVE`	`{ path, content, summary? }`	Commit the content to the repository
Host → Viewer	`PGV_SAVE_RESULT`	`{ ok, error? }`	Result of the save operation
Viewer → Host	`PGV_REQUEST_LOAD`	`{ path }`	Request content of a specific target file
Host → Viewer	`PGV_LOAD_RESULT`	`{ path, content }`	Response with file content

Minimal viewer template:

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <title>My Custom Viewer</title>
</head>
<body>
  <div id="app">Loading...</div>
  <script>
    let payload = null;

    // Helper: fetch a file through the host proxy
    function pgvFetch(url) {
      return new Promise((resolve, reject) => {
        const reqId = 'req-' + Date.now() + '-' + Math.random().toString(16).slice(2);
        const timeout = setTimeout(() => reject(new Error('PGV_FETCH timeout')), 15000);

        function onMsg(ev) {
          const m = ev.data;
          if (!m || m.type !== 'PGV_FETCH_RESULT' || m.reqId !== reqId) return;
          window.removeEventListener('message', onMsg);
          clearTimeout(timeout);
          m.ok ? resolve(m.text) : reject(new Error(m.error));
        }

        window.addEventListener('message', onMsg);
        parent.postMessage({ type: 'PGV_FETCH', url, reqId }, '*');
      });
    }

    // Listen for host messages
    window.addEventListener('message', async (ev) => {
      const msg = ev.data;
      if (!msg) return;

      if (msg.type === 'PGV_INIT') {
        payload = msg.payload;

        // Fetch the primary file content via targets
        const xmlUrl = payload.targets.xml || payload.entryRawUrl;
        const content = await pgvFetch(xmlUrl);

        // Render your UI
        document.getElementById('app').textContent = content;
      }

      if (msg.type === 'PGV_SAVE_CLICKED') {
        const editedContent = getEditedContent(); // your logic
        parent.postMessage({
          type: 'PGV_REQUEST_SAVE',
          path: payload.path,
          content: editedContent,
          summary: 'Update via custom viewer'
        }, '*');
      }
    });

    // Signal readiness
    parent.postMessage({ type: 'PGV_READY' }, '*');
  </script>
</body>
</html>

Security model: The iframe is sandboxed. File fetches are proxied through the host using a strict allow-list: only same-origin URLs matching /raw/ or /src/ paths are permitted. The edit_allow array in the manifest controls which files the viewer can write back.

Real-World Example: Organization Register Viewer

A custom viewer for an XML register of organizations, validated against an XSD schema.

Repository structure:

processgit.viewer.json          ← Manifest
register-viewer.html            ← Custom HTML viewer/editor
register.xml                    ← Data file (the register)
register.xsd                    ← XSD schema for validation

Manifest:

{
  "version": 1,
  "viewers": [
    {
      "id": "org-register",
      "primary_pattern": "register.xml",
      "type": "html",
      "entry": "register-viewer.html",
      "edit_allow": ["register.xml"],
      "targets": {
        "xsd": "register.xsd",
        "xml": "register.xml"
      }
    }
  ]
}

When a user browses to register.xml, instead of seeing raw XML, they get a fully interactive table editor with search, sorting, inline editing, XSD validation status, and the ability to save changes back to the repository — all from a single self-contained HTML file shipped in the same repo.

4. Custom Viewers To Be Made

The ProcessGit custom viewer framework (processgit.viewer.json) makes it straightforward to build new domain-specific viewers. The following are planned custom viewers to be developed and shipped as reference implementations:

Viewer	Target Files	Description	Status
JSON Schema Viewer	`.schema.json`, `.json-schema`	Visual form-based editor for JSON Schema definitions with property tree, type selectors, and validation preview	Planned
OpenAPI / Swagger Viewer	`.openapi.yaml`, `.openapi.json`, `.swagger.json`	Interactive API documentation viewer with try-it-out request builder and schema visualization	Planned
CSV / Spreadsheet Viewer	`.csv`, `.tsv`, `.xlsx`	Tabular data viewer with sorting, filtering, column statistics, and cell-level editing	Planned
YAML Config Editor	`.yaml`, `.yml` (with schema)	Schema-aware YAML editor with autocomplete, validation, and visual form rendering	Planned
Gantt / Timeline Viewer	`.gantt.json`, `.timeline.json`	Interactive Gantt chart for project scheduling and process timeline visualization	Planned
Form Builder	`.form.json`, `.form.yaml`	Drag-and-drop form designer for building data entry forms tied to repository schemas	Planned
Process KPI Dashboard	`.kpi.json`, `.metrics.yaml`	Dashboard viewer for process metrics, KPIs, and SLA definitions with chart rendering	Planned
Data Flow Diagram Viewer	`.dfd.json`, `.dataflow.xml`	Visual editor for data flow diagrams showing data stores, processes, and flows	Planned
Regulation / Policy Viewer	`.regulation.xml`, `.policy.json`	Structured viewer for legal and regulatory documents with cross-reference navigation	Planned

How to Build Your Own Custom Viewer

Any repository can ship a custom HTML-based viewer. See the Custom Viewers & Editors section for the full processgit.viewer.json manifest format and PGV postMessage protocol reference.

Key steps:

Create a processgit.viewer.json manifest defining your viewer's id, primary_pattern, entry HTML file, and edit_allow list
Build your viewer HTML using the PGV protocol (PGV_READY → PGV_INIT → PGV_FETCH → PGV_DIRTY → PGV_REQUEST_SAVE)
Place both files in the same repository directory
Navigate to a matching file — ProcessGit renders your viewer instead of raw source

Community contributions of new viewers are welcome. Open an issue to discuss your viewer idea before submitting a pull request.

5. Repository Classification

ProcessGit tracks repository classification directly in the platform database. Each repository has metadata fields that categorize its purpose and lifecycle stage.

Field	Values	Description
`repo_type`	`process`, `decision`, `reference`, `connector`, `template`	What kind of artifact the repo stores
`uapf_level`	`0`–`4` or null	UAPF hierarchy level (L0=enterprise … L4=task)
`reference_kind`	`schema`, `classifier`, `register`, `codelist`, `vocabulary`, `standard`	Sub-classification for reference repos
`status`	`draft`, `stable`, `deprecated`, `archived`	Lifecycle status

A default classification (repo_type=process, status=draft) is created automatically when a repository is created.

Typical Use Cases

Executable business processes (BPMN-based workflows with visual editing)
Decision logic and rulesets (DMN decision tables and graphs)
Case management models (CMMN cases)
Algorithm packages (.uapf bundles with schema-validated manifests)
Public-sector and enterprise process catalogs with governed releases
Reference data registers with custom HTML viewers/editors
XSD schemas with visual browsing and editing
Network/graph data visualization (N-Graph with Cytoscape.js)
Document classification schemes (XML structured preview)
AI-powered data assistants for repository content (chat agents with MCP tools)
Exposing structured data to external AI agents via MCP server endpoints
AI-assisted conformity analysis of administrative processes against procedural law requirements
Automated classification of organizational documents and processes against regulatory schemas
Regulatory requirement registers with AI cross-referencing for compliance gap identification
Cross-repository AI queries connecting multiple MCP servers
AI-assisted execution engines that require governed, versioned inputs
Single Source of Truth (SSOT) for operational logic

MCP Server Integration (Model Context Protocol)

ProcessGit implements a built-in MCP server for every repository, enabling AI agents and LLMs to query, search, and validate repository data through a standardized protocol. This turns every ProcessGit repository into an AI-accessible knowledge base.

How It Works

Any repository containing a processgit.mcp.yaml configuration file exposes an MCP server endpoint. External AI tools (Claude Desktop, custom agents, other MCP clients) can connect to this endpoint and interact with the repository data using structured tool calls.

Protocol: JSON-RPC 2.0 over HTTP with Server-Sent Events (SSE) streaming.

Endpoint: GET/POST /{owner}/{repo}/mcp

MCP Configuration (`processgit.mcp.yaml`)

version: 1

server:
  name: "my-data-server"
  description: "MCP server for organization register data"
  instructions: |
    This server provides access to organizational data.
    Use 'search' to find entities and 'get_entity' for details.

sources:
  - path: "data/organizations.xml"
    type: "xml"
    schema: "data/organizations.xsd"
    description: "Registry of organizations"
  - path: "data/classifications.xml"
    type: "xml"
    description: "Document classification scheme"

Field	Required	Description
`version`	Yes	Config version (currently `1`)
`server.name`	Yes	Human-readable server name
`server.description`	No	Server purpose description
`server.instructions`	No	Usage instructions for AI agents
`sources`	Yes	Array of data sources (at least 1)
`sources[].path`	Yes	Path to the data file in the repo
`sources[].type`	Yes	Data type (`xml` currently supported)
`sources[].schema`	No	Path to XSD/JSON Schema for validation
`sources[].description`	No	Human-readable description of the source

Available MCP Tools

When an AI agent connects to a ProcessGit MCP server, it has access to these tools:

Tool	Description
`help`	Returns server capabilities and usage instructions
`identify`	Returns server identity, repository info, and available sources
`describe_model`	Describes the data model, entity types, and their attributes
`search`	Full-text search across all indexed entities
`get_entity`	Retrieve a specific entity by ID or path
`list_entities`	List all entities with optional filtering
`validate`	Validate data against its XML/JSON schema
`check_conformity`	Cross-reference entities against regulatory requirements in the repository. Returns matched requirements with relevance scores for conformity assessment
`generate_document`	Generate documentation from the data model

Connecting External AI Tools

Any MCP-compatible client can connect to a ProcessGit MCP server:

MCP Server URL: https://your-processgit-instance.org/{owner}/{repo}/mcp

The server supports both standard HTTP request/response and SSE streaming for real-time tool execution results.

AI Chat Agents

ProcessGit provides an in-browser AI chat interface tied to repository data. When a repository contains an agent.chat.yaml configuration, the file tree displays a clickable chat agent entry with a robot icon. Clicking it opens an interactive chat panel where users can ask questions about the repository data using natural language.

Quick Start

Create an agent.chat.yaml in your repository root:

version: "1.0"

ui:
  name: "My Assistant"
  subtitle: "Ask me anything about this project"
  welcome_message: |
    Hello! I can help you understand this repository.
  quick_questions:
    - "What does this project do?"
    - "How is the data structured?"
    - "Does this process comply with all regulatory requirements?"

llm:
  provider: "anthropic"
  model: "claude-sonnet-4-5"
  api_key_ref: "ANTHROPIC_API_KEY"
  max_tokens: 1500
  temperature: 0.3
  system_prompt: |
    You are a helpful assistant for this repository.
    Use the available MCP tools to search and retrieve data.
    When asked about conformity or compliance, use the check_conformity
    tool to cross-reference processes against requirements.

mcp:
  use_repo_mcp: true

Example with OpenAI:

llm:
  provider: "openai"
  model: "gpt-4o"
  api_key_ref: "OPENAI_API_KEY"

Example with Ollama (local, no API key):

llm:
  provider: "ollama"
  model: "llama3"
  api_base_url: "http://localhost:11434"  # optional, defaults to localhost

Supported LLM Providers

Provider	Example Models	API Key Env Var
Anthropic	`claude-sonnet-4-5`, `claude-haiku-3`	`ANTHROPIC_API_KEY`
OpenAI	`gpt-4o`, `gpt-4o-mini`	`OPENAI_API_KEY`
Ollama	`llama3`, `mistral` (local)	— (runs locally)

Agent File Discovery

Priority	Path	Description
1	`agent.chat.yaml`	Root directory (default agent)
2	`.processgit/agent.chat.yaml`	Config directory
3	`*.agent.chat.yaml`	Named variants (e.g., `classification.agent.chat.yaml`)

Multiple *.agent.chat.yaml files create multiple independent chat agents in the same repository.

MCP Tool Integration

Chat agents can use MCP tools to answer questions with data from the repository:

mcp:
  use_repo_mcp: true            # Use this repo's own MCP server
  additional_servers:            # Connect to other repos' MCP servers
    - name: "org-register"
      url: "https://your-instance.org/owner/data-repo/mcp"
      description: "External data source"
  allowed_tools:                 # Whitelist specific tools
    - search
    - get_entity
    - describe_model
  denied_tools: []               # Or blacklist specific tools

Conversation History

Enable persistent conversation storage on a dedicated git branch:

history:
  enabled: true
  storage: "git-branch"
  branch: "chat-history"
  retention_days: 90
  max_conversations_per_user: 100
  anonymize: false

Conversations are stored in a date-organized structure on an orphan git branch, providing an immutable audit trail through git commit history. Commits are batched (every 5 minutes or 10+ updates) to avoid polluting history.

Access Control & Rate Limiting

access:
  visibility: "authenticated"     # "public", "authenticated", or "team"
  rate_limits:
    requests_per_minute: 10
    requests_per_day: 100
    max_conversation_turns: 50
  budget:
    max_monthly_usd: 50.00
    alert_threshold_pct: 80       # Alert admin at 80% budget usage

Chat API Endpoints

Method	Path	Description
`POST`	`/{owner}/{repo}/chat`	Send a message (SSE stream response)
`GET`	`/{owner}/{repo}/chat/agents`	List available chat agents
`GET`	`/{owner}/{repo}/chat/history`	List conversation history

Server Configuration

Enable and configure chat agents globally in app.ini:

[chat]
ENABLED = true
MAX_AGENTS_PER_REPO = 10
RATE_LIMIT_PER_MINUTE = 10
MAX_MONTHLY_BUDGET = 100.0
DEFAULT_PROVIDER = anthropic

Security Rules

API keys are referenced by environment variable name only — never store actual keys in agent.chat.yaml
Rate limiting is enforced per-user at both per-minute and per-day levels
Budget controls stop serving requests when the monthly USD limit is exceeded
Visibility controls who can access the chat (public, authenticated, or team)
Tool allow/deny lists restrict which MCP tools the LLM can invoke
Iframe sandbox applies to any custom viewer content rendered alongside chat

Architecture Overview

Upstream: Fork of Gitea (MIT), a self-hosted Git service written in Go
Backend: Go — custom modules in modules/diagrams, modules/uapf, modules/processgitviewer
Frontend: TypeScript + Webpack — diagram adapters in web_src/js/features/diagrams/, viewer framework in web_src/js/features/processgitviewer/
Diagram libraries: bpmn-js (BPMN), cmmn-js (CMMN), dmn-js (DMN), bpmn-auto-layout
Deployment: Docker-based with a bootstrap service for template repos
Database: SQLite by default (with the repo_classification table for process metadata)
Validation: Embedded JSON Schema for UAPF manifests; client-side XML validation for diagrams

Installation

This is the only supported installation method. Updates are delivered through the in-app admin UI (Site Administration → Maintenance → Updates) which expects the exact compose layout shipped at the path below. Ad-hoc deployments (custom Dockerfiles, hand-edited compose files, Kubernetes manifests, docker run on the image directly) will work for a first install but break the self-update flow.

Prerequisites

Requirement	Notes
Linux host	Ubuntu 22.04 LTS or newer recommended. WSL2 works for development. Windows host and Podman are not supported.
Docker Engine 20.10+	with Docker Compose plugin (v2). See "Installing Docker" at the end of this section if needed.
2 GB RAM minimum	4 GB recommended for active multi-user use.
5 GB free disk	Plus space for repository data, LFS, attachments.
TCP port 18080	HTTP UI. Remappable in `deploy/docker-compose.yml` if needed.
TCP port 12222	Git over SSH. Same — remappable.
Outbound HTTPS	to `ghcr.io` (signed images) and `api.github.com` (release manifests). The self-update sidecar checks `api.github.com/repos/Algomation-AI/ProcessGit/releases` periodically.

ARM64 hosts are not yet supported — current images are linux/amd64 only.

Quick start

Three commands to a running ProcessGit instance on a fresh host. No git clone, no source build, no manual install wizard — the images are pre-built, signed, and pulled from GHCR.

# 1. Create a working directory and download the compose file
mkdir -p ~/processgit/deploy && cd ~/processgit
curl -sL -o deploy/docker-compose.yml \
  https://raw.githubusercontent.com/Algomation-AI/ProcessGit/v0.1.4/deploy/docker-compose.yml

# 2. Generate a bearer token for the self-update sidecar, and tell ProcessGit
#    which URL operators will reach it at (this is important — if you skip it,
#    you'll see a warning banner in the admin UI later).
cat > deploy/.env <<EOF
PROCESSGIT_UPDATER_TOKEN=$(openssl rand -hex 32)
PROCESSGIT_ROOT_URL=http://YOUR_HOST_OR_IP:18080/
EOF

# 3. Start
docker compose -f deploy/docker-compose.yml up -d

After ~30 seconds verify everything is healthy:

docker compose -f deploy/docker-compose.yml ps

Expected:

deploy-processgit-init-perms-1    Exited (0)
deploy-processgit-init-config-1   Exited (0)
processgit                        Up (healthy)
processgit-updater                Up
deploy-processgit-bootstrap-1     Started / Exited

First-time setup

Open http://YOUR_HOST_OR_IP:18080/ in a browser.
Click Register (top right) and fill in the form.
The first registered user automatically becomes site administrator (a Gitea convention). Use a real email and a strong password.
Sign in.

You're ready to use ProcessGit. Click your avatar → Site Administration to access admin features.

Verify signed images (optional but recommended)

Every ProcessGit image and the release.json manifest attached to each GitHub Release are keyless-signed by the build workflow via Sigstore. Verify with cosign before deploying in security-sensitive contexts:

cosign verify ghcr.io/algomation-ai/processgit:0.1.4 \
  --certificate-identity-regexp '^https://github.com/Algomation-AI/ProcessGit/\.github/workflows/release\.yml@.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

A successful verification proves the image was built by this repository's published release workflow and hasn't been altered since.

Updating to a new version

Updates are installed through the admin UI, not by editing the compose file or running docker pull manually. The flow:

Open Site Administration → Maintenance → Updates.
If a newer release is available the page shows "Install vX.Y.Z" with a green banner.
Click it. You're redirected to a job-detail page that auto-refreshes every 2 seconds.
Watch the state machine progress through planning → snapshotting → pulling → verifying → migrating → swapping → healthchecking → committed. Total time is typically 30–60 seconds on a warm cache.
If the post-swap healthcheck fails, the previous version is automatically restored and you'll see the rolled_back state with the failure point in the per-step output. No data is lost.
After committed, the page reloads and shows the new current version.

The web UI is briefly unavailable (~5–10 seconds) while the main container restarts. SSH-based Git access keeps working throughout.

Configuration

Most operators don't need to configure anything beyond the three values in deploy/.env:

Variable	Default	Purpose
`PROCESSGIT_UPDATER_TOKEN`	required	Shared secret between the main app and the updater sidecar. Generate once with `openssl rand -hex 32`.
`PROCESSGIT_ROOT_URL`	`http://localhost:18080/`	Full URL operators will reach the instance at. The admin UI warns if this doesn't match the browser's current URL.
`PROCESSGIT_DOMAIN`	`localhost`	Hostname used in clone URLs (`https://<DOMAIN>/user/repo`).
`PROCESSGIT_SSH_PORT`	`12222`	External SSH port. Display only — the container always listens on 22 internally.
`PROCESSGIT_VERSION`	`latest`	Pin a specific image tag. Leave unset to auto-track `latest`.

These are read by the processgit-init-config step on first boot only. After that, edit /data/gitea/conf/app.ini inside the volume directly to change them — see the Gitea config cheatsheet for the full surface area.

Opt out of the self-update sidecar

If you have a change-control process and prefer to update via docker compose pull manually:

Don't set PROCESSGIT_UPDATER_TOKEN and start only the services you want:

docker compose -f deploy/docker-compose.yml up -d \
  processgit-init-perms processgit-init-config processgit processgit-bootstrap

Or stop the sidecar after the fact:

docker compose -f deploy/docker-compose.yml stop processgit-updater

The admin UI will then display a "the updater sidecar is not configured" message instead of update banners. The main app is fully functional without it.

Troubleshooting

Symptom	Likely cause	Fix
`processgit` "unhealthy" forever	Slow host; first-boot Gitea init exceeds healthcheck `start_period`	Wait 90 seconds, recheck with `docker compose ps`. If still unhealthy, see logs below.
`permission denied` for `/data/git/.ssh/authorized_keys.tmp` in logs	Running an image older than v0.1.3 with a current compose file	`docker compose pull && docker compose down -v && docker compose up -d`
`non-string key at top level: 404` on `up -d`	`curl` got a 404 (private repo? wrong tag?) and wrote it into the compose file	Re-run the curl with the correct tag; check `head -3 deploy/docker-compose.yml` is real YAML
Admin UI shows "Could not reach the updater"	Token mismatch or updater container not running	`docker compose ps processgit-updater` and `grep TOKEN deploy/.env` to confirm
ROOT_URL banner warning in admin UI	`PROCESSGIT_ROOT_URL` wasn't set on first boot	Edit `/data/gitea/conf/app.ini` inside the volume (`docker exec processgit sed -i ...`), then `docker compose restart processgit`

For anything not covered above, the first stop is:

docker compose -f deploy/docker-compose.yml logs --tail=80 processgit
docker compose -f deploy/docker-compose.yml logs deploy-processgit-init-config-1

If you can reproduce a problem from a fresh up -d, open an issue at https://github.com/Algomation-AI/ProcessGit/issues with the logs attached.

Installing Docker (Ubuntu / WSL)

If your host doesn't have Docker yet:

sudo apt update
sudo apt install -y ca-certificates curl gnupg

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo tee /etc/apt/keyrings/docker.asc > /dev/null
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
  https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Add yourself to the docker group so you don't need sudo
sudo usermod -aG docker $USER
newgrp docker

For developers — building from source

If you're modifying ProcessGit's Go code itself, see DEVELOPING.md. The Quick Start path above is for operators deploying ProcessGit; building from source is a different workflow and is not the supported deployment path.

Project Status

Development / Early Access

ProcessGit is under active development. Expect rapid iteration, breaking changes, and evolving documentation. Backward compatibility is not guaranteed at this stage.

Contributing

Contributions are welcome. Please open an issue to discuss significant changes before submitting a pull request.

License

ProcessGit is a fork of Gitea and is licensed in two parts.

Upstream Components — MIT

The Gitea source code and its dependencies remain under the MIT License (see LICENSE). This applies to everyone, at no charge.

Original Additions — dual-licensed

ProcessGit's own code — UAPF / UAPF-IP integration, the MCP server and chat agents, viewers and editors, schemas, templates and branding — is dual-licensed:

Free use — at no charge for personal, academic, internal non-commercial, and evaluation use, as defined in LICENSE-COMMERCIAL, Section 3.
Commercial license required — for SaaS / hosting, redistribution, embedding, provision to external users, rebranding, and revenue-generating use (LICENSE-COMMERCIAL, Section 4).
Public sector / government use — requires a commercial license in all cases, including internal and non-revenue use (LICENSE-COMMERCIAL, Section 5).

Full terms: LICENSE and LICENSE-COMMERCIAL. Commercial licensing enquiries: licensing@algomation.io

The commercial licensing documents are a draft pending review by legal counsel.

Name		Name	Last commit message	Last commit date
Latest commit History 315 Commits
.devcontainer		.devcontainer
.github		.github
assets		assets
build		build
cmd		cmd
contrib		contrib
deploy		deploy
docker		docker
docs		docs
models		models
modules		modules
options		options
public		public
resources/uapf		resources/uapf
routers		routers
services		services
snap		snap
templates		templates
tests		tests
tools		tools
updater		updater
web_src		web_src
.air.toml		.air.toml
.changelog.yml		.changelog.yml
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.example		.env.example
.envrc		.envrc
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitpod.yml		.gitpod.yml
.golangci.yml		.golangci.yml
.ignore		.ignore
.mailmap		.mailmap
.markdownlint.yaml		.markdownlint.yaml
.npmrc		.npmrc
.spectral.yaml		.spectral.yaml
.yamllint.yaml		.yamllint.yaml
BSDmakefile		BSDmakefile
CLA.md		CLA.md
CONTRIBUTING.md		CONTRIBUTING.md
DCO		DCO
DEVELOPING.md		DEVELOPING.md
Dockerfile		Dockerfile
Dockerfile.rootless		Dockerfile.rootless
LICENSE		LICENSE
LICENSE-COMMERCIAL		LICENSE-COMMERCIAL
MAINTAINERS		MAINTAINERS
Makefile		Makefile
NOTICE		NOTICE
README.md		README.md
UPSTREAM.md		UPSTREAM.md
crowdin.yml		crowdin.yml
eslint.config.ts		eslint.config.ts
eslint.json.config.ts		eslint.json.config.ts
flake.lock		flake.lock
flake.nix		flake.nix
go.mod		go.mod
go.sum		go.sum
main.go		main.go
main_timezones.go		main_timezones.go
package.json		package.json
playwright.config.ts		playwright.config.ts
pnpm-lock.yaml		pnpm-lock.yaml
pyproject.toml		pyproject.toml
stylelint.config.ts		stylelint.config.ts
tailwind.config.ts		tailwind.config.ts
tsconfig.json		tsconfig.json
types.d.ts		types.d.ts
updates.config.ts		updates.config.ts
uv.lock		uv.lock
vitest.config.ts		vitest.config.ts
webpack.config.ts		webpack.config.ts

Folders and files

Latest commit

History

Repository files navigation

ProcessGit

What is ProcessGit

AI-Powered Process Analysis

How It Works

Key AI Capabilities

Why Governed Data Matters for AI

Core Features

1. Built-in File Viewers & Editors

Complete Viewer Inventory

Detection & Rendering

2. UAPF Package Support — ProcessGit in the UAPF ecosystem

Two endpoints per repository

Import / Export

3. Custom Viewers & Editors (processgit.viewer.json)

How It Works

Manifest Format (processgit.viewer.json)

Building a Custom Viewer

Real-World Example: Organization Register Viewer

4. Custom Viewers To Be Made

How to Build Your Own Custom Viewer

5. Repository Classification

Typical Use Cases

MCP Server Integration (Model Context Protocol)

How It Works

MCP Configuration (processgit.mcp.yaml)

Available MCP Tools

Connecting External AI Tools

AI Chat Agents

Quick Start

Supported LLM Providers

Agent File Discovery

MCP Tool Integration

Conversation History

Access Control & Rate Limiting

Chat API Endpoints

Server Configuration

Security Rules

Architecture Overview

Installation

Prerequisites

Quick start

First-time setup

Verify signed images (optional but recommended)

Updating to a new version

Configuration

Opt out of the self-update sidecar

Troubleshooting

Installing Docker (Ubuntu / WSL)

For developers — building from source

Project Status

Contributing

License

Upstream Components — MIT

Original Additions — dual-licensed

About

Topics

Resources

License

Licenses found

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

3. Custom Viewers & Editors (`processgit.viewer.json`)

Manifest Format (`processgit.viewer.json`)

MCP Configuration (`processgit.mcp.yaml`)

Packages