---
title: Automatically Mirror Sr.ht To GitHub
date: 2025-05-15
---

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:

![](/static/images/gh_about.png)

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!