orbi

English | 简体中文

Orbi

GitHub Issues in, tagged releases out.

Orbi claims an Issue from GitHub Issues, develops it in an isolated worktree, runs an independent review session, merges only the reviewed head, and lets a release Issue freeze the SHA and publish the tag. GitHub Issues are the only state store—no database, queue, or daemon.

Ledger: 414 merged PRs · 537 closed Issues · 36 tagged releases

Inspect one loop: Issue #835 → PR #843 → Release v0.5.4

Website ｜ Documentation ｜ Discussions ｜ Docker GHCR · Docker Hub

Quick start

git clone https://github.com/orbi-build/orbi.git && cd orbi
uv tool install --force --reinstall --editable --python python3 .  # compatible system Python (>= 3.14, e.g. Fedora 43 / current Arch); older system Python (e.g. Ubuntu 24.04 ships 3.12): --python 3.14 so uv provisions it

Want just the CLI? Published on PyPI as orbi-cli (requires Python ≥ 3.14; the installed command stays orbi): uv tool install orbi-cli (on an older system Python, e.g. Ubuntu 24.04's 3.12, add --python 3.14 so uv provisions a compatible interpreter) or pip install orbi-cli inside an activated Python ≥ 3.14 environment; verify with orbi --version → orbi , uninstall with uv tool uninstall orbi-cli. To run Orbi itself, use the one-line installer at the top of Getting started — it creates the editable install Orbi's deployment drives.

Ready check (before setup)

• uv: uv --version; Pi and its provider: pi --version, then pi --print "reply with the single word: ok"
• GitHub CLI ≥ 2.94 (official repository — Ubuntu 24.04's package 2.45.0 is too old): run gh auth login once, then verify gh auth status
• Linux — systemd user session: systemctl --user status
• macOS — launchd GUI session: launchctl print gui/$(id -u) (not yet verified on real hardware; reports welcome)

Choose the mode in Getting started: bootstrap uses this checkout as repo_dir; External single-repo mode uses it as deploy_home and a foreign repository as repo_dir.

cp src/orbi/example_config.toml orbi.toml
orbi setup --config orbi.toml  # 4. run one-time setup (checks prior gh auth, labels, scheduler units (systemd/launchd), and checkout; idempotent)
PYTHONPATH=src python3 -m orbi.runner --config orbi.toml  # 5. manually run one tick (for initial verification; the timer schedules normal runs)
orbi doctor --config orbi.toml  # 6. verify deployment health

Why Orbi

• GitHub Issues are the task pool: the ai-ready label dispatches work, and the delivery record (comments, PRs, and CI) is complete by default, with no second task system;
• Fully automated: a user scheduler timer (systemd on Linux, launchd on macOS) triggers a tick every 5 minutes. Normal operation needs no status command, polling, or supervision;
• Independent review + merge gates: after a PR opens, an independent review session reviews it and fixes findings in the same session. Only the reviewed head can merge, and AI never merges or pushes protected branches;
• Fail fast: command errors fail immediately and leave the evidence in the logs. The Issue is marked ai-blocked for a human decision, with no silent fallback;
• Observable end to end: every journal log and GitHub progress comment carries the same run_id, so the complete timeline can be reconstructed with one grep.

What it does

GitHub Issue (ai-ready)
  → Claim: create a feature branch + isolated worktree (from the frozen origin/main SHA)
  → Pi development: plan → implement → test → verify
  → Commit delivery (the Agent stops at the commit)
  → Runner closeout: sync the latest base, push, and create a PR (body includes Fixes #N)
  → Independent review (fixes in the same session) → merge gate → merge

• Each task gets its own run: the branch, worktree, logs, and PR are all associated with the same run_id; retries create a new run and preserve the old evidence unchanged;
• Failures are classified clearly: recoverable failures return to the same PR for continued fixes, while unrecoverable failures mark the Issue ai-blocked for a human;
• Supports orbi add for dispatching work, status for viewing the queue, session for following the Pi session, install-units for idempotently installing the scheduler units (systemd on Linux, launchd on macOS), and doctor for read-only diagnostics.

Documentation

Development and contribution

See the development contract in AGENTS.md, and Contributing for dispatching Issues, reporting bugs, and submitting PRs. Runtime code lives in the src/orbi/ package (Issue #168 src layout; the editable finder maps the entire package directory, so new modules need no reinstall). The checkout root has no orbi.py (to avoid shadowing the installed package); the direct-execution compatibility entry point is python3 -m orbi.cli, not the formal usage path.

License

This project is fair-code, released under the Sustainable Use License (v1.0). See the complete text in LICENSE.md at the repository root.

In practice:

• Run Orbi on your own repositories for free forever—for personal use and internal company use alike, at any scale. You can modify the code, self-host it, and run it across a thousand repositories without requesting authorization.
• You may share it, provided that it is free and used for non-commercial purposes.
• Commercial authorization is required only when you sell Orbi itself—for example, hosting it as a service for customers or embedding it in a paid product.

If you are unsure which side your use falls on, ask in Discussions; we will give you a clear answer.