GitWire

Self-hosted AI governance for GitHub individuals and teams.

GitWire watches your repositories, evaluates policy, runs safe automations, and records proof for every action.

Decide. Execute. Prove.

---

What GitWire Is

GitWire is an AI maintainer control plane for GitHub individuals and teams. It brings repository automation, policy evaluation, quality gates, action tracking, and audit evidence into one self-hosted system.

It is built for maintainers who want automation with clear boundaries: every action should have a reason, a policy basis, an execution record, and a way to verify what happened afterward.

Use GitWire when you want to answer:

• Which repositories need attention?
• Which AI or automation action is allowed to run?
• Why was a label, comment, review, branch, PR, or merge action created?
• Did the action still hold after the repository changed?
• Which decisions were skipped, blocked, retried, or reconciled?

Core Model

GitHub events
    → policy evaluation
    → AI / rule / gate decision
    → managed action
    → reconciliation
    → audit evidence

GitWire is built around three jobs:

Job	Meaning	Examples
Decide	Evaluate policy and risk before acting.	.gitwire.yml, custom rules, trigger filters, quality gates, waivers
Execute	Run controlled automations through workers.	Triage, CI healing, stale management, AI review, merge queue, issue fixes
Prove	Record evidence for every decision and mutation.	Decision logs, action lifecycle, audit trail, reconciliation, dashboard history

---

What It Can Do

Repository Automation

• AI issue and PR triage
• Duplicate issue detection
• CI failure diagnosis and self-healing PRs
• Autonomous issue-fix PRs with scope guards
• Stale issue and PR management
• Branch cleanup and policy reconciliation
• Merge queue workflows, disabled by default until configured
• AI pull request review
• Flaky test and dependency trust workflows
• Cross-repository insights and readiness scoring

Governance

• Per-repo .gitwire.yml policy
• Dry-run mode
• Trigger filters by branch, author, and path
• Custom rule expressions
• Quality gates
• Policy waivers
• Decision log
• Managed action tracking
• Reconciliation of GitWire-created mutations

Operator Surfaces

• REST API
• Next.js dashboard
• Telegram bot
• PostgreSQL-backed audit and activity history

---

Operator Trust & Observability

GitWire is built around a simple operating model: Decide. Execute. Prove.

The dashboard gives operators a proof-oriented view of GitWire automation:

• Managed actions — inspect the lifecycle of proposed, approved, executed, succeeded, failed, and reconciled actions.
• Decision logs — search and filter decisions by repository, pillar, source, target, outcome, trigger event, and time range.
• Waiver visibility — review active, expiring, and expired policy waivers, including who granted them and why.
• Dry-run proof — see what GitWire would have done without mutating GitHub.
• Audit bundles — export bounded JSON or Markdown evidence packages for repositories, targets, pillars, and time windows.

Audit bundles use the audit-bundle/v1 schema and apply recursive redaction for secret-like fields before export.

Place .gitwire.yml in .github/.gitwire.yml or the repository root:

version: 1

pillars:
  triage:
    enabled: true
    auto_label: true
    duplicate_detection: true

  ci_healing:
    enabled: true
    auto_patch: true
    max_fix_attempts: 3
    blocked_file_patterns:
      - ".env*"
      - "secrets/**"
      - "*.pem"
      - "*.key"

  issue_fix:
    enabled: false
    max_file_changes: 3
    max_line_changes: 200
    blocked_paths:
      - "migrations/**"
      - ".github/**"
      - "db/**"

  merge_queue:
    enabled: false

settings:
  dry_run: false

See .gitwire.example.yml for the full reference.

Custom Rules and Quality Gates

GitWire includes a small expression engine for repo-specific automation.

custom_rules:
  docs_only:
    if: "files | every(match('docs/**'))"
    run:
      - action: add-label
        args:
          label: docs

Quality gates evaluate repository metrics before allowing protected actions:

quality_gates:
  default:
    conditions:
      - metric: ci_failure_rate_7d
        operator: "<"
        threshold: 0.3
      - metric: readiness_score
        operator: ">="
        threshold: 40
    block_on_fail: true

The dashboard and API include a playground for testing expressions before shipping policy changes.

---

Policy Preview & Simulation

GitWire helps operators understand policy changes before they affect repositories.

The policy preview workflow is intentionally non-mutating: it does not save config, enqueue jobs, or write to GitHub.

Operators can:

• Validate .gitwire.yml and inspect structured errors, warnings, enabled pillars, dry-run state, risky settings, and normalized redacted config.
• Preview policy behavior in the dashboard before rollout.
• Simulate proposed policy against historical GitWire decisions to see what would act, skip, dry-run, block, or require AI replay.
• Compare impact between the current repo policy and a proposed policy, including dry-run changes, pillar enablement, risk changes, warning changes, and per-event outcome changes.
• Review guardrail recommendations generated by deterministic rules for safer rollout.

Recommended rollout workflow

graph LR
    V[Validate] --> P[Preview]
    P --> S[Simulate]
    S --> C[Compare Impact]
    C --> R[Review Recommendations]
    R --> E[Enable with dry-run]

Loading

1. Validate the proposed policy.
2. Confirm dry-run and enabled pillars.
3. Simulate against recent repository history.
4. Compare proposed behavior against current behavior.
5. Review guardrail recommendations.
6. Roll out with dry-run first when enabling risky or newly permissive automation.

Limitations

• AI-dependent outcomes (triage, AI review, issue-fix) are marked would_require_ai — simulation does not fabricate model outputs.
• Simulation is policy/guard-focused: it evaluates pillar enablement, trigger filters, and dry-run status, not full AI replay.
• Historical events are drawn from the decision_log within the selected time window.

API endpoints

Endpoint	Purpose
POST /api/config/validate	Validate policy YAML, return errors/warnings/risks
POST /api/config/simulate	Replay proposed policy against historical events
POST /api/config/diff-impact	Compare current vs proposed policy behavior
POST /api/config/recommendations	Generate deterministic guardrail recommendations

See Policy Preview API for full reference.

---

Policy Rollout Controls

GitWire turns policy preview into a controlled rollout workflow with approval, promotion, and rollback evidence.

Rollout lifecycle

graph LR
    D[draft] --> V[validated]
    V --> R[review_ready]
    R -->|approve| A[approved]
    R -->|reject| RJ[rejected]
    A -->|promote| P[promoted]
    P -->|rollback| RB[rolled_back]
    D -->|cancel| C[cancelled]
    V -->|cancel| C
    A -->|cancel| C

Loading

How it works

1. Create a rollout plan in draft state with a proposed .gitwire.yml
2. Attach evidence — validation, simulation, diff impact, recommendations
3. Request review — transition to review_ready
4. Approve or reject — requires all evidence attached and critical recommendations acknowledged
5. Promote — writes the approved policy as the active repo policy (previous policy snapshot preserved)
6. Roll back — restores the previous policy if something goes wrong (full audit evidence captured)

Safety guarantees

• Promotion is the only path that writes policy — generic transitions are blocked
• Write-before-transition — if policy write fails, state does not change
• Previous policy snapshot captured before every promotion
• Rollback evidence includes config hashes for audit proof
• Approval requires critical recommendation acknowledgement
• All 4 evidence types required before approval (validation, simulation, diff, recommendations)

API endpoints

Endpoint	Purpose
POST /api/rollouts	Create rollout plan
GET /api/rollouts	List plans with filters
GET /api/rollouts/:id	Get plan detail
PATCH /api/rollouts/:id/evidence	Attach evidence
POST /api/rollouts/:id/approve	Approve plan
POST /api/rollouts/:id/reject	Reject plan
POST /api/rollouts/:id/promote	Promote to live policy
POST /api/rollouts/:id/rollback	Roll back to previous policy

See Rollout API for full reference.

Dashboard: /rollouts page with lifecycle timeline, evidence cards, audit trail, and state-driven actions.

---

Operator Onboarding

GitWire guides new operators from first dashboard login to safe governed rollout.

Setup Checklist

The dashboard shows a first-run setup checklist with 8 checks that surface installation state immediately:

Check	Blocking	What it verifies
GitHub App configured	yes	App ID and private key are set
Database connected	yes	PostgreSQL is reachable
Redis connected	yes	Redis is reachable
GitHub App installed	yes	At least one installation is linked
Repositories synced	yes	At least one repo has been imported
Webhook events received	no (warn)	Webhooks are flowing within the last 7 days
Policy file configured	no (warn)	.gitwire.yml or dashboard overrides exist
Dry-run mode	no (info)	Shows whether dry-run is active

The checklist auto-hides when ready and provides a "next step" CTA with specific recommendations. No secret values are returned — checks report boolean presence only.

Starter Policy Templates

When .gitwire.yml is missing, the checklist shows safe starter templates with explicit safety labels:

Template	Safety Label	Best For
Starter (Dry-Run)	Dry-run protected	Safest first config — all pillars observe only
Triage Only	Low-risk live	Issue/PR labeling — labels and comments only
CI Healing (Preview)	Safe to preview	CI diagnosis without patching
Open-Source Maintainer	Review before rollout	Balanced automation for public repos
Strict Governance	Dry-run protected	Enterprise/regulated repos — audit-first

Onboarding Walkthrough

A complete 10-step walkthrough takes operators from install to first governed rollout:

graph LR
    A[Install] --> B[Configure App]
    B --> C[Start Services]
    C --> D[Open Dashboard]
    D --> E[Use Checklist]
    E --> F[Pick Template]
    F --> G[Validate]
    G --> H[Simulate]
    H --> I[Create Rollout]
    I --> J[Approve & Promote]

Loading

API endpoints

Endpoint	Purpose
GET /api/setup	Return 8-check setup status with overall state and next step
GET /api/setup/templates	List all starter policy templates with metadata
GET /api/setup/templates/:id	Get a single template with full YAML content

---

Architecture

GitHub Webhooks
      |
      v
Express API (:3000)
      |
      v
Redis 7 + BullMQ queues
      |
      v
9 background workers
      |
      v
PostgreSQL 16
      |
      +--> Next.js dashboard (:3001)
      +--> Telegram bot (:3002)

Monorepo Packages

Package	Role
@gitwire/core	Shared constants and enums with zero runtime dependencies
@gitwire/runtime	PostgreSQL, Redis, queues, logger, and GitHub client factories
@gitwire/rules	Config schema, expression engine, custom rules, and quality gates
@gitwire/web	Express API, routes, services, and BullMQ workers
web-dashboard	Next.js 16 dashboard
@gitwire/bot	Telegram bot using Grammy
@gitwire/worker	Future generic worker package
@gitwire/triage	Future triage extraction package
@gitwire/healer	Future CI-healing extraction package
@gitwire/maintainer	Future maintainer extraction package
@gitwire/mcp	Future MCP integration package
@gitwire/cli	Future CLI package

---

Dashboard

The dashboard provides real-time visibility into the GitWire control plane.

Key areas:

• Overview and fleet health
• Setup checklist (first-run guided onboarding)
• Repository readiness
• Action lifecycle
• Activity feed
• CI healing
• Issue triage
• Pull request intelligence
• Duplicate detection
• Maintainer workflows
• Custom rules
• Config playground
• Quality gates
• Decision logs (search/filter by repo, pillar, source, outcome, trigger, time range)
• Dry-run proof view (non-mutating evaluation evidence)
• Policy waivers (active, expiring, expired, with decision linkage)
• Audit bundle export (JSON + Markdown, redacted)
• Webhook deliveries
• Trust and dependency workflows

---

Telegram Bot

GitWire ships with a Telegram bot for operational checks and lightweight commands.

/status system health and recent activity /repos connected repositories /readiness fleet readiness scores /gates owner/repo quality gate status /evaluate owner/repo run quality gates /deliveries webhook delivery stats /decisions recent decision log /config owner/repo resolved GitWire config /activity action summary /actions recent managed actions /dry-run dry-run proof view /policy-preview policy validation, simulation, diff, recommendations /rollouts policy rollout lifecycle with approval, promotion, rollback

---

Quick Start

Requirements

• Node.js 20+
• npm
• Docker and Docker Compose

GitHub App credentials and an Anthropic API key are needed for GitHub connection, AI diagnosis, and action execution. They are not required to start the local server — see GitHub App setup and Environment variables when you are ready to connect GitHub.

Local Development

The local development setup runs PostgreSQL and Redis in Docker containers and the Node.js application directly on your machine.

# 1. Clone and install dependencies
git clone https://github.com/Octo-Lex/GitWire.git
cd GitWire
npm install

# 2. Copy the environment template
cp packages/web/.env.example packages/web/.env
# The template already contains local-development defaults:
#   DATABASE_URL=postgresql://gitops:password@localhost:5432/gitops_hub
#   REDIS_URL=redis://localhost:6379
# GitHub and Anthropic credentials can be added later.

# 3. Start PostgreSQL and Redis (waits for health checks)
docker compose -f packages/web/docker/docker-compose.yml up -d --wait

# 4. Apply database migrations (run once during initial setup)
npm run db:migrate
# Re-running this command is safe — it reports already-applied migrations.

# 5. Start the backend server
npm run dev
# Backend: http://localhost:3000

# 6. In a separate terminal, start the dashboard
npm --workspace=web-dashboard run dev
# Dashboard: http://localhost:3001

Verify the local server

curl http://localhost:3000/health
# Expected: {"status":"ok",...}

GitHub connection, repository diagnosis, AI recommendations, and action execution require their external credentials and are outside the infrastructure-only startup described above.

Common Commands

npm run dev          # Start backend development server
npm run start        # Start backend server
npm run build        # Build all workspaces with build scripts
npm test             # Run workspace tests when present
npm run db:migrate   # Apply PostgreSQL migrations

---

Current Scale

Area	Current Shape
Backend workers	9 BullMQ workers
Database	45 tables across 19 migrations
Dashboard	25 app sections
Backend routes	Express REST API with webhook ingestion
Policy engine	.gitwire.yml, expressions, custom rules, quality gates
Onboarding	Setup checklist, 5 starter templates, 10-step walkthrough
Interfaces	REST API, dashboard, Telegram bot
Tests	1,497 across rules, runtime, web services, and dashboard
Documentation	120+ pages

---

Documentation

Documentation lives in docs/.

Recommended starting points:

• First-run onboarding walkthrough
• Docker Compose setup
• GitHub App setup
• Environment variables
• Policy-as-code
• Expression language
• Custom rules
• Quality gates
• Risk scoring
• System architecture
• REST API reference

---

Security Model

GitWire is designed around explicit control and auditability:

• API-key authentication for REST endpoints
• GitHub webhook HMAC verification
• Per-repo policy controls
• Dry-run mode for safe rollout
• Scope guards for autonomous fixes
• Blocked file/path patterns
• Decision logs for skipped, blocked, and executed actions
• Managed action records for GitWire-created mutations
• Reconciliation to detect stale or invalidated actions
• Dry-run proof view — non-mutating evidence labeled distinctly from executed actions
• Audit bundle export — recursive redaction of secret-like fields (token, secret, password, private_key, api_key, pem, etc.) before any export
• Policy waivers — time-limited exceptions with full audit trail (who, why, when, expiry)
• Policy preview workflow — validation, simulation, diff impact, and recommendations are all non-mutating: no config saves, no queue jobs, no GitHub writes
• Guardrail recommendations — deterministic, rule-based rollout advice (no AI-generated guidance in policy preview)
• Policy rollout controls — governed lifecycle (draft → validated → approved → promoted → rolled_back) with approval workflow, evidence requirements, and rollback evidence
• Promotion is the only write path — policy writes only happen through the dedicated promote endpoint, never through generic transitions
• Previous policy snapshots — captured before every promotion for safe rollback

For production, run GitWire behind HTTPS, restrict dashboard access, rotate API keys, and give the GitHub App only the permissions required for the enabled workflows.

---

Why GitWire

GitHub repositories accumulate operational work quickly: issues need triage, pull requests need review, CI failures need diagnosis, stale work needs follow-up, and repository policies need consistent enforcement.

GitWire gives maintainers a single place to define policy, run automations, inspect decisions, and prove what happened.

What GitWire offers:

• A self-hosted automation layer for GitHub operations
• Policy-as-code for repository behavior
• AI-assisted triage, review, and repair workflows
• Quality gates and readiness signals before sensitive actions
• A full action lifecycle for repository mutations
• A dashboard for fleet-wide visibility
• A Telegram bot for operational checks and alerts
• Audit records for decisions, skipped actions, failures, and reconciliations

The goal is simple: help maintainers move faster while keeping automation explainable, bounded, and accountable.

---

Project Status

GitWire is under active development. Core platform pieces are implemented, while several extraction packages remain placeholders for future modularization.

Good fit today:

• Self-hosted experiments
• Internal GitHub automation
• Small-team repository governance
• AI maintainer workflow prototypes

Still maturing:

• Enterprise benchmark suite
• Full external scanner ingestion
• Sandboxed patch validation
• Hardened merge queue batching/speculation
• Stable plugin/MCP ecosystem

---

License

MIT