Runko

Runko is an innovative self-hosted monorepo platform designed to streamline software development using plain Git. It enables first-class project management within a single repository while implementing change-based review processes similar to Gerrit, along with features like path ownership, affected-based CI scoping, and server-enforced merge gates. Both human developers and automated coding agents interact seamlessly with a unified CLI/API interface, providing a versatile experience for all users.

Key Features:

• Monorepo Management: Easily manage multiple projects within a single repository.
• Change-based Reviews: Utilize Gerrit-style refs/for/ pushes for effective code review.
• Path Ownership: Define ownership of specific paths for better project governance.
• CI Scoping: Target CI checks specifically based on the changes made.
• Rebase-based Merging: Implement rebase-based landings with strict server-side policies.

Runko operates on a public instance, allowing users to browse code, track changes, and view review history without needing an account. Users are encouraged to explore the code and its changes via the following links:

• Code Repository
• Change History
• Interactive Playground

Clone the repository with:

git clone https://runko.victornazzaro.com/o/runko/repo.git

Architecture and Design:

Runko's architecture relies solely on Git as its core storage medium, while Postgres provides a rebuildable index of the trunk without creating additional sources of truth. The complete design details can be found in the design document.

Change Management Process:

In Runko, direct pushes to main and merged pull requests are prohibited. Instead, changes are pushed to refs/for/main, undergoing a series of checks based on the relevant PROJECT.yaml manifests which specify the required CI checks. These checks are executed by a generic CI executor, ensuring that only vetted changes progress through the codebase.

Current Status:

Runko is fully operational and utilized in its development processes, serving as a practical testbed for its features. Comprehensive documentation regarding its implementation and engineering history is available in docs/implementation-log.md.

Project Structure:

The repository contains several key directories:

docs/design.md      # Full design specifications
docs/spec/          # Schema artifacts
db/                 # Database migrations and queries
internal/           # Shared internal components
platform/           # Control-plane libraries
runkod/             # Daemon processes for handling requests
web/                # Web UI built with React and TypeScript
cli/runko/          # CLI for human/agent interaction

CLI Usage:

Runko provides a consistent command-line interface, where every action is executed through commands. A daily usage example includes:

runko project create --name payments-api --type service --lang go
runko workspace create --name fix-sku --project payments-api --by you
runko change push
runko change land

Building and Testing:

To build and test Runko, follow these commands:

git clone https://runko.victornazzaro.com/o/runko/repo.git runko
cd runko
make check  # Run formatting, vetting, and testing

Contributions and community discussions are welcome; however, pull requests will be reviewed on the Runko platform, since this repository serves merely as a read-only mirror.