5-Minute Quickstart Guide

Get your own private ProGit instance running with Podman or Docker in less than five minutes.

Step 1: Launch Container

Run the following command in your terminal to start ProGit with persistent volumes:

podman run -d --name progit \
  -p 3000:3000 -p 3443:3443 -p 2222:2222 \
  -v progit-data:/data \
  localhost/progit:latestCopy

docker run -d --name progit \
  -p 3000:3000 -p 3443:3443 -p 2222:2222 \
  -v progit-data:/data \
  progit/progit:latestCopy

Step 2: Complete Setup Wizard

1. Open your browser and navigate to http://localhost:3000.
2. Fill in your desired Super Administrator username, email, and password.
3. Click Complete Installation & Create Super Admin. ProGit will lock the setup and redirect you to the main dashboard.

Step 3: Create & Push to Your First Repository

# Create test directory and initialize git
mkdir my-project && cd my-project
git init
echo "# Hello ProGit" > README.md
git add README.md
git commit -m "Initial commit"

# Push over Smart HTTP
git remote add origin http://localhost:3000/<your-username>/my-project.git
git push -u origin mainCopy

Architecture & Pure Go Engine

Understand how ProGit achieves maximum portability, concurrency, and security with zero CGO dependencies.

Pure Go SQLite WAL Engine

Traditional Git web applications that use SQLite rely on CGO bindings to the C SQLite library (such as mattn/go-sqlite3). This causes several critical operational headaches: slow cross-compilation, reliance on host GCC/Clang toolchains, and complex multi-architecture container setups.

ProGit completely eliminates CGO by using modernc.org/sqlite — a 100% pure Go translation of SQLite. Features include:

• Zero CGO (CGO_ENABLED=0): Single static Go binary without libc/musl dependency conflicts.
• Write-Ahead Logging (WAL) Mode: Allows concurrent readers without blocking write transactions.
• Busy Timeout & Mutex Protections: Configured with 5000ms busy timeout to prevent database is locked errors during high-volume Git pushes.

Technology Stack

Project Credits & Attributions

Recognizing the sponsors, creators, and open-source foundations behind ProGit.

Acknowledgments

• Prodevans: For enterprise platform sponsorship, infrastructure support, and continued cloud-native stewardship.
• Sanjeev Senapati: Architect, primary creator, and maintainer of the modern ProGit codebase.
• The Gogs Project: Special appreciation to Jiahua Chen (Unknwon) and the Gogs community for pioneering lightweight Git services in Go.

Podman & Docker Deployment

Deploying ProGit with production-grade container isolation and persistent volumes.

Automated Deployment Script

ProGit includes dedicated scripts for one-click building and deployment using Podman or Docker:

# Build the lightweight Alpine container image (~37 MB)
bash podman/build.sh

# Deploy with persistent volumes and healthcheck validation
bash podman/deploy.shCopy

Volume Persistence

ProGit stores all state in /data inside the container. We recommend mapping named volumes to ensure seamless data persistence across container updates:

Docker Compose Example

version: '3.8'
services:
  progit:
    image: localhost/progit:latest
    container_name: progit
    restart: always
    ports:
      - "3000:3000"
      - "3443:3443"
      - "2222:2222"
    environment:
      - PROGIT_APP_NAME=ProGit
      - PROGIT_DOMAIN=git.example.com
      - PROGIT_ROOT_URL=https://git.example.com/
      - PROGIT_PROTOCOL=https
      - PROGIT_HTTPS_PORT=3443
    volumes:
      - progit-data:/data

volumes:
  progit-data:Copy

Standalone Binary Installation

Run ProGit directly on Linux or macOS as a native system daemon without containers.

1. Create System User and Directories

sudo adduser --system --shell /bin/bash --gecos 'ProGit Version Control' --group --disabled-password --home /home/git git
sudo mkdir -p /data/db /data/repositories /data/config /data/logs
sudo chown -R git:git /dataCopy

2. Place Binary

sudo cp progit /usr/local/bin/progit
sudo chmod +x /usr/local/bin/progitCopy

3. Systemd Service File

Create /etc/systemd/system/progit.service:

[Unit]
Description=ProGit Service
After=syslog.target
After=network.target

[Service]
Type=simple
User=git
Group=git
WorkingDirectory=/data
ExecStart=/usr/local/bin/progit web
Restart=always
Environment=PROGIT_APP_NAME="ProGit"

[Install]
WantedBy=multi-user.targetCopy

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now progitCopy

Compile From Source

Build both the React UI and Go backend from the official repository.

Prerequisites

• Go 1.24 or higher
• Node.js 22+ and npm
• Git CLI installed on system

Build Instructions

# 1. Clone repository
git clone https://github.com/sanjeevsenapati/progit.git
cd progit

# 2. Build Frontend UI
cd web
npm ci
npm run build
cd ..

# 3. Copy built frontend assets into internal/ui/dist
cp -r web/dist/* internal/ui/dist/

# 4. Compile Pure Go Binary (Zero CGO)
CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o progit ./cmd/progit

# 5. Start ProGit
./progit webCopy

Web Installation Wizard

Configure your instance parameters and initialize the Super Administrator.

Wizard Fields

HTTPS & TLS Configuration

Securing Git traffic with automatic TLS, HSTS, and custom certificates.

Built-in HTTPS Server

ProGit features a native HTTPS engine that runs simultaneously alongside HTTP. To activate TLS directly in conf/app.ini:

[server]
PROTOCOL = https
DOMAIN = git.example.com
ROOT_URL = https://git.example.com:3443/
HTTP_PORT = 3000
HTTPS_PORT = 3443
CERT_FILE = /data/config/https/cert.pem
KEY_FILE = /data/config/https/key.pemCopy

Automatic Self-Signed Certificates

If CERT_FILE or KEY_FILE are not specified when PROTOCOL = https, ProGit automatically generates an ECDSA P-256 self-signed certificate on boot, ensuring immediate encryption without configuration.

Reverse Proxy Setup

Configuring Nginx or Caddy in front of ProGit for SSL termination and custom domains.

Nginx Configuration

server {
    listen 80;
    server_name git.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name git.example.com;

    ssl_certificate /etc/letsencrypt/live/git.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/git.example.com/privkey.pem;

    client_max_body_size 500M;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}Copy

Caddy Configuration

git.example.com {
    reverse_proxy 127.0.0.1:3000
    request_body {
        max_size 500MB
    }
}Copy

Configuration Cheat Sheet

A fast reference for essential ProGit configuration keys.

# ProGit Global Configuration File
# Location: conf/app.ini or /data/config/app.ini

[app]
NAME = ProGit
RUN_MODE = prod
RUN_USER = progit

[server]
PROTOCOL = http
DOMAIN = localhost
ROOT_URL = http://localhost:3000/
HTTP_PORT = 3000
HTTPS_PORT = 3443
DISABLE_SSH = false
SSH_PORT = 2222
SSH_LISTEN_PORT = 2222

[database]
TYPE = sqlite3
PATH = /data/db/progit.db

[repository]
ROOT = /data/repositories
DEFAULT_BRANCH = main

[security]
INSTALL_LOCK = true
SECRET_KEY = !#@FDEW&*(#$@*
LOGIN_REMEMBER_DAYS = 7

[pages]
ENABLED = trueCopy

app.ini File Reference

Comprehensive documentation of all available configuration blocks in app.ini.

Section: [server]

Section: [database]

Environment Variables Reference

All app.ini keys can be overridden via container environment variables with PROGIT_* prefixes.

Database & SQLite WAL Mode

How ProGit configures SQLite for high-concurrency enterprise workloads.

Write-Ahead Logging (WAL)

ProGit automatically configures SQLite with the following pragmas on connection initialization:

PRAGMA journal_mode = WAL;
PRAGMA synchronous = NORMAL;
PRAGMA busy_timeout = 5000;
PRAGMA foreign_keys = ON;Copy

Automated WAL Checkpoints

In WAL mode, writes are committed to a temporary journal file (progit.db-wal) and periodically merged into the main database file. Administrators can trigger a manual checkpoint at any time via the admin endpoint:

curl -X POST http://localhost:3000/api/v1/admin/maintenance/wal-checkpoint \
  -H "Authorization: Bearer <admin_token>"Copy

Built-in SSH Server (Port 2222)

Secure, key-based Git operations without needing host OpenSSH integration.

SSH Key Generation

ProGit generates host Ed25519 and RSA keys in /data/ssh/ if none exist. Git clients can authenticate directly using their public keys.

User Key Registration

1. Generate an Ed25519 key pair on your local machine:

   ssh-keygen -t ed25519 -C "your_email@example.com"Copy

2. Copy the contents of ~/.ssh/id_ed25519.pub.
3. In ProGit, navigate to User Settings > SSH Keys > Add Key.
4. Paste the public key and save. You can now clone and push over SSH!

Smart HTTP & SSH Git Operations

Full compliance with the Git v2 Smart Transfer Protocol.

Clone Formats

• HTTP/HTTPS: http://localhost:3000/<owner>/<repo>.git
• SSH: ssh://git@localhost:2222/<owner>/<repo>.git
• Wiki HTTP: http://localhost:3000/<owner>/<repo>.wiki.git
• Wiki SSH: ssh://git@localhost:2222/<owner>/<repo>.wiki.git

Blank Repository Quick Setup (GitHub-Style)

When creating a repository without an initial README (or when a bare repository has zero commits), ProGit displays a comprehensive setup guide matching GitHub's workflow:

• Quick Setup Bar: Instant toggle between HTTPS and SSH clone URLs with one-click clipboard copying.
• Create a new repository on the command line: Ready-to-copy terminal commands initializing Git, adding a README, committing, setting main branch, and pushing to ProGit.
• Push an existing repository from the command line: Copyable commands to add ProGit as remote and push existing branches.
• Import code from another repository: Direct shortcut button linking to the repository import wizard.

Repository Import

ProGit allows importing external Git repositories directly via /new/import or POST /api/v1/repos/import. The server clones the entire history (all commits, branches, and tags) using Git mirror replication and seamlessly binds it to your personal or organization account.

Online Code Editor & Prettier Themes

Feature-rich in-browser editing with real-time syntax highlighting and 8 Prettier themes.

8 Curated Themes

Online Commits

Edit any file, provide a custom commit message and optional extended description, and choose between committing directly to the active branch or creating a new feature branch.

File Creation & Directory Uploads

Create nested paths online, upload multiple files, and import whole directories.

Nested File Creation

When creating a new file online, type the entire target path (e.g., src/controllers/auth.go). ProGit automatically creates intermediate directories and commits the file atomically.

Directory Uploads with Subdirectory Preservation

ProGit supports dragging and dropping whole folders or using the Upload a directory picker. Folder structures like assets/icons/logo.svg are preserved and committed in a single atomic Git tree update.

Branch Management & Protection

Branch lifecycle management, UI creation, commit stats, and default branch protection.

Branch Overview

The Branches page displays:

• Active branches and their latest commit SHA, author, and timestamp.
• Ahead / Behind commit counts relative to the default branch.
• Branch deletion controls (with safety protection on the default branch).

Quick Branch Creation

Create branches directly from the branch dropdown in the repository code view or from the dedicated Branches management screen.

Pull Requests, Code Review & Merges

Full GitHub-style code collaboration with unified diffs, inline comments, and native merges.

Branch Comparison

Compare any two branches across commits. The compare view highlights added, modified, and deleted lines with unified diff formatting.

Formal Code Review States

• Approve: Submit an approval to authorize merging.
• Request Changes: Indicate blocking feedback that must be addressed.
• Comment: General feedback without explicit approval/rejection.

Native Git Merges

Authorized reviewers and repository owners can execute a native Git merge with a single click. ProGit performs the merge on the server side and commits the merge commit to the target branch.

Repository Forking

Fork repositories into your personal account or any organization you administer.

Fork Mechanics

When you click Fork on any repository:

1. ProGit prompts you to select the target destination (your personal account or an organization).
2. A complete server-side clone of the bare repository is initialized on disk.
3. All branches, tags, commit histories, and refs are preserved.
4. Parent-fork relationships are tracked, allowing cross-repository Pull Requests.

ProGit Pages (Static Site Hosting)

Host static sites, documentation, and HTML portfolios directly from your Git repositories.

Enabling ProGit Pages

1. Navigate to your repository and click the Pages tab.
2. Toggle Enable ProGit Pages on.
3. Choose your source branch (e.g. main or docs) and source directory (/ or /docs).
4. Click Save Pages Settings.

Public Website URL

Your site is immediately published at:

http://localhost:3000/pages/<owner>/<repo>/

Git-Backed Wiki Engine

Dual-mode documentation: edit via web UI or clone as a native Git repository.

Cloning the Wiki via Git

Every repository has an independent Git-backed wiki bare repository:

git clone http://localhost:3000/<owner>/<repo>.wiki.git

Commit your .md markdown files locally and push to origin; they immediately appear on the web Wiki!

Kanban Project Boards

Agile task and project tracking embedded into every repository.

Features

• Default columns: To do, In progress, and Done.
• Add custom columns (e.g. In Review, Backlog).
• Task cards supporting freeform Markdown notes or links to existing repository Issues.
• Card movement between columns with automatic completion percentage metrics.

Organizations, Teams & Access Controls

Manage company repositories, team assignments, and fine-grained collaborator permissions.

Roles & Access Levels

• Organization Owner: Complete control over the organization, all its teams, members, and repositories.
• Team Permissions:
  • read: Can clone and view code, issues, and wiki.
  • write: Can push commits, create branches, edit online, and manage project boards.
  • admin: Full settings and collaborator management on team repositories.
• External Collaborators: Invite individual users to private repositories with granular read, write, or admin permissions without adding them to an organization.

Webhooks & Automated Delivery

Trigger CI/CD pipelines, Slack/Discord notifications, and custom webhooks automatically on Git push, issue, and pull request events.

Overview

ProGit features an asynchronous, pure-Go webhook dispatch engine. When events occur in your repository (such as code pushes over HTTP or native SSH, issue creation, or pull request reviews), ProGit queues and delivers HTTP POST payloads with cryptographic HMAC signatures to your subscribed endpoints.

Supported Event Triggers

Cryptographic Signature Verification (HMAC-SHA256)

When you configure a secret token on a webhook, ProGit calculates a cryptographic HMAC-SHA256 signature for every payload and transmits it in both standard GitHub-compatible and ProGit headers:

• X-Hub-Signature-256: sha256=<hex-encoded HMAC signature>
• X-ProGit-Signature: sha256=<hex-encoded HMAC signature>
• X-ProGit-Event: The event name (e.g. push, issues, pull_request, ping)
• X-ProGit-Delivery: Unique delivery UUID for tracing and idempotency

import hmac, hashlib

def verify_progit_signature(payload_bytes, secret_key, header_signature):
    expected = "sha256=" + hmac.new(secret_key.encode(), payload_bytes, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header_signature)Copy

Delivery Logs & Test Pings

Repository administrators can trigger an immediate test ping from the Repository Settings → Webhooks tab to verify network connectivity and signature verification. Each delivery is logged with full request/response diagnostics, HTTP status codes, and execution duration.

Developer Direct Messaging

Built-in developer communication system for private messaging, peer feedback, and sprint coordination.

Overview

ProGit includes an integrated messaging system that allows developers and contributors to communicate privately within the platform without leaving their code workspace. Whether coordinating code reviews, discussing sprint priorities, or providing private feedback, developers can exchange messages directly.

Key Capabilities

• Real-time Unread Badge: The top navigation bar displays a live unread message counter that updates as messages arrive.
• Inbox & Outbox: Clean tabbed interface separating received messages from sent communications.
• One-Click Reply: Reply directly to sender with automated subject prefixing (Re: ...) and conversation continuity.
• Quick Developer Directory: Message composer with auto-population of active platform developers.
• Markdown Formatting: Messages support rich Markdown text, code blocks, lists, and inline links.

Danger Zone & Repository Security

Critical administrative actions: visibility toggling, read-only archiving, ownership transfers, and collaborator security.

Danger Zone Actions

Located in the Settings → Danger Zone tab of every repository, these operations protect high-stakes repository transitions:

Collaborator-Scoped Issue Assignees

• The GET /api/v1/repos/{owner}/{repo}/assignees endpoint returns exclusively users with valid collaborator or owner privileges.
• Assigning an issue to any external user or stranger is blocked at the backend API layer with HTTP 400 Bad Request ("user must be a collaborator or owner of this repository").

Repository Search & Discovery

Real-time debounced autocomplete, keyboard navigation shortcuts, URL-synchronized exploration, and multi-tenant access control.

Global Navbar Search

ProGit provides a responsive, debounced search bar embedded in the global top navigation on every page:

• Real-Time Autocomplete: Matches repositories dynamically across repository names, descriptions, owner handles, and combined owner/repo paths (e.g., cbdc/website or cbdc/) as you type.
• Canonical Git Path Search: Developers can search in owner/repository format directly, allowing instant filtering of specific organizations or owners.
• Root Query & Clean Shortcut Handling: Typing / cleanly focuses the input without character leakage, or returns all accessible repositories when queried directly.
• Rich Dropdown Feedback: Results display the repository owner, name, visibility badges (Private lock or Public), description snippet, and star counts.
• Direct Navigation: Clicking any search result or selecting it via keyboard navigates instantly to the target repository overview.

Keyboard Shortcuts

Designed for power users and keyboard-first developer workflows:

Explore Page Search & Pagination

The Explore page (/explore) allows comprehensive repository discovery with server-side pagination:

• URL Query & Page Binding: Directly open or bookmark /explore?q=keyword&page=2 to immediately navigate to filtered results.
• Interactive Pagination Controls: Displays total repository counts, previous/next controls, and direct page jumps with smooth scrolling.
• Live Browser History: Searching inside the Explore view automatically updates the browser's URL using window.history.replaceState, enabling instant copy-paste sharing with team members.

Multi-Tenant Access Control & Privacy

• Anonymous / Unauthenticated Users: Can only discover public repositories (is_private = false).
• Authenticated Developers: Can discover all public repositories, plus private repositories where they are the owner, a confirmed collaborator, or an organization member.
• System Administrators: Hold global visibility across all public and private repositories.

Super Admin Setup & CLI

Provisioning and managing administrator privileges from the terminal.

CLI User Creation

# Create super administrator via CLI inside Podman / Docker
podman exec -it progit /usr/local/bin/progit admin create-user \
  --username="admin" \
  --email="admin@example.com" \
  --password="YourSecurePassword123!" \
  --adminCopy

User & Key Administration

Administer user accounts, security tokens, and SSH public keys.

Administrative Powers

• Activate / Suspend: Temporarily lock user accounts without deleting repository data.
• Promote / Demote: Grant or revoke system administrator rights. (Self-demotion is blocked to prevent accidental administrative lockouts).
• Delete User: Purge account and associated user repositories from the server.

Repository Oversight & Danger Zone

Global repository management and disk usage telemetry.

Global Repository List

In /admin > Repositories, administrators can inspect all repositories hosted across all user accounts and organizations, including visibility status and disk usage.

Administrative Deletion

Administrators can delete any repository directly from the admin panel. ProGit purges the metadata from SQLite and permanently removes the .git directory from disk.

WAL Checkpoints & System Telemetry

Live Go runtime metrics and database maintenance.

Live Diagnostics Dashboard

In /admin > System Overview, ProGit renders live runtime diagnostics directly from the Go runtime:

• Go compiler version (e.g. go1.24.1)
• Active Goroutine count
• Heap memory allocations and system memory
• Total registered users and repositories

Manual WAL Checkpoint API

curl -X POST http://localhost:3000/api/v1/admin/maintenance/wal-checkpoint \
  -H "Authorization: Bearer <admin_token>"Copy

REST API Overview & Authentication

Interact programmatically with ProGit using the REST v1 API.

Base URL

http://localhost:3000/api/v1

Authentication Methods

ProGit supports two primary authentication schemes for API interaction:

1. Personal Access Tokens (Bearer PAT): Ideal for scripts, CI/CD runners, and automated tools.

   Authorization: Bearer pgt_34f8a92...

2. Web Session Cookie: Sent automatically by browsers when authenticated (`progit_session`). SameSite is enforced with HttpOnly security.

IP Rate Limiting

To neutralize credential brute-force attacks while preserving automated test throughput, authentication routes (/api/v1/auth/login and /api/v1/auth/register) enforce an IP-based sliding window rate limit of 120 requests per minute. Requests exceeding this threshold receive HTTP 429:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "error": "Too many authentication attempts. Please try again later."
}

Standard JSON Error Format

All client and server errors return structured JSON with an explanatory error key:

{
  "error": "resource not found or access denied"
}

Health & Readiness Probes

Verifies Go HTTP server, pure-Go SQLite WAL database connectivity, and repository disk access.

{
  "app": "ProGit",
  "status": "ok",
  "version": "1.0.0",
  "database": "healthy",
  "repositories": "accessible",
  "ssh_enabled": true,
  "uptime": "2h14m"
}

Kubernetes / container readiness probe returning HTTP 200 OK when ProGit is ready to accept traffic.

Users, Tokens & SSH Keys API

Endpoints for registration, session authentication, profile settings, PATs, and SSH keys.

Register User Account

{
  "username": "dev_alice",
  "email": "alice@progit.local",
  "password": "SecretPassword123!",
  "full_name": "Developer Alice"
}

User Login (Create Session)

{
  "username": "dev_alice",
  "password": "SecretPassword123!"
}

Response sets Set-Cookie: progit_session=... and returns user profile:

{
  "message": "Login successful",
  "token": "d307a10bb36...",
  "user": {
    "id": 1,
    "username": "dev_alice",
    "email": "alice@progit.local",
    "is_admin": false
  }
}

Get Current User Profile

Returns the currently authenticated user's session profile, permissions, and administrator status.

User Logout

Clears active session cookie and invalidates session token.

Inspect Public User Profile

Returns public account details, repositories, bio, location, and activity metrics.

Update User Settings

{
  "full_name": "Alice Senior Engineer",
  "bio": "Distributed systems and Go developer",
  "location": "Bengaluru, India",
  "website": "https://github.com/alice"
}

Update Password

{
  "old_password": "SecretPassword123!",
  "new_password": "NewSecretPassword456!"
}

User Dashboard Overview

Retrieves the authenticated developer's personalized dashboard context including their active repositories, paginated recent activity stream, affiliated organizations, and starred projects.

Personal Access Tokens (PAT)

{
  "name": "ci-builder-token",
  "scopes": "repo,user"
}

SSH Public Keys

{
  "title": "MacBook Pro M-Series",
  "key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIGt7..."
}

Repositories & Branches API

Endpoints for repository creation, metadata inspection, stars, collaborators, and branch lifecycle.

List Repositories

Lists repositories. Optional query parameters include ?owner={username} to filter by owner handle, or ?q={query} to perform keyword filtering.

Search Repositories

Global repository search supporting keyword matching against repository name, description, owner username, and combined owner/repo paths (e.g. cbdc/website or cbdc/). Supports ?q=/ to discover all accessible repositories without filter elimination. Includes strict access control: unauthenticated users only discover public repositories; authenticated users discover public repositories and private repositories where they are the owner, a confirmed collaborator, or an organization member.

{
  "ok": true,
  "repositories": [
    {
      "id": 14,
      "name": "cloud-distributed-kv",
      "owner_name": "dev_alice",
      "description": "High performance pure-Go key-value store",
      "is_private": false,
      "num_stars": 12,
      "default_branch": "main"
    }
  ],
  "total": 1
}Copy

Explore Repositories

Retrieves paginated repositories and platform highlights for the Explore page. Supports keyword search via ?q={query}, current page selection via ?page={page}, and page size via ?limit={limit}.

{
  "repositories": [
    {
      "id": 14,
      "name": "cloud-distributed-kv",
      "owner_name": "dev_alice",
      "description": "High performance pure-Go key-value store",
      "is_private": false,
      "num_stars": 12,
      "default_branch": "main"
    }
  ],
  "total": 48,
  "page": 1,
  "limit": 12,
  "total_pages": 4
}Copy

Create Repository

{
  "name": "cloud-distributed-kv",
  "description": "High performance pure-Go key-value store",
  "private": false,
  "auto_init": true,
  "readme": "Default"
}

Import Repository

Clones an external Git repository from GitHub, GitLab, Bitbucket, or any Git remote URL directly into ProGit with complete commit history, branches, and tags. Supports optional authentication credentials for private repositories.

{
  "clone_url": "https://github.com/octocat/Hello-World.git",
  "owner": "dev_alice",
  "name": "Hello-World",
  "description": "Imported repository with full history",
  "private": false,
  "auth_username": "",
  "auth_password": ""
}

Get Repository Details

{
  "id": 14,
  "name": "cloud-distributed-kv",
  "full_name": "dev_alice/cloud-distributed-kv",
  "owner": "dev_alice",
  "default_branch": "main",
  "is_private": false,
  "is_archived": false,
  "can_write": true,
  "is_admin": true,
  "clone_urls": {
    "http": "http://localhost:3000/dev_alice/cloud-distributed-kv.git",
    "ssh": "ssh://git@localhost:2222/dev_alice/cloud-distributed-kv.git"
  }
}

Toggle Repository Star

{
  "starred": true,
  "num_stars": 12
}

List Collaborators

Add / Update Collaborator

{
  "mode": "write"
}

Allowed modes: read (clone and inspect), write (commit and push code), admin (full repository settings).

Revoke Collaborator

List Branches

Pass ?detail=true to return rich branch metadata including author, latest commit SHA, commit message, and relative timestamp.

Create Branch

{
  "branch_name": "feature/raft-consensus",
  "base_ref": "main"
}

Delete Branch

Branch protection blocks deletion of the default repository branch (main / master) with HTTP 400.

List Tags

Commit History & Diffs

File Tree & Online Commits API

Endpoints for browsing trees, reading raw blobs, editing files online, and multi-file directory uploads.

Get Directory Tree

Returns tree entries, root README content (if available), total commits count, and the latest commit details for the requested ref and path (matching GitHub's repository code view).

{
  "entries": [
    {
      "name": "README.md",
      "path": "README.md",
      "type": "blob",
      "size": 1820,
      "sha": "a1b2c3d..."
    }
  ],
  "readme": "# README...",
  "latest_commit": {
    "sha": "f1aecdf5ec1f4faf9656087606decb823193dcc0",
    "short_sha": "f1aecdf",
    "author": "sanjeevsenapati",
    "email": "sanjeev@therasoftonline.com",
    "message": "Initial Commit from cli",
    "timestamp": "2026-11-02T05:07:59Z"
  },
  "total_commits": 7
}Copy

Get Blob File Content

{
  "name": "README.md",
  "path": "README.md",
  "size": 1820,
  "content": "# Cloud KV Store\n\nUltra-fast in-memory...",
  "is_binary": false,
  "language": "markdown"
}

Stream Raw File Bytes

Streams raw file bytes with appropriate Content-Type headers (e.g. image/png, application/octet-stream).

Online File Creation & Update

{
  "branch": "main",
  "content": "package core\n\ntype KV struct {}\n",
  "message": "Add KV core definition"
}

Online File Deletion

{
  "branch": "main",
  "message": "Remove deprecated configuration"
}

Multipart Multi-File & Directory Upload

Accepts multipart/form-data with form fields branch, message, and one or more file fields preserving relative paths (webkitdirectory).

Issues & Assignees API

Endpoints for issue tracking, discussion comments, and security-scoped collaborator assignees.

List Issues

Query parameters: ?state=open|closed, ?assignee=dev_alice.

Create Issue

{
  "title": "Support distributed snapshotting",
  "content": "We need to support checkpointing WAL files across multiple nodes."
}

Get Issue Details

Update Issue Status & Title

{
  "title": "Support distributed snapshotting (v2)",
  "state": "closed"
}

Get Collaborator Assignees (Security Scoped)

Returns only users eligible for issue assignment: confirmed repository owners and collaborators. External users and platform strangers are strictly excluded.

Assign Issue to Collaborator

{
  "assignee": "dev_alice"
}

Assigning an issue to any user who is not an owner or collaborator returns HTTP 400 Bad Request.

Issue Comments Thread

{
  "content": "Implemented in PR #5. Will verify with integration test."
}

Pull Requests & Review API

Endpoints for opening PRs, inspecting unified diffs, code reviews, and executing merges.

List Pull Requests

Open Pull Request

{
  "title": "Add HTTPS support and ACME integration",
  "content": "Implements automatic TLS certificate provisioning",
  "head": "feature-https",
  "base": "main"
}

Inspect PR Details & Mergeability

Get Pull Request Unified Diff

Submit Code Review

{
  "content": "Architecture looks solid. Verified zero CGO compatibility.",
  "review_state": "approved"
}

Review states: approved, comment, changes_requested.

List & Add Inline Review Comments

{
  "content": "Consider adding a timeout here to avoid socket leaks",
  "path": "internal/https/cert.go",
  "line": 42
}

Execute Native Git Merge

{
  "merge_style": "merge"
}

Supported merge styles: merge (merge commit), squash (squash and merge), rebase (rebase and fast-forward).

Repository Forking API

Endpoints for cloning repositories into user or organization namespaces with upstream tracking.

Fork Repository

{
  "organization": "prodevans"
}

Omit organization to fork into the authenticated user's personal namespace.

List Downstream Forks

Returns an array of all forks spawned from this parent repository.

Wiki & ProGit Pages API

Endpoints for managing Git-backed wiki documentation and static Pages website hosting.

List Wiki Pages

Get Single Wiki Page

Create or Update Wiki Page

{
  "title": "Architecture Overview",
  "content": "# System Architecture\n\nProGit is built in pure Go...",
  "message": "Add architecture overview"
}

Delete Wiki Page

Get Wiki Page Revision History

ProGit Pages Configuration

{
  "branch": "main",
  "folder": "/docs"
}

Configures static hosting. Rendered pages are served at /pages/{owner}/{repo}/.

Webhooks & Deliveries API

Programmatic control for registering webhooks, triggering test events, and reviewing delivery audit logs.

List Repository Webhooks

Returns an array of all webhooks registered on the repository.

Create Webhook

{
  "url": "https://ci.example.com/webhooks/progit",
  "secret": "your_secure_hmac_secret",
  "content_type": "json",
  "events": "push,issues,pull_request",
  "is_active": true
}

Trigger Test Ping Delivery

Dispatches an immediate ping event to verify server connectivity and HMAC validation. Returns the created delivery record.

List Webhook Deliveries

Inspect up to 50 recent webhook delivery attempts, including HTTP status codes, response times, request headers, and response payloads.

Delete Webhook

Danger Zone & Repository Governance API

Endpoints for changing repository visibility, read-only archiving, ownership transfer, and deletion.

Change Repository Visibility

{
  "is_private": true
}

Archive / Unarchive Repository

Set "archive": true to lock repository to read-only; set "archive": false to restore write access.

{
  "archive": true
}

Transfer Repository Ownership

{
  "new_owner": "dev_alice"
}

Atomically moves the Git bare repository directory on disk and reassigns ownership records in SQLite.

Delete Repository

Permanently deletes the repository and removes its bare Git directory from disk.

Developer Messaging API

Endpoints for direct peer messaging, inbox management, and notification counters.

List Active Developers

Returns a list of active developer accounts available for direct messaging.

Send Direct Message

{
  "recipient_username": "dev_bob",
  "subject": "Sprint Targets Discussion",
  "content": "Hi Bob, can we review the webhook signatures today?"
}

Get Inbox Messages

Get Sent Messages (Outbox)

Get Unread Message Count

{
  "unread_count": 3
}

Mark Message as Read

Delete Message

Organizations & Teams API

REST endpoints for organization, team, and member administration.

Create Organization

{
  "name": "prodevans",
  "full_name": "Prodevans Technologies",
  "description": "Cloud native solutions"
}

List Organizations

Get Organization Profile

Organization Members

{
  "username": "dev_alice",
  "role": "admin"
}

Organization Teams

{
  "name": "Backend Engineers",
  "description": "Core backend team",
  "permission": "write"
}

Team Members

List Organization Repositories

Projects & Kanban API

Endpoints for managing project boards, columns, and task cards.

List Repository Projects

Create Project Board

{
  "title": "Release v1.0 Roadmap",
  "description": "Launch milestone tracking"
}

Get Project Board & Columns

Returns board columns, task cards, and progress metrics (`total_cards`, `done_cards`).

Update / Delete Project

Project Columns

{
  "title": "In Review"
}

Task Cards

{
  "column_id": 1,
  "content": "Verify zero CGO builds across Linux and macOS"
}

{
  "column_id": 3,
  "content": "Verified: Alpine, Debian, macOS binaries all run without CGO"
}

System Admin & Maintenance API

Endpoints for Super Admin platform telemetry, user administration, and SQLite database maintenance.

Inspect System Telemetry

{
  "users_count": 14,
  "repos_count": 8,
  "orgs_count": 2,
  "goroutines": 32,
  "go_version": "go1.23.4",
  "mem_alloc_mb": 42.8,
  "db_size_kb": 1280
}

Manage Platform Users

{
  "username": "qa_operator",
  "email": "qa@progit.local",
  "password": "SecurePassword123!",
  "is_admin": true
}

{
  "is_admin": false,
  "is_active": true
}

Global Repository Registry

Database Maintenance (WAL Checkpoint & Vacuum)

{
  "op": "checkpoint_wal"
}

Operations: checkpoint_wal (runs PRAGMA wal_checkpoint(TRUNCATE)), vacuum (runs SQLite VACUUM to reclaim free pages).

Backup & Disaster Recovery

Simple, reliable procedures to backup and restore ProGit data.

Backup Procedure

Because ProGit uses SQLite and local bare Git repositories, backup requires capturing only two directories:

# 1. Trigger SQLite WAL Checkpoint
curl -X POST http://localhost:3000/api/v1/admin/maintenance/wal-checkpoint -H "Authorization: Bearer <token>"

# 2. Archive data directory
tar -czvf progit-backup-$(date +%F).tar.gz /data/db /data/repositories /data/configCopy

Restoring Data

# Extract archive to /data
tar -xzvf progit-backup-2026-11-01.tar.gz -C /Copy

Upgrading ProGit

Safe, zero-downtime upgrades for containers and binary installations.

Container Upgrades

# Pull or build latest image
bash podman/build.sh

# Redeploy container (persistent volumes ensure zero data loss)
bash podman/deploy.shCopy

Binary Upgrades

sudo systemctl stop progit
sudo cp progit.new /usr/local/bin/progit
sudo systemctl start progitCopy

Troubleshooting & FAQ

Answers to common operational questions and error resolutions.

Q: Why do Git pushes over HTTP fail with 401 Unauthorized?

Ensure you authenticate with a valid username and password, or use a Personal Access Token (PAT) created from Settings > Access Tokens.

Q: How do I change the default SSH port from 2222?

Set SSH_PORT = <port> and SSH_LISTEN_PORT = <port> under [server] in app.ini, or pass PROGIT_SSH_PORT=<port> as an environment variable.

Q: How does ProGit Pages resolve file MIME types?

ProGit has a built-in MIME-type registry covering HTML, CSS, JavaScript, SVG, PNG, WebP, JSON, and WebAssembly. It delivers assets with proper Content-Type headers.