Radicle: peer-to-peer collaboration with Git

Radicle is a new, peer-to-peer, MIT/Apache-licensed collaboration platform written in Rust and built on top of Git. It adds support for issues and pull requests (which Radicle calls "patches") on top of core Git, which are stored in the Git repository itself. Unlike GitHub, GitLab, and similar forges, Radicle is distributed; it doesn't rely on having everyone use the same server. Instead, Radicle instances form a network that synchronizes changes between nodes.

As a new project, Radicle is not fully featured compared to the mature and centralized forges. That said, the Radicle developers are using Radicle itself to collaborate on the software, along with a Zulip chat system. The first 1.0.0 release candidate was announced on March 26.

(Note that I am paid to help develop Radicle.)

Overview

In Radicle, each user runs their own node on each computer they use for collaboration. The node stores copies of the repositories the user is interested in, regardless of whether they're created by the user or cloned from another node. The node process runs in the background to fetch changes from peers and serve repositories to peers that want them. To the user, the node acts like a local Git server. You clone from, pull from, or push to the node and it coordinates with other nodes.

There is a web interface for browsing repositories, issues, and patches, and it also allows opening and managing issues. The web interface can be opened for the local node, or on a suitably configured server, for any other node. Thus you can inspect any public node to see if it is in sync with yours.

The web interface looks a lot like the more mainstream forges, and is meant to feel instantly familiar. You can browse the code, issues, and existing patches. However, unless you run your own Radicle node and open its web interface, you can't currently make changes: you can't report issues, comment on issues, etc.

If you want to clone a repository locally, the web interface provides two ways: either using normal Git (git clone) and an HTTPS URL, just like other forges, or having your Radicle node fetch it and clone from that using the rad command-line tool. You don't need to use Radicle to get a copy of a repository from Radicle.

Creating issues and patches — and commenting on them — happens using your own Radicle node. There is a command-line interface, and a web user interface. The Radicle project is also working on a full-screen terminal user interface, like Midnight Commander but for Git, and there is integration with Visual Studio Code and IntelliJ IDEs, among others.

Motivation

The motivation for Radicle is similar to that of the overall decentralization movement. The centralized Git forges are popular for good reasons: they've put in a lot of effort into being easy to use and efficient, and to provide the kinds of features their users need. However, they are also not always great for everyone. There is some truth in the joke that when GitHub is down, the world stops developing software. Git was the first popular distributed version control system. Then, the popularity of GitHub made it the most centralized version control system.

With a peer-to-peer system, if your node is down, you may have to stop working, but nobody else needs to. More importantly, you don't need permission to run a Radicle node. Your access can't be revoked. Your repositories can't be deleted from your node by others. Nobody will force you to accept an "updated" set of terms and conditions.

Radicle stores issues and patches in the Git repository itself. You can create, comment, and manage them while offline. Radicle is local-first software: network access is only required for operations that inherently require communicating with other computers, such as retrieving or sending changes. Everything else works without the network.

Radicle repositories are self-signing, a necessary feature in a distributed system. While a GitHub repository can be authenticated by location (it's on GitHub with a given name), a Radicle repository is associated with a small set of cryptographic signing keys, which allows its identity and contents to be authenticated regardless of where the repository is stored.

Radicle's origin traces back to 2017. Its development is funded by Radworks, an organization that coordinates on the Ethereum blockchain using a token called RAD. However, Radicle does not use any blockchain or cryptocurrency technology. Radicle is not the only approach to decentralized collaboration over Git. ForgeFed is a protocol built on ActivityPub to support a federated network of Git servers.

Architecture

Nodes communicate with each other using two different protocols. First, there is a gossip protocol, where nodes tell each other about the nodes and repositories they know about, and about changes to the repositories. Second, they use the Git v2 smart transfer protocol to exchange repository content.

Each node stores copies of the repository as it exists on each other node it knows about, using the Git namespace feature and the node identifier as a name. Each node has nearly identical content, so this is an efficient way to store the data. To Git, a Radicle repository is a perfectly normal repository. Radicle uses standard Git mechanisms to add a persistent repository identity, issues, and patches. These are stored in special Git refs.

Every repository stored in Radicle has an identity that is the same in every Radicle node where the repository appears. If there are multiple copies of a repository stored in a node, each copy has the same identity, and can thus be identified as a version of the same repository. This identity is created by committing an "identity document" that contains metadata about the repository; an example identity document is:

    {
      "payload": {
        "xyz.radicle.project": {
          "defaultBranch": "master",
          "description": "Radicle Heartwood Protocol & Stack",
          "name": "heartwood"
        }
      },
      "delegates": [
        "did:key:z6MksFqXN3Yhqk8pTJdUGLwATkRfQvwZXPqR2qMEhbS9wzpT",
        "did:key:z6MktaNvN1KVFMkSRAiN4qK5yvX1zuEEaseeX5sffhzPZRZW",
        "did:key:z6MkireRatUThvd3qzfKht1S44wpm4FEWSSa4PRMTSQZ3voM"
      ],
      "threshold": 1
    }

The document includes a description of the repository and its default branch. The delegates list contains the public Ed25519 keys of the delegate(s) that are empowered to change the identity document or commit to the main branch. This document is stored behind the rad/id ref in the repository. It must be signed by one of the delegate's private keys. Each repository has a short ID that is calculated from a hash of the initial version of the identity document. This ID will not change as the identity document is modified, and can thus be used to identify the repository over time.

There is no way to prevent anyone from changing the identity document on their own node and signing it with their own key, bypassing Radicle. However, other nodes won't accept the change, since it is not signed by a delegate's key, making such changes pointless. Radicle also signs the branch and tag refs. The signatures are refreshed whenever a node changes anything in the repository. This means that other nodes can verify another node's repository content without inspecting the other node directly. This helps prevent forgeries and related attacks.

Issues and patches are stored using an implementation of a conflict-free replicated data type, which Radicle calls a "collaborative object", or COB. Any node can append data to a COB, and changes from different nodes can be merged without conflict. (Normal git conflict management applies to the rest of the content of the repositories, however: the user needs to resolve them.) The COB mechanism in Radicle is generic, and can be used to build further collaboration tools.

Seed nodes

Any node can synchronize data with any other node, but only if they can communicate directly. With network address translation (NAT) being prevalent, this is often not possible. Radicle does not yet have "NAT punching", but relies on third-party, publicly accessible seed nodes. This is safe thanks to the repositories being self-signed: the seed node can't modify the data.

Thus, if Alice and Bob are both behind NAT networks, they can collaborate via a seed node on the Internet that they both can access. Unlike with centralized forges, anyone can set up a seed node. This works especially well for open-source projects that don't need to keep repositories hidden. If hiding is necessary, a private seed node and Radicle private repositories can be used. A private repository is one that's configured to only be shared with specific other nodes. However, Radicle is not yet a good solution for truly confidential material: the private nodes are still rather rudimentary.

Missing features and other challenges

Radicle does not yet have mature support for continuous-integration systems, although work on that is underway. There is also only rudimentary support for code review, but that is also being worked on.

Currently, Radicle has a simple identity system: each node has its own public key. A challenge for the future is to evolve this into a more versatile identity system. For example, a developer with both a laptop and a desktop system would benefit from being able to certify that both nodes are theirs. Support for groups or organizations is also missing.

Perhaps a more fundamental challenge is that interacting with a Radicle repository, even just to report issues, requires using Radicle. With a centralized forge, all you need is an account and a web browser. This may be a problem for projects that would like to use Radicle, but whose users can't be expected to use it.

Conclusion

Radicle is a new and promising decentralized approach to Git hosting. If you are curious to know more, the guides are a good place to start. We're also accepting patches and hoping to bring in new contributors, so if you know some Rust and care about developer tooling, please join us on our Zulip forum.