Skip to content

About

An agentic AI system that investigates GitHub issues, generates code fixes, runs tests in an isolated sandbox, and prepares pull requests for human review.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

GitResolve

GitResolve

Investigate issues. Verify fixes. Keep humans in control.

GitResolve is an autonomous, verification-centric AI issue investigation and repair platform for Python repositories. It analyzes issues, builds an actionable investigation plan, reproduces faults, verifies candidate patches in a hardened Docker sandbox, and creates draft GitHub pull requests only after explicit human approval.

Launch Live App    Watch Demo Video

CI   Python 3.12   FastAPI   Next.js   Docker   Gemini

Overview • Showcase • Workflow Architecture • Components • Deployment • Run Locally


What it does

GitResolve turns a GitHub issue or a direct bug report into a reviewable, fully-tested repair workflow. It gathers repository context, develops an investigation plan, checks whether the reported failure can be reproduced, and validates a proposed patch inside an isolated Docker sandbox before asking for approval.

The workflow has two explicit human gates:

  1. Gate 1 — Approve the plan before repair execution begins. Developers can engage in interactive multi-turn dialogue with the agent to clarify constraints or refine the approach.
  2. Gate 2 — Approve the exact verified diff before GitHub publication. Developers inspect the full diff, reproduction evidence, and test receipts.

Approval is cryptographically bound to the diff hash that was reviewed. Any subsequent change invalidates the approval and requires re-verification. GitResolve creates draft pull requests; it never auto-merges into target repositories.


Visual Showcase

1. Connected Repositories & Real-Time Issue Sync

Select from your installed GitHub repositories, inspect open issues, and trigger repairs with a single click.

Connected Repositories and Issues



2. Gate 1: Conversational Plan Review

Before any code changes occur, review the agent's structured investigation plan, budget allocation, and discuss adjustments in natural language.

Gate 1 Plan Review



3. 13-Stage Agent Execution & Live Event Stream

Watch the agent worker execute baseline tests, fault localization, test reproduction, and patch generation with real-time streaming telemetry.

Repair Progress and Event Stream



4. Draft Pull Request Created

Inspect the verified diff hash and test receipts. Upon your authorization, GitResolve publishes a clean draft Pull Request to GitHub.

Pull Request Created

Agentic Workflow & Verification Architecture

flowchart TD
    subgraph Ingestion ["1. INGESTION & PLANNING"]
        A["GitHub Issue or Bug Report"] --> B["FastAPI Control Plane: Validate & Store Task"]
        B --> C["Asynchronous Worker Claims Distributed Lease"]
        C --> D["LangGraph Planning Engine"]
        D --> E["Structured Investigation Plan & Budget"]
    end

    subgraph Gate1 ["GATE 1: HUMAN PLAN REVIEW"]
        E --> G1{"Developer Plan Review<br/>(Interactive Dialogue)"}
        G1 -- "Request Re-plan / Clarify" --> D
        G1 -- "Reject / Cancel" --> X1["Task Cancelled"]
        G1 -- "Approve Plan" --> F["Dispatch Repair Phase"]
    end

    subgraph SandboxExecution ["2. HARDENED DOCKER SANDBOX REPAIR LOOP"]
        F --> G["Acquire Pinned Git Snapshot"]
        G --> H["Launch Ephemeral Docker Container<br/>(No Network, No Host Secrets, Read-Only FS)"]
        H --> I["Execute Baseline Test Suite"]
        I --> J["Agent Fault Localization & Minimal Reproduction Test"]
        J --> K["Propose Constrained Code Patch"]
        K --> L["Sandbox Verification: Full Suite + Regression Test"]
        L --> M{"Deterministic Policy & Safety Gate"}
        M -- "Tests Fail / Scope Exceeded" --> N["Iterate / Backtrack Repair"]
        N --> K
    end

    subgraph Gate2 ["GATE 2: HUMAN DIFF APPROVAL"]
        M -- "Verified Patch" --> G2{"Developer Diff Approval<br/>(Review Exact Diff Hash & Test Receipts)"}
        G2 -- "Reject Patch" --> N
        G2 -- "Approve Exact Diff" --> O["Publication Phase Dispatched"]
    end

    subgraph Publication ["3. GITHUB PUBLICATION"]
        O --> P["Cryptographic Hash & Receipt Re-validation"]
        P --> Q["Create Isolated Fix Branch"]
        Q --> R["Commit Verified Patch"]
        R --> S["Open Draft Pull Request on GitHub"]
    end

    classDef gate fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#f8fafc;
    classDef success fill:#064e3b,stroke:#10b981,stroke-width:2px,color:#f8fafc;
    class G1,G2 gate;
    class S success;
Loading

Architecture & Components

GitResolve separates the user-facing web application, control plane, asynchronous agent worker, external integrations, and repository execution boundary. The API coordinates requests and persists task state; repository code is run exclusively inside hardened Docker containers.

Component Responsibilities

Component Responsibility Isolation Boundary
Frontend Next.js 14 web client: Firebase Google auth, GitHub installation flow, task timeline, interactive plan review, and diff inspection. Firebase sign-in and backend GitHub sessions are strictly decoupled. The browser never receives GitHub App private keys.
API · backend guide FastAPI control plane: versioned REST API, request validation, authentication, ownership checks, task lifecycle, and event streaming. Never executes repository code. Dispatches jobs to durable persistence without blocking on execution.
Services · store Task transitions, policy enforcement, GitHub access management, and persistence abstractions. Firestore access is isolated behind typed store interfaces. Repository permissions are validated directly against GitHub.
Worker Background runner: claims plan, execute, and publication phases; maintains distributed leases; handles cancellation. Runs outside API request threads; production deployments run on dedicated VM instances sharing durable Firestore storage.
Agent runtime · model router Dual LangGraph workflows (planning & repair), typed state, tool schemas, and task-scoped token budgets. Agent output constitutes evidence/proposals; backend policy gates determine task transitions. Model calls route through ModelRouter.
GitHub integration · setup guide Installation-scoped OAuth tokens, repository syncing, and PR publication. Publication re-validates the approved diff hash, base SHA, and trusted Docker verification receipt.
Sandbox Hardened execution runner: acquires pinned repository snapshots, prepares wheel dependencies, and runs tests in Docker. Receives no host credentials or Docker socket; execution runs with network disabled.

Production Deployment Architecture

GitResolve is architected as a resilient, decoupled cloud system deployed across Google Cloud Platform and Vercel:

flowchart TD
    Frontend["Next.js 14 Frontend - Vercel Edge Network"]
    API["FastAPI Control Plane - Google Cloud Run"]
    Firestore[("Google Cloud Firestore - Transactional Task Store")]
    subgraph GCE ["Google Compute Engine VM (e2-standard-4)"]
        Worker["GitResolve Agent Worker - Async Daemon"]
        Sandbox["Hardened Docker Sandbox - Isolated Container"]
        Worker --> Sandbox
    end
    External["External APIs - Google GenAI & GitHub App"]

    Frontend -- "HTTPS REST (Firebase Bearer Token)" --> API
    API -- "ACID Task State & Events" --> Firestore
    Worker <-- "Distributed Lease Polling & State Updates" --> Firestore
    Worker -- "Model Routing & PR Publication" --> External
Loading
  • Frontend on Vercel: Hosted at gitresolve-agent.vercel.app, delivering edge-cached static assets, dark-mode terminal aesthetics, and reactive polling for real-time lifecycle event logs.
  • API on Google Cloud Run: Containerized FastAPI service with automated HTTPS, autoscaling, and secure environment variable injection via Google Secret Manager.
  • Worker on Google Compute Engine (GCE): Dedicated Ubuntu VM (e2-standard-4) hosting the persistent background daemon and the local Docker daemon required for untrusted repository code execution.
  • Persistence on Google Cloud Firestore: Central document database enforcing ACID transactions for distributed worker leases, task status transitions, and immutable event streams.
  • LLM Routing via Google GenAI: Powered by Gemini 2.5 and 3.8 Flash via a specialized ModelRouter enforcing per-task token quotas, bounded retries, and fallback handling.

Safety and Support Boundaries

  • Untrusted Inputs: Model responses and repository contents are treated as untrusted input.
  • Independent Policy Gates: Deterministic scope and diff checks, verification receipts, and backend approval gates—not model confidence—control whether a patch can be published.
  • Container Isolation: Repository commands and tests run in Docker, never on the API or worker host. Execution containers run with network disabled and receive no host credentials.
  • Diff Hash Integrity: The exact SHA-256 hash of the unified diff approved by the developer must match the publication payload byte-for-byte.
  • Supported Targets: Currently optimized for Python 3.12 repositories on Linux x86-64 using pytest and Streamlit AppTest.

Limits & Budgets

Limit Value Where it's defined (file/constant)
Max model calls per task 50 backend/app/core/config.py (Settings.max_model_calls), backend/app/services/policy.py (HARD_CAPS["maxModelCalls"])
Max repair attempts per task 6 (cap: 1–12) backend/app/core/config.py (Settings.max_repair_attempts), backend/app/services/policy.py (HARD_CAPS["maxRepairAttempts"])
Max tool calls per task 120 backend/app/agent/graph_engine/state.py (DEFAULT_MAX_TOOL_CALLS)
Max graph steps per task 240 backend/app/agent/graph_engine/state.py (DEFAULT_MAX_GRAPH_STEPS)
Max specialist (gemini-4-argon) calls 2 backend/app/agent/graph_engine/state.py (MAX_SPECIALIST_CALLS_PER_TASK)
Input / output token budget 300,000 / 40,000 tokens backend/app/agent/graph_engine/state.py (DEFAULT_MAX_INPUT_TOKENS, DEFAULT_MAX_OUTPUT_TOKENS)
Diff scope limit 5 files, 150 lines (400 max w/ deletions) backend/app/core/config.py (Settings.max_diff_files, Settings.max_diff_lines), sandbox/models.py (ExecutionRequest.max_diff_lines)
Sandbox command timeout 60s default (300s max) sandbox/models.py (ExecutionRequest.timeout_seconds), backend/app/core/config.py (Settings.execution_timeout_seconds)
Task execution timeout 1,800s (30 min) backend/app/core/config.py (Settings.task_timeout_seconds)
Worker lease / heartbeat 90s lease / 30s heartbeat backend/app/core/config.py (Settings.lease_seconds, Settings.heartbeat_seconds)
Daily task quota 10 tasks/day backend/app/core/config.py (Settings.max_tasks_per_day)
API rate limits 300 req/min per IP, 30 writes/min per user backend/app/core/config.py (Settings.rate_limit_per_minute_ip, Settings.rate_limit_writes_per_minute_user)

Getting Started

Prerequisites

  • Python 3.12 and uv
  • Node.js 18+ and npm
  • Docker with Linux container support

Install Dependencies

From the repository root, install the Python environment:

uv sync --group dev

Install frontend dependencies:

cd frontend
npm ci

Run Local Development Services

  1. Start the API backend (from repository root):

    uv run python -m uvicorn app.main:app --app-dir backend --reload --host 127.0.0.1 --port 8000
  2. Start the frontend (from frontend/):

    npm run dev
  3. Verify endpoints:

    • Web application: http://localhost:3000
    • API health check: http://localhost:8000/health

Development Checks

Run the backend test suite:

uv run pytest -q

Run frontend linting, typechecking, and production build:

npm --prefix frontend run lint
npm --prefix frontend run build

Documentation

Core Guides

Specifications & Compliance


Repository Layout

agent/       Model routing and shared agent utilities
assets/      Brand assets and application screenshots
backend/     FastAPI application, worker daemon, and test suites
docs/        System architecture, schemas, and compliance specifications
frontend/    Next.js 14 web application
githubapp/   GitHub App integration and publication services
sandbox/     Docker execution runner and verification profiles
scripts/     Operational and deployment scripts

License

All rights reserved.

GitResolve is publicly available for viewing and evaluation purposes. No open-source license is granted. Unauthorized copying, modification, redistribution, or commercial use of the source code is not permitted, except as allowed by applicable law or GitHub's Terms of Service.

About

An agentic AI system that investigates GitHub issues, generates code fixes, runs tests in an isolated sandbox, and prepares pull requests for human review.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages