Maiao: Bringing Gerrit-Style Code Review Workflow to GitHub

Migrating Workflow from Gerrit to Mainstream Platforms

Code review is an indispensable part of modern software engineering. Among the many review tools, Gerrit has long been favored by large engineering teams like Google for its unique "one commit per review" philosophy. Born in 2008, Gerrit was originally developed by Google for the Android Open Source Project (AOSP). Written in Java, it uses JGit (a Java implementation of Git) under the hood and manages review state through custom Git reference namespaces (refs/for/* and refs/changes/*)—essentially, it's a Git server with review logic built in, rather than just a web interface layer. However, this very architectural design makes Gerrit deployment complex and its ecosystem relatively closed, requiring an independent Java application server and dedicated database, which deters many teams accustomed to platforms like GitHub and GitLab.

The recently discussed open-source project Maiao on Hacker News is attempting to fill this gap. It seamlessly migrates Gerrit-style code review workflows to mainstream hosting platforms like GitHub, GitLab, and Gitea, allowing developers to enjoy Gerrit's core advantages without switching platforms.

Core Value of Gerrit Workflow

To understand Maiao's significance, we first need to grasp the fundamental difference between Gerrit and the traditional Pull Request (PR) model.

Commit-Centric vs Branch-Centric

The traditional GitHub PR model is branch-centric: developers accumulate multiple commits on a feature branch and ultimately submit them as a whole for review. The Pull Request model, first introduced and popularized by GitHub in 2008, builds code review on top of Git branches. Its core advantage lies in its low barrier to entry—any developer who understands Git branching can quickly get started. This approach works well for smaller features, but when a PR contains multiple logically independent changes, reviewers often struggle to evaluate them individually, leading to "big PR syndrome"—piled-up comments and declining review quality. Microsoft research shows that PR review quality significantly drops beyond 200 lines of changes; Google's engineering practice data indicates that changes under 100 lines have markedly better review pass rates and defect detection rates than larger changes, providing data evidence for "big PR syndrome."

Gerrit adopts a commit-centric model: each commit corresponds to an independent review unit (Change). Changes are broken down into atomic logical units, each reviewed and merged separately. This level of granular control makes code reviews more focused and iterations clearer. Gerrit implements change tracking through the Change-Id mechanism—each commit message embeds a unique Change-Id identifier. When developers amend a commit and push again, Gerrit automatically recognizes it as a new version (patchset) of the same Change, rather than an entirely new change. This design provides clear version history for multiple iterations of the same logical change.

Stacked Changes

Gerrit natively supports "stacked changes," where a series of interdependent commits can be reviewed in parallel without waiting for the previous one to be fully merged. This is especially important for large refactorings or phased feature implementations.

Stacked changes solve an extremely common development scenario: developers need to continue building subsequent features based on a change while waiting for the first change to be reviewed and approved. In the traditional PR model, this requires creating a new branch based on an unmerged branch, forming a PR chain—when the first PR is modified, all subsequent PRs need manual rebasing, which is error-prone and cumbersome to manage. Gerrit's Change-Id and automatic dependency relationship maintenance allow stacked changes to iterate and be reviewed independently. Notably, similar tools like Graphite, ghstack (open-sourced by Facebook), and git-branchless have recently attempted to implement similar functionality in the GitHub ecosystem, demonstrating the widespread need for stacked changes. In comparison, Maiao's differentiation lies in its cross-platform unified solution rather than being limited to a single platform.

Maiao's Core Features and Design Philosophy

Maiao's core approach is: reproduce Gerrit's workflow logic on the client side while keeping the underlying hosting service as GitHub, GitLab, or Gitea. Developers still use familiar platforms for discussions and merging, but organize changes following Gerrit's philosophy.

Cross-Platform Compatibility: GitHub, GitLab, Gitea Fully Covered

Interestingly, Maiao supports multiple platforms. The project explicitly lists target platforms including GitHub, GitLab, and Gitea. Teams can adopt a unified review workflow regardless of which hosting service they use.

For teams that self-host Gitea instances for compliance or cost reasons, this is an especially friendly feature. Gitea is a lightweight Git hosting solution written in Go, known for extremely low resource consumption—a single-core CPU server with 512MB memory can run it smoothly. In recent years, driven by data sovereignty, compliance requirements (like GDPR, Dengbao), and concerns about third-party platform pricing changes, more and more enterprises are choosing self-hosted code hosting services. Gitea also spawned the Forgejo project in 2022 (maintained by the Codeberg community), further enriching the self-hosting ecosystem. Maiao's support for Gitea means that even teams choosing fully autonomous and controllable infrastructure can enjoy advanced code review workflows.

Zero Infrastructure Deployment, Reducing Migration Costs

In the past, to experience Gerrit workflow, teams had to either deploy a complete Gerrit server (meaning independent Java runtime environment, database configuration, SSH key management, and integration with CI/CD systems) or rely on Google's Gerrit hosting. Maiao reduces this barrier to nearly zero—no additional server infrastructure is needed; just introducing the tool on top of existing platforms is sufficient. This "client-first" design philosophy significantly reduces teams' migration costs and operational burden.

Which Teams Are Suited for Maiao

Maiao currently has 23 upvotes and a few comments on Hacker News, with discussion heat still in early stages, but it touches on a real pain point.

The following types of teams should pay particular attention:

• Engineering teams that value commit granularity: If your team pursues atomic commits and high-quality code history, Maiao's philosophy will be highly compatible. Atomic Commits require each Git commit to contain only one logically complete change and keep the codebase in a buildable, testable state. This practice's value manifests in multiple dimensions: during debugging, git bisect can precisely locate the specific change that introduced the problem; during code rollback, you can accurately revert a single feature without affecting other changes; clear commit history itself serves as documentation, helping newcomers understand the code's evolution. The Linux kernel community exemplifies atomic commit practice—Linus Torvalds and kernel maintainers require each patch to be self-contained and independently reviewable.
• Teams migrating from Gerrit: Many engineers who used Gerrit miss that fine-grained review experience when moving to GitHub; Maiao provides a middle ground.
• Projects needing to handle complex dependent changes: Stacked changes offer clear advantages for large refactorings, kernel-level development, and similar scenarios.

Limitations to Consider Before Using Maiao

Gerrit-style workflow is not a panacea. Its learning curve is relatively steep; teams need to shift from "branch"-based thinking habits and master relatively advanced Git operations like interactive rebase and commit amend. For small projects or teams accustomed to lightweight PR processes, introducing this workflow might actually increase cognitive burden.

Additionally, as a relatively nascent open-source tool, Maiao's maturity, community activity, and stability of compatibility with various platform APIs still need validation through actual use. Whether the tool can truly be "seamless" often depends on how well edge cases are handled—for example, when platform APIs change, when merge conflicts appear in the middle of a stacked change chain, or when team members mix Maiao with traditional PR workflows, how does the tool perform? These are practical issues that need attention.

Conclusion

Maiao represents a commendable direction of exploration: rather than forcing teams to switch platforms, it layers better workflows on top of existing ecosystems through tooling. In the high-frequency and critical aspect of code review, such "incremental improvement" is often more easily accepted than "starting from scratch."

For developers long torn between GitHub's PR model and Gerrit's fine-grained review, Maiao offers a third option worth trying. As the project matures, it may prompt more teams to rethink: what kind of code review workflow do we really need?

Key Takeaways