A home for your code.
GitHearth is a planned source-available development platform for repositories, code review, project planning, CI/CD, packages, security, and collaboration. The long-term goal is broad GitHub/GitLab-style capability with customer control over hosting and data.
Current status: verified experimental single-node application. The repository contains a Rust server with PostgreSQL migrations, administrator bootstrap, bearer sessions and membership-scoped organizations, Git hosting over Smart HTTP and SSH, repository browsing, issues and pull requests (threaded inline reviews, suggestions, drafts, reviewers and code owners, commit checks, branch and tag protection, signed-commit policy, merge methods, conflict handling, merge queue and auto-merge), forks, notifications, a server-rendered UI, and installation, backup/restore, upgrade and uninstall runbooks with executable drills. Replication, CI integration, packages, security scanning and production hardening remain planned. The repository remains private during initial development.
- One product supports both a single-machine installation and a distributed deployment.
- The same APIs, permission rules, identifiers, and durable formats apply in both modes.
- Rust is the primary implementation language; performance claims require measurements.
- Users can self-host, export their data, and use standard Git clients.
- GitHearth is licensed under the Business Source License 1.1; see Licensing.
- Completed features are intended to be available without feature tiers: one commercial license covers the whole product.
GitHearth is source-available under the Business Source License 1.1. It is not open source.
- Free: reading, copying and modifying the code, and any non-production use such as development, testing and evaluation.
- Needs a commercial license: production use. Contact the maintainers to arrange one.
- Later: each version becomes available under the Apache License 2.0 four years after it is published.
Contributions are covered by CONTRIBUTING.md. To report a vulnerability, see SECURITY.md.
Requirements: Docker Engine with Compose, Python 3, and a terminal. Ports 8080,
2222 and 54329 must be free. Run these from the repository root. The database and
repository storage are persistent Docker volumes, and the generated .env is a
secret (it is git-ignored).
# 1. Generate a unique local database password
umask 077
python3 - <<'PY'
import pathlib, secrets
with pathlib.Path('.env').open('x') as f:
f.write('POSTGRES_PASSWORD=' + secrets.token_hex(32) + '\n')
PY
# 2. Build and start PostgreSQL, migrate, generate the SSH host key, then the app
docker compose up --build --wait
# 3. Confirm the server is ready
curl --fail http://127.0.0.1:8080/health/ready
# 4. Create the first administrator (password on stdin, 12+ bytes; runs once)
read -r -s -p 'New administrator password (12+ bytes): ' ADMIN_PASSWORD; echo
printf '%s' "$ADMIN_PASSWORD" | docker compose exec -T app githearth-server bootstrap-admin --username admin
unset ADMIN_PASSWORDOpen http://127.0.0.1:8080/ and sign in as admin. Git clients use
http://127.0.0.1:8080/<org>/<repo>.git or ssh://127.0.0.1:2222/<org>/<repo>.git.
Stop while keeping data with docker compose down. docker compose down --volumes
permanently deletes this installation's database. Plain HTTP is for loopback
development only; terminate TLS at a trusted proxy before any nonlocal use
(see tls.md).
For the direct-binary path, the full configuration reference, the API exercise
and the real-PostgreSQL test procedure, see foundation.md.
For a production installation, the preflight doctor check and upgrades, see
install.md, upgrade.md
and uninstall.md.
Start with the master plan.
| Document | Purpose |
|---|---|
| Master plan | Vision, constraints, deployment promise, scope, and design priorities |
| Full forge roadmap | Milestones M0–M14, dependencies and completion gates through the complete baseline |
| First milestone | M1 scope, acceptance criteria and M2 task breakdown |
| Capability inventory | Required feature families and their acceptance obligations |
| Qualification and decisions | Capacity, faults, deployment profiles, pending choices and release evidence |
| M1 verification | Reviewer evidence, criterion outcomes and limits |
| Foundation runbook | Start the server, migrate, bootstrap, exercise API and run real PostgreSQL tests |
| Metadata contract | Data ownership, transactions, workload definitions, and account-scale profiles |
| Decision gates | Agreed requirements, unresolved decisions, and the implementation sequence |
| Deployment contract | Single-node/cluster behavior, failure semantics, expansion, and merge requirements |
| Backup and restore | Concrete backup/restore procedure and storage verification |
| Database experiment | Reproducible lab setup, workload runner, and result interpretation |
| Database decision | Provisional PostgreSQL selection, measured evidence, and remaining qualification gates |
| Authorization decision | Cedar policy-based authorization: roles, built-in forbids, failing closed |
| Merge execution decision | A/B merge contract: intents, methods, expected-ref execution, recovery (proposed for M3) |
| Local results | 84 measured runs, errors, resource observations, and process recovery |
| Git prototype | Working local commands, tests, and current limitations |
The full product scope now has a milestone roadmap and capability inventory; detailed subsystem ADRs are resolved before their implementation gates. These documents do not claim feature parity, production capacity, or distributed correctness.
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings