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, administrator-created accounts with disable/re-enable and password reset, failed sign-in throttling, bearer sessions and membership-scoped organizations with API and browser membership administration, 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. Create the rest of the team
under Accounts (/admin/accounts): an administrator supplies each account's
initial password, can disable and re-enable accounts, and can reset passwords.
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.
A direct installation uses one command, githearth-server setup, which writes
the configuration and generates the host key before migrating and creating the
first administrator (install.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 |
| Two-person delivery roadmap | Phase ownership, increments and acceptance cases, including M4.1–M11a |
| Milestone direction decisions | Build order and the direction chosen for each milestone's main decisions |
| 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 |
| Accounts | Creating, disabling and re-enabling accounts; password change and reset; failed sign-in bounds |
| 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 |
| Push and lifecycle decision | Push acknowledgement boundary, journal, lifecycle and 410 after rename, transfer or delete |
| Merge execution decision | A/B merge contract: intents, methods, expected-ref execution, recovery |
| SSH transport decision | SSH admission, key handling and the shared push pipeline |
| Durable jobs decision | Jobs, leases, retry budgets and the M4.1 outbox relay |
| Signed commits decision | Signed-commit policy and stale-approval dismissal |
| Forks decision | Fork contributions, storage and pull-request policy |
| Drafts decision | Draft pull requests and their effect on merge eligibility |
| Git replication decision | M5 commit point, object manifests, replicated lifecycle and member rules |
| PostgreSQL HA decision | Patroni topology, exact synchronous settings, fencing and the application contract |
| Placement and reads decision | Placement, per-endpoint reads, the move protocol and expansion |
| Platform slice decision | M4.2 object storage, tokens, secrets, encrypted backups and fairness |
| Identity slice decision | M11a OIDC, second factors, sign-up, recovery and deletion |
| 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