initial commit

2025-07-02 16:02:49 -04:00 · 2025-07-02 16:02:49 -04:00 · ed6c1e9522
commit ed6c1e9522
58 changed files with 2221 additions and 0 deletions
--- a/content/blog/mirror-srht-to-github.md
+++ b/content/blog/mirror-srht-to-github.md
@ -0,0 +1,112 @@
+---
+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!