Mirroring Sourcehut to GitHub

This post is older than a year. Information may be outdated.

Published: [ 2024-02-03 23:45 EST ]
Categories: [ programming ]
Tags: [ github, vcs ]

So I (mostly) stopped using GitHub a while back. Unfortunately for me, my CMS Grav requires plugins to be hosted on GitHub. As my KaTeX plugin is developed on Sourcehut, this makes publishing the plugin a little difficult. However, I have come up with an ingenious solution—mirror the Sourcehut repository to GitHub.

It's really easier than it sounds!

Mirroring the Actual Repository Contents

There is no built-in function in GitHub to mirror a repository (unlike in Forgejo), but a Sourcehut build action ought to do that instead!

First, I had to create a secret to allow Sourcehut to push to GitHub. I am avoiding using SSH keys because SSH keys have access to all of your repositories on GitHub instead of the ones Sourcehut needs access to.

The mirroring process is fairly simple! I first created an empty repository on GitHub with the same name as the repository on Sourcehut. Creating an empty repository is very important! Ensure "Add a README file", "Add .gitignore", and "Choose a license" are all unmarked!

To give Sourcehut push access to this repository, I added a fine-grained access key on GitHub's secrets page, set the expiry date to a year in the future, allowed it access to only my plugin repository, and gave it only the "Read access to metadata" and "Read and Write access to code" permissions.

Then, I added the access token to Sourcehut's secret system in the following format for the file at ~/.git-credentials with permissions 600:

https://GITHUB_USERNAME:github_pat_SECRET@github.com

Make a note of the UUID generated!

Then, in the repository, I created the Sourcehut build file .build.yml:

image: alpine/edge
secrets:
  - 4df836f8-5313-40b1-bc4e-b7b20cfd147e # Set your UUID here!
environment:
  REPO: grav-plugin-staticmath
  GH_USER: 9p4
tasks:
  - push-to-github: |
      cd ~/"${REPO}"
      git config --global credential.helper store
      git push --mirror "https://github.com/${GH_USER}/${REPO}"

This file assumes that the repositories are named the same on both Sourcehut and GitHub. In the case that the names are different, keep the REPO variable as the GitHub repository name and change the line with cd to be cd ~/sourcehut-repository-name.

As you push the repository with the new changes, Sourcehut should notify you that the build has started, like so:

$ git push
Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 20 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 776 bytes | 776.00 KiB/s, done.
Total 3 (delta 1), reused 0 (delta 0), pack-reused 0
remote: Build started:
remote: https://builds.sr.ht/~fd/job/1143073 [.build.yml]
To git.sr.ht:~fd/grav-plugin-staticmath
   2d70c2f..622bbf0  main -> main

Go to the URL to ensure the push succeeded, and take a look at the GitHub repository to check if the mirror process worked.

If so, great! There is one more issue, however.

Preventing Interaction on GitHub

Of course, this is just one-half of the puzzle. Preventing issues and pull requests from being opened on the GitHub repository and instead directing interaction to the canonical Sourcehut tools is also required.

In the settings for the GitHub repository, disable as many features as possible:

Unfortunately, you cannot disable pull requests on GitHub. To prevent pull requests from being created requires a different approach: a pull request template that yells at the user to NOT create a pull request!

In the .github/pull_request_template.md, I added the following:

# Your Pull Request Will Not Be Merged
This is a mirror of the [Sourcehut](https://git.sr.ht/~fd/grav-plugin-staticmath) repository.
I will close this PR.
If you want to contribute, please do so on Sourcehut.
[Here is how](https://git-send-email.io).
Yes, it requires sending an email.
It's easier than it sounds.
[Direct all attention to the Mailing List](https://lists.sr.ht/~fd/grav-plugin-staticmath)

This is in imperfect solution at best. At worst, people will ignore the message and create the pull request anyway. In this case, a GitHub action that automatically closes all pull requests may be in order (along with unwatching the repository so you are not spammed with emails for each individual who does not read the instructions).

Worse still, it is now harder (if not impossible) for people to then find the mailing lists and issue tracker. I've resolved to placing a set of links at the top of the README that link to the relevant places on Sourcehut:

- [Grav StaticMath Plugin](https://git.sr.ht/~fd/grav-plugin-staticmath)
- [StaticMath Server](https://git.sr.ht/~fd/staticmath-server)
- [Issues](https://todo.sr.ht/~fd/grav-plugin-staticmath)
- [Mailing List](https://lists.sr.ht/~fd/grav-plugin-staticmath)

This has the wonderful side-effect of offering links from the Sourcehut Git repository to the Sourcehut issue tracker (which does not exist otherwise, as the main project page is the only place that contains the resources side-by-side).

Farblos has also let me know that GitHub has support for a custom GitHub-specific README file in .github/README.md, if you wish to detail GitHub-specific information there.

So What?

So far, however, the GitHub mirroring has worked great! Pushing tags works automatically, and people are even creating issues! It does leave the question of how many contributors I am missing out on by not being on GitHub and not using their contribution tools (i.e. GitHub issues, GitHub PRs, etc.) My project is small enough and stable enough for me to not necessarily worry about the lack of contributors. Discovery is done through Grav's plugin page, and not GitHub, so having the canonical repository in another place is not as much of a detriment.

However, I do have another repository that is kept exclusively on GitHub: the jellyfin-plugin-sso. Frankly, people are put off by Sourcehut's workflow, and I don't blame them. Considering that it's much easier to ask for help on this repository compared to sending an email to ~fd/jellyfin-plugin-sso@lists.sr.ht (a sketchy email address if I've ever seen one), people can get more help, and so my project becomes better.

Sourcehut is great! I'm disappointed that it doesn't get more traction, but it's clear why Sourcehut remains a niche among developers. Indiscriminately moving everything to Sourcehut is not the solution if you wish to keep a community around your project. I've heard the argument that Sourcehut's model is nice because it keeps the "bad programmers" out. This elitism ultimately harms the open-source community.

I am more than happy with Sourcehut remaining a niche if I get to keep its workflow (which I do have some complaints about, but that's a post for another time), but that workflow is not great for most developers, even extremely experienced ones, who want to help out on a project.

Consider the kind of people who would create issues on the issue tracker, the kind of people who would want to do a drive-by contribution, and ask yourself if they are comfortable using Sourcehut.

Besides, I'm sure you can adapt these instructions for Codeberg anyway.

Some inspiration taken from Michael Kelly's blog.

Corrections? Comments? Just wanna say hi? Get in touch!

I'll be back to writing about Nix crimes and bizarre projects in no time, but wow is college hard. One post a week might be back on the table if I decide to start publishing the papers I have to write for my classes here, but don't count on it.

I'm also back on Mastodon. Don't make me regret this. And read the RFC if you send a follow request.