GitCover Symbol GCBoKGitCover Body of Knowledge

Axis 5: Procedures

SME Onboarding

The entry for SMEs into Git-native compliance follows a stepwise path:

  1. Initialize Git repository — Structure with .gitcover/ directory, V7GUID configuration
  2. Select OSCAL catalog — GoBD baseline, BSI modules, or individual profile
  3. Activate OPA policies — Pre-receive hooks for validation before commit
  4. Set up GPG signing — One GPG key pair per actor
  5. Start evidence chain — Assign first V7GUIDs, begin prev-hash chaining

For Entrepreneurs from Side-Business Level

The entry can begin with a very simple setup: GCDMS for evidence archiving, GCPN for evidence chains. Expand later: OSCAL policies, OPA validation, multi-tenant.

Interactive Onboarding: The "Compliance City"

Instead of classical questionnaires, onboarding takes place as a modular construction following the concept of a city on a Lego baseplate. Every architectural decision and every functional requirement corresponds to a building block or a set (Lego set) that is stored and versioned as a structured module in the newly initialized default Git repository.

The analogy for the user:

Phase 1 — Lay out baseplate (Initialization & Identity):

The system automatically creates the default repository for the tenant. The onboarding assistant determines the company's identity. The data is stored in a structured manner in the 'TOP' (Tenant Organization Profile) repository — the first Git commit is already the first auditable compliance process. Incidentally: Tenants can naturally also be organized hierarchically, like the corporate structures they belong to.

Building Block Technical Equivalent Purpose
Baseplate git init --object-format=sha256 Basis of all tenant activities in the 'TOP' Git repository and directory
Town Hall ./.gitcover GitCover Dot-Directory where the Tenant Dictionaries and Configurations reside

Phase 2 — Infrastructure wiring (utility network):

The assistant captures the IT landscape: laptop workstation, file server, cloud-first or hybrid infrastructure. Parameters such as internet connection, domain, storage paths, etc. flow into the infrastructure information and prepare paths for cross-connections (others.json).

Phase 3 — Erect buildings (functional scope):

The user decides modularly which regulatory areas their city should secure:

Building Block Scope Action
Marketplace (GoBD/AO basis) Mandatory for every SME — procedure documentation e.g. Module & folder /compliance/gobd/ is activated
Bank & Cash (financial accounting) Journal management, general ledgers, bank interfaces e.g. Module & folder /finance/journal/ and /finance/ledgers/ is activated
Factory Gate (security/NIS2) Optional extended IT security and reporting obligations e.g. Module & folder /compliance/nis2/ is activated

The user never sees configuration files or code at any point. Since every step immediately produces a clean Git commit, the system is fully audit-proof per GoBD and AO from the very first minute.

Tenant Isolation and Access Control

OIDC Claims and others.json

Linking OIDC claims with others.json is the royal road for multi-tenant, layperson-safe compliance environments. In others.json the following accumulate:

  1. Canonical routes to the tenant's own Git repositories
  2. Cross-connections to Git repositories of other tenants, if the tenant is a member of a group

Access is controlled via OIDC claims (roles and custom claims such as tenant_id and group memberships). An inlet pipeline reads others.json depending on the user claim and injects the allowed paths as a system prompt:

You are the GitCover Agent for Tenant X. You have exclusive access to the following repositories: [Path 1], [Path 2]. Do not execute commands outside these directories.

For the end user, this security apparatus remains invisible. They log in, see their familiar work environment, and the AI automatically knows where it may operate.

AI-Assisted Data Entry via Form Bridging

Chat interfaces are suitable for contexts and analyses, not for strict data type capture (IBANs, postal codes, OSCAL schemas). GCBoK therefore recommends a form bridging approach:

  1. AI recognizes need: The user says "I want to add a new business premises."
  2. Dynamic form URL: The AI outputs a link to a validated web input form (Blazor WASM/PWA), coupled with session and user management.
  3. Encapsulated input: The user fills out the form — hard-validated before saving.
  4. Direct write to Git: The form writes the result as a structured file directly into the working directory of the tenant repository and triggers the commit.
  5. AI takes over again: The MCP server reports "file updated," the AI confirms in chat.

Advantage: Validation before saving protects the single source of truth. LLMs do not manipulate the write process. Git hook/OPA validation is triggered immediately.

The .gitcover/ Directory Structure

The .gitcover/ directory in the root of a GitCover repository is the central archive for all non-code artifacts. It serves audit-proof integrity, compliance (GoBD/AO), and audit trail management.

Directory Layout

.gitcover/
├── issues/              # Gitea Issues as .v7g.md
├── projects/            # Project management data
├── time_tracking/       # Time tracking and effort records
├── workflows/           # Workflow states and approvals
├── compliance/
│   ├── oscals/          # OSCAL documents (System Security Plans)
│   ├── opa/             # OPA rules (Rego policies)
│   └── hooks/           # Git hooks for automation
├── audit/
│   ├── signatures/      # Cryptographic signatures
│   ├── timestamps/      # Timestamps (ELSTER/Bundesanzeiger)
│   └── logs/            # Protocols
└── README.md            # Documentation of the structure

File Naming Convention

General format: {uuidV7}_{human-readable-key}_{description}.v7g.md

Artifact Type Example Rationale
Issue 018e312f-..._#123_Bugfix-Login.v7g.md UUIDv7 for sortability, # for identification
Project 018e312f-..._Project-X.v7g.md Unique, temporally sortable
Time tracking 018e312f-..._2026-06-29_Axel-D.v7g.md Date and user in plain text
Sidecar (PDF/DOCX) Invoice_2026.pdf.v7g.md Metadata for the original document

Metadata Schema (.v7g.md Frontmatter)

---
uuid: 018e312f-3e4f-7000-8000-000000000000
key: "#123"
type: "issue"
title: "Bugfix: Login Module"
original_source: "Gitea"
original_repo_hash: "a1b2c3d4e5f6..."
related_commits: ["abc123", "def456"]
related_elements:
  project: "Project-X"
  milestone: "v1.0"
forensic_attributes:
  created_at: "2026-06-29T12:00:00Z"
  updated_at: "2026-06-29T14:30:00Z"
  created_by: "Axel D."
compliance:
  gobd_relevant: true
  audit_trail: true
  signature: "GPG signature hash"
  timestamp: "ELSTER-2026-06-29-120000"
---

Automation through Git Hooks and Webhooks

GitCover repos are automatically configured with hooks/webhooks during init or tenant onboarding:

The versioning of these hooks/webhooks also occurs via Git, so changes are traceable and auditable (self-referential, versioned, audit-proof). The hooks themselves can be versioned code artifacts that reside in .gitcover/hooks/ and are updated as needed, documented in compliance with GoBD or NIS2.

Issue Archiving: Gitea DB to Git Fact Base

Problem Statement

Gitea issues are database entries — not native Git objects. They are not versioned and cannot be reconstructed if the Gitea database is lost. Commits reference issues only textually (Fixes #123); this reference is not interpreted by Git.

Solution: Automated Export as .v7g.md

The workflow from Gitea database to audit-proof fact base:

  1. Gitea issue created → Webhook triggers export
  2. Export as .v7g.md → Save in .gitcover/issues/
  3. Extract metadata → UUID, hashes, signatures
  4. Git commit with signature → git commit -S
  5. OSCAL/OPA validation → Compliance check
  6. Timestamp → ELSTER/Bundesanzeiger integration (if required)

OPA Example Rule for Issue Validation

package gcbok.compliance

violation[msg] {
  input.path == "issues"
  file := input.files[_]
  not startswith(file.name, "018")  # UUIDv7 check
  msg := sprintf("Issue %s hat keine gueltige UUIDv7 im Dateinamen", [file.name])
}

GoBD/AO Compliance

GoBD Requirement Implementation in .gitcover/
Traceability Every change is logged in .gitcover/audit/logs/
Immutability .v7g.md files are never overwritten but versioned
Retention obligation 10 years (DE) — .gitcover/ as central archive
Evidence function .v7g.md files as digital evidence
Auditability Signatures and timestamps enable forensic validation

Audit-Readiness

Audit-readiness means: Every audit can take place at any time — without follow-up preparation.

Prerequisite Git-native Fulfillment
Complete audit trail Git history (commit log)
Verifiable identities GPG signatures
Temporal sortability V7GUID timestamps
Machine-readable evidence OSCAL Assessment Results
Policy conformance OPA validation results

GoBD Year-End Close

The GoBD year-end close with Git-native compliance:

  1. Close period — Freeze Git branch FY2026 (tag)
  2. Validate evidence chain — Check V7GUID chaining (script)
  3. Generate OSCAL Assessment Results — Automated from OPA validations
  4. GPG seal issuance — Closing commit with CEO signature
  5. Archiving — .v7g.zip container, v7g-export

NIS2 Risk Analysis

The NIS2 risk analysis on a Git basis:

  1. Asset inventory — Git repositories as asset register
  2. Risk identification — OPA policies for threat scenarios
  3. Assessment — V7GUID classification for risk categories
  4. Mitigation — Pre-receive hooks for policy enforcement
  5. Report — OSCAL Assessment Results as NIS2 evidence

AI Server Integration in the LAN

Architecture Principle

GCBoK describes a reference model for integrating a headless AI server in the LAN that centrally provides LLM inference and RAG-supported compliance agents. The AI environment runs in an isolated container environment (Rootless Podman) but couples to natively installed services on the host for inference and web search.

SSH Script Host (OSSH)

For demanding tasks (code compilation, Git operations, compliance checks) that go beyond the container sandbox, the agent uses an SSH Script Host — a controlled, key-based breakout to the host system:

  1. Agent decides: "Execute dotnet-build"
  2. SSH channel: encrypted connection via id_rsa.pub to host user
  3. Native process: command is executed in the real OS context
  4. Stream return: stdout/stderr are returned as text stream
  5. Agent analyzes: compiler output in LLM context

Security requirement: The SSH key generated in the container must be installed on the host in authorized_keys. Communication occurs purely via standard data streams (stdin, stdout, stderr) — without file transfer.

Consistent Path Addressing (FQN)

To avoid path inconsistencies between workstation, container, and script host, file server shares are mounted at identical mount points on all systems. AI agents and human developers reference identical absolute path specifications at all times.

Multi-Device Capability

Through centralization on the AI server, multiple end devices can access the same environment in parallel:

Share Frontends: Nextcloud as Read-Only Frontend

Role Distribution

Component Role GCBoK Compliance
GCDMS Primary storage location for compliance artifacts in Git Complete
GCPN Policy validation (OPA/Rego) and compliance rules Complete
GCUCB Context bus for AI agents, OPA validators, audit systems Complete
Nextcloud Only for shares/permissions (external users, mobile access) Limited

Conditions for Use

Nextcloud can be used selectively for shares in a GCBoK-based environment if:

  1. Read-only shares only — No changes via Nextcloud; all mutations run through Git
  2. Git integration — Nextcloud mounts Git repos as external storage (WebDAV, S3 Gateway, or GCSYNC)
  3. Policy validation — GCPN defines access rules (OPA/Rego); Nextcloud only implements them
  4. Audit logging — Nextcloud logs are forwarded to GCAL (Syslog/Loki)
  5. Open-source compliance — Community Edition only, no proprietary plugins

Exclusion Criteria

See also: Templates for OSCAL catalogs and OPA policies in Axis 6: Templates.