lnbits-sensei/docs/remotes.md

Remote topology

lnbits-sensei.git.remotes (declared in modules/git/remotes.nix) abstracts how the local LNbits checkout is wired to its git remotes. Three patterns cover almost every workflow.

1. Upstream-only

You read upstream, never push. Good for a read-only dev box, a CI runner, or initial exploration before you've decided to contribute.

lnbits-sensei.git.remotes = {
  upstream = "https://github.com/lnbits/lnbits";
  fork     = null;
  extras   = [ ];
};

What you get:

• upstream remote pointing at canonical lnbits/lnbits.
• No fork remote — the bootstrap script skips it when fork is null.
• No extras.

2. GitHub fork for PRs

You maintain a personal fork on GitHub and use it as your push target for PRs landing in upstream. upstream stays pull-only.

lnbits-sensei.git.remotes = {
  upstream = "https://github.com/lnbits/lnbits";
  fork     = "git@github.com:<you>/lnbits.git";
  extras   = [ ];
};

What you get:

• upstream for fetching releases / rebasing onto main.
• fork as the default push target.
• The upstream-PR helper (later pass) knows to push branches to fork and open the compare URL against upstream.

3. Multi-remote with a private host

You also push to a private forgejo / gitea / codeberg mirror — for internal review, a deployment pipeline, or just an off-GitHub backup. The upstream + public-fork flow stays intact; the extras layer on top.

lnbits-sensei.git.remotes = {
  upstream = "https://github.com/lnbits/lnbits";
  fork     = "git@github.com:<you>/lnbits.git";
  extras = [
    { name = "internal"; url = "git@<your-forgejo>:<org>/lnbits.git"; }
    { name = "mirror";   url = "git@codeberg.org:<you>/lnbits.git"; }
  ];
};

What you get:

• Same as pattern 2, plus the named extras as additional remotes.
• Each extra becomes a git remote add <name> <url> on bootstrap; pushing to them is opt-in (never the default push target).

Notes

• extras is a list of { name; url; } submodules — order is preserved, and future fields (pushUrl, mirror) can be added without breaking existing configs.
• The module is schema-only. The dev-env bootstrap script (later pass) is what actually runs git remote add against a real checkout. It is idempotent: re-running after editing extras reconciles the on-disk remotes with the declared set.
• fork = null is the right value when you have no GitHub fork — don't point it at a placeholder URL, the bootstrap script keys on null to skip the fork remote entirely.