Documentation Center

GitScribe Core Manual

Discover developer guides, interactive configuration explorers, engine architectures, and advanced AI test frameworks to automate your GitHub documentation.

⌘K

getting started

Introduction

The Automated Engine for GitHub Docs

GitScribe is an intelligent documentation automation platform designed to keep repository documentations completely synced with your code changes. By integrating directly as a GitHub App, it securely monitors pushes and pull requests, analyzes differences using Google Gemini, indexes codebases via Retrieval-Augmented Generation (RAG) embeddings, and automates high-quality documentation edits as pull requests.

✓Never Stale Docs

Documentation runs dynamically matching each git commit or pull request, keeping code details accurately written automatically.

✓RAG-Powered Depth

Indexes code files in 3072-dimensional vector embedding database (pgvector) to feed exact architecture context into generative models.

getting started

How It Works

The 5-Step Automation Lifecycle

GitScribe sits between your GitHub repository and your development workspace, listening for event actions and managing background pipelines seamlessly.

Secure GitHub Connection

Install the GitScribe GitHub App. Provide repository permissions to grant secure access over webhooks, code checking, and pull requests.

Define Rules in YAML

Create a simple `.gitscribe.yml` file in the root of your repo. Customize markdown target directories, tone choices, file exclusions, and testing frameworks.

Code Push & Webhook Dispatch

When you push code or open a PR, a secure webhook signature verifies payload legitimacy and queues background worker jobs.

Vector Code Indexing & RAG Search

Modified code is chunked and embedded using Google Gemini embeddings into PostgreSQL pgvector database, fetching precise system context.

Automated Pull Request

AI engines process the code changes, generate technical markdown summaries, and create a Pull Request directly back to your repo for final review.

getting started

Quick Start

Integrate GitScribe into your GitHub Workflow

Get GitScribe connected to your repository and automate your documentation and test suites in under 3 minutes. As a managed platform, GitScribe connects securely to your GitHub accounts with no hosting or local infrastructure required.

1Connect Your GitHub Repository

Navigate to the GitScribe Dashboard and click "Connect Repository". This will take you to the secure GitHub App authorization screen. Grant access to either your entire workspace or specify selected repositories. Once authorized, GitScribe instantly initiates a read-only background sweep to build vector index embeddings (pgvector) of your repository structure.

2Automated Push & PR Workflow

Whenever a developer pushes code changes or opens a Pull Request, a secure GitScribe webhook verifies the payload. The system analyzes your code updates, consults the vector embeddings for full codebase context, and automatically generates beautiful documentation improvements. These are submitted directly back to your repository as a clean, structured Pull Request for your team to inspect and merge.

3Enable AI Sibling Test Generation

GitScribe does more than write docs—it automatically maintains test coverage for modified files! To activate sibling test generation, simply add a `.gitscribe.yml` config file to the root of your project:

# .gitscribe.yml
version: "1.0"

tests:
  enabled: true
  framework: "vitest" # Options: "vitest" | "jest"

4Define Custom Manual Test Directions

You can inject manual test generation instructions or exclude components directly from code comments. The GitScribe worker parses these inline directives on the fly:

// gitscribe-test: include: verify auth token expirations trigger 401 returns
// gitscribe-test: exclude: skip mocking slow Stripe subscription endpoints

configuration

.gitscribe.yml Reference

Customize documentation pipelines inside your repository

By putting a `.gitscribe.yml` file in the root folder of your project, you can override default options. Configure output markdown directories, specify documentation tone variants, enable automated sibling test generations, and supply ignore path matrices.

Precedence Note: System fallback defaults take control if any options are missing. An empty `.gitscribe.yml` behaves identically to default specifications.

configuration

Interactive Configuration Explorer

Click config parameters to discover usage definitions and presets

.gitscribe.yml

version: "1.0"

maxConcurrentFiles: 5

docs:

outputDir: "docs/generated"

tone: "formal"

tests:

enabled: false

framework: "vitest"

ignore:

- "node_modules/**"

- "dist/**"

💡 Click parameters above to view spec descriptionsYAML explorer

maxConcurrentFiles

Type: numberDefault: 5

Controls the maximum number of modified codebase files parsed in parallel. Higher numbers increase throughput speed but may hit Google Gemini API rate limits or triggers GitHub API throttling.

YAML Snippet Example:

maxConcurrentFiles: 8

Preset selected: minimal

advanced

AI Sibling Test Generation (Beta)

Write logic, let AI handle coverage creation

GitScribe features automated unit test creation. When enabled under `.gitscribe.yml`, the RAG engine watches for logic updates and constructs high-quality, framework-compliant testing suites (e.g., `api.ts` -> `api.test.ts`) that match code changes.

Sibling Test Generation Pipeline Rules

•Incremental-Only behavior: AI engines only write new tests if sibling files do not exist. Prevents overwriting custom manually-crafted assertions.
•Strict Import Matching: Sibling tests automatically parse relative exports and map import routes accurately so tests execute out-of-the-box.
•Directive Parsing: Customize logic blocks using comments inside files for targeted assertions.

advanced

Inline Testing Directives

Control automated test generators directly from your comments

You can dictate precisely what tests Gemini creates or excludes directly inside the codebase. Add line or block directive comments anywhere in the file.

Line-level Directives

Provide single-sentence instructions to direct AI focus to a specific validation:

// gitscribe-test: include: asserts 401 response status for invalid authentication tokens
// gitscribe-test: exclude: heavy end-to-end database integrations

Block-level Directives

Provide nested criteria groups over complex files:

// gitscribe-test-begin
// include: rejects payload structures with missing signature keys
// include: supports standard timeout retry triggers
// exclude: external network API calls
// gitscribe-test-end

Attention: Directives represent best-effort hints for AI context building. Malformed strings or non-supported commands are ignored with console logging.

architecture

RAG Engine Pipeline

The Flowchart of Code-to-Doc Automation

Explore the pipeline flow showing how code commits route from GitHub through verification layers, BullMQ distributed background processing queues, vector indexes, and generative updates:

GitHub WebhookPush / Pull Request

Signature VerifySHA256 Hook Secret

Job EnqueueBullMQ Redis

Worker WorkerFilter files & YAML

Vector Databasepgvector IndexingRAG

Gemini Generation3072-dim context

Automated Documentation Pull RequestReady for developer inspection, edit, or direct merging.

architecture

oRPC API and Webhook Reference

Complete backend contract endpoints and routes

GitScribe exposes type-safe, end-to-end procedures via oRPC for web clients alongside secure webhooks for GitHub integrations:

Procedure/Path	Method	Authentication	Description
repos.listConnected	RPC Procedure	Yes (authed)	Queries database to retrieve repositories synced with user account.
repos.connect	RPC Procedure	Yes (authed)	Initiates repository synchronizations, starts BullMQ codebase embeddings indexing.
chat.createSession	RPC Procedure	Yes (authed)	Creates new RAG chat context sessions for AI repo interactions.
chat.sendMessage	RPC Procedure	Yes (authed)	Sends code question queries, processes similarities, streams Gemini text returns with citations.
/api/webhooks/github	HTTP Webhook	Verification Signature	Entry listener endpoint mapping GitHub push and PR webhook payloads.