Welcome to Radicle — software that enables developers to securely collaborate over a peer-to-peer network built on Git. Check out our homepage if you haven't already seen our comparison between Radicle and alternatives like GitHub or GitLab.
Assuming you're already onboard Radicle's vision of sovereign code infrastructure, let's talk about what we'll cover. With this guide, you'll:
- Create a Radicle identity.
- Migrate your code hosting to Radicle's network.
- Continue pushing changes to Radicle alone, or mirror changes in both Radicle and GitHub.
This guide also works if you're currently using GitLab, Gitea, or any other Git-based code hosting platform.
Radicle doesn't yet have feature parity with GitHub — we're still working on visual code reviews, an issue board, and CI/CD pipelines. Even if the lack of these features is stopping you from migrating in full, we still encourage you to migrate your project to Radicle and mirror your changes so that you can quickly make the switch when the time is right!
Install the Radicle CLI
To migrate from GitHub to Radicle, you first need to install the Radicle CLI and create a Radicle identity, which is like creating an account on GitHub. It's how your projects are identified on the Radicle network, and it's your key to hosting code and collaborating with others on your project.
Once you're done with the first two steps — Install the Radicle
rad CLI. and Run
rad auth to create your
Radicle identity. — you can return here for the rest of the instructions.
Initialize your project on Radicle
Radicle wraps around the
git binary and processes you already use to manage your project's data and history. This
wrapper lets you push your code to the sovereign Radicle network and collaborate with others.
Because you already have a project you've pushed to GitHub, you already initialized the Git repository with
which created the
.git directory to store objects, heads, refs, and more.
Initializing a project on Radicle is as simple as setting up Git for the first time:
Add a description and choose your default branch, which is typically either
rad init does two things:
- Creates a unique peer-to-peer identity — a project URN — for your project.
- Adds a new
remoteto your project's existing configuration using that new identity, for pushing code to a unique address on the Radicle network.
You'll also see a line similar to
ok Project initialized: rad:git:hnrkqi6ohci9m59i54ppiy3fqkedkjt98ymdo. The text
rad:git: is your project's URN.
You can always find your project's URN by running
rad . from the project's directory.
Push to the Radicle network
You can push to the network now that you've initialized your project on Radicle.
Since this is your first push to Radicle, the CLI asks which seed node you want to sync with. Radicle provides three
seed nodes with identical functionality —
Choose any that you like!
You can also sync to multiple Radicle-hosted seed nodes, or host your own seed
node, if you'd like additional resiliency or security.
push syncs with your default seed node, which you can find with
git config --local rad.seed, but you'll need to run
rad push --seed <your-seed-node-url> for each additional seed node you want to sync with.
rad pushes your project to the Radicle network, it outputs details on where you can find your project on the
Radicle web app.
🌱 Your project is synced and available at:
Push to both Radicle and GitHub simultaneously (mirror)
If you're not ready to migrate away from GitHub completely, you can mirror your project in both places.
git add .
git commit -m "Your commit message here"
If you don't like running two commands, you could also create an alias in Zsh or Bash to automate the process. Edit your
~/.bash_profile file and add the following line, which first pushes to your existing remote on GitHub
and Radicle in sequence when you run
alias gp="rad push && git push"
Code collaboration on Radicle (issues and patches/PRs)
Certain features, like visual code reviews and issue discussion boards, aren't yet live on Radicle.
We're prioritizing must-have features like issues and patches, with more information coming soon.
For now, the best way to collaborate is to have each contributor clone the project, push changes to their remotes, and have a single maintainer responsible for tracking, reviewing, and merging changes to keep the project and contributors in sync.
You can also create, view, and comment on issues using the CLI.
If you're having trouble with any part of the migration process, check out our troubleshooting guide, or head over to the #support channel on Discord, where a member of the Radicle team will help you out.
The next best thing you can do is share your project with collaborators so they can clone it and push their changes, completing your migration away from not just GitHub, but all centralized, online-first, and censorship-prone code hosting platforms.
Now that you're on the Radicle network, hop into our Discord server, where our core team and collaborators actively chat about the future of sovereign code infrastructure, what we're working on next, and ways to get involved.