Automatically Mirroring Sr.ht To GitHub
For a variety of reasons, I’ve recently migrated to sr.ht for Git and project hosting. I prefer the minimal, no-frills interface, and I really like that you can have multiple repositories, mailing lists, and issue trackers grouped under the same project. The email-centric workflow is also appealing to me.
However, the fact remains that a strong presence on GitHub is very important. If you’re a student hoping to land a programming job, you need to keep those commit stats up. Many tools, such as Yazi’s package manager, only support GitHub repositories. However, I don’t like GitHub, that’s the whole reason I switched!
I finally decided to give automatically mirroring my repositories a shot. While it was a bit of work to set up, it’s worth it in the end. In this post, I’ll guide you through the process.
SSH and Sourcehut Secrets
The first step is to give builds.sr.ht push access to your GitHub repositories
via ssh. Begin by generating an ssh key pair:
ssh-keygen -t ed25519 -f ~/.ssh/gh_mirror_id -N ""
You’ll want to add the public key to your GitHub account. Navigate to
Settings → SSH and GPG keys, click the big green button, and paste the
contents of gh_mirror_id.pub. Make sure its key type is “Authentication Key”,
and give it a helpful name like sr.ht builds.
Next, you need to upload the private key to Sourcehut. Visit
builds.sr.ht/secrets, name it something
memorable, and paste gh_mirror_id into the big box labeled “Secret”. Take care
to tick the Secret Type → SSH Key menu option before hitting the blue
“Add” button.
Keep this page open, because you’ll need the secret’s UUID later.
Build Manifest
The basic idea is as follows: whenever you push to your chosen sr.ht
repositories, it should automatically be pushed to GitHub with the --mirror
flag. Sourcehut has an automated build system that’s up for the task. (Note:
you need a paid account to use it.)
For any repository you want to mirror, you’ll need to add a file called
.build.yml to the root. This file will look familiar if you’ve worked with
GitHub actions before. Then, you set up the environment, import the ssh key
from earlier, and add a task for pushing the repository as if you were doing it
from the command line. Finally, make sure you’ve created an empty GitHub
repository ahead of time — otherwise, the build will fail!
image: alpine/latest
packages:
- git
- openssh
secrets:
- SECRET_UUID_HERE
environment:
# in case the repos have different names
srht_repo: repo-name-on-srht
github_repo: repo-name-on-gh
github: git@github.com:yourusername
tasks:
# ssh-keyscan is required, command fails otherwise!
- mirror: |
ssh-keyscan github.com >> ~/.ssh/known_hosts
cd "$srht_repo"
git remote add github "$github/$github_repo.git"
git push --mirror github
And that’s it! Anytime you push to a branch that has this build manifest in it, your GitHub mirror is updated.
Readme Wrangling
Since all you’re doing is mirroring, you can’t have a different readme on
GitHub. There’s a few things I recommend doing so folks viewing your repository
on GitHub don’t get confused. You can mention the mirror in the “About” section,
and include a link to your sr.ht repo:
I also recommend prominently displaying links to your bug tracker and mailing
list, if applicable to your project. Finally, make sure there’s an early link to
the sr.ht project page. You could also explicitly mention that the project
lives on sourcehut and is mirrored on GitHub, but this may be overkill. Consider
this example from my Ashen project README:
ex_start
This monorepository contains official implementations of Ashen across a range of editors, terminals, tools, and more — each carefully tuned to carry the same muted warmth. The project lives on sourcehut and is mirrored on GitHub. To report issues or make requests, visit the ticket tracker or contact the mailing list (possibly by carrier pigeon.)
ex_end
Happy Hacking!
Now, you should be able to comfortably use sr.ht to host your projects without
sacrificing the ubiquity of GitHub. Happy hacking!