113 lines
4.5 KiB
Markdown
113 lines
4.5 KiB
Markdown
---
|
|
title: Automatically Mirror Sr.ht To GitHub
|
|
date: 2025-05-15
|
|
description: Brief tutorial on setting up automatic mirroring from sr.ht to github.
|
|
---
|
|
|
|
For a variety of reasons, I've recently migrated to [sr.ht](https://sr.ht/~ficd)
|
|
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](https://yazi-rs.github.io/)'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:
|
|
|
|
```bash
|
|
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](https://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!
|
|
|
|
```yaml
|
|
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](https://sr.ht/~ficd/ashen/) and
|
|
is mirrored on [GitHub](https://github.com/ficcdaf/ashen). To report issues or
|
|
make requests, visit the [ticket tracker](https://todo.sr.ht/~ficd/ashen) or
|
|
contact the [mailing list](https://lists.sr.ht/~ficd/ashen) (_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!
|