eblume/blumeops
1
1
Fork 0
Code Issues Pull requests Projects Releases 83 Packages Wiki Activity Actions
blumeops/docs/how-to/configuration/create-a-spork.md
Erich Blume 6ecfaf02b6 Add spork strategy: tooling and documentation 
Spork-create mise task sets up a floating-branch soft-fork of a
mirrored upstream project with daily mirror-sync via Forgejo Actions.
Includes explanation card, how-to guides for setup and branch
management, and the spork-create uv script.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-28 22:58:10 -07:00

2.4 KiB
Raw Blame History

title modified last-reviewed tags
Create a Spork 2026-03-28 2026-03-28
how-to
git
forgejo

Create a Spork

How to set up a floating-branch soft-fork ("spork") of a mirrored upstream project using mise run spork-create.

Prerequisites

  • Mirror already exists at mirrors/<project> on forge (see manage-forgejo-mirrors)
  • 1Password CLI authenticated (op CLI)
  • SSH access to forge.ops.eblu.me:2222

Create the spork

mise run spork-create kingfisher

This will:

  1. Fork mirrors/kingfisher → eblume/kingfisher on forge
  2. Create a blumeops branch from upstream's main branch
  3. Remove any upstream .forgejo/ directory (if present)
  4. Add .forgejo/workflows/mirror-sync.yaml and commit it
  5. Set blumeops as the default branch
  6. Clone to ~/code/3rd/kingfisher with three remotes: origin, mirror, upstream

Options:

mise run spork-create kingfisher --dry-run          # preview only
mise run spork-create kingfisher --no-clone         # skip local clone
mise run spork-create kingfisher --main-branch dev  # override branch name

Verify the setup

cd ~/code/3rd/kingfisher
git remote -v
# origin   ssh://forgejo@forge.ops.eblu.me:2222/eblume/kingfisher.git (fetch)
# mirror   ssh://forgejo@forge.ops.eblu.me:2222/mirrors/kingfisher.git (fetch)
# upstream https://github.com/mongodb/kingfisher.git (fetch)

git branch -a
# * blumeops
#   remotes/origin/blumeops
#   remotes/origin/main

What happens next

The mirror-sync workflow runs daily at 05:00 UTC and:

  • Fast-forwards main from the mirror
  • Rebases blumeops on top of main
  • Rebases any feature/local/* and feature/upstream/* branches
  • Rebuilds the deploy branch (all features merged)

See manage-spork-branches for working with feature branches.

Terminology

Term Meaning
origin Your mutable fork at eblume/<project> on forge
mirror Read-only upstream mirror at mirrors/<project> on forge
upstream Canonical upstream repository (e.g., GitHub)
main Clean upstream tracking branch (may be named master, dev, etc.)
blumeops Default branch — upstream + local workflows/tooling
deploy Build artifact branch — everything merged, used for deployments

See also