Federation

Federation lets people on another GitBlixt instance fork your repositories and send you merge requests, without an account on your instance. Each instance keeps its own users; the two instances vouch for each other with signed requests.

How it works

• Every instance publishes its URL and public key at /.well-known/gitblixt. Requests between instances are signed with that key.
• A peer starts as pending and can do nothing until an admin marks it trusted. An admin can also block a peer.
• A merge request from a peer is opened by a stand-in user named username@their-host. That user cannot sign in or push.
• The upstream fetches the contributor's branch itself, over HTTPS, from the fork's public clone URL. The fork must be reachable from the upstream.
• When the merge request is merged or closed upstream, the contributor's instance is told, and the submission shows its new state there.

Connecting two instances

Both instances must add each other, and both admins must trust the other side.

1. As an admin, open Admin → Federation (/admin/federation).
2. Under Add a peer, enter the other instance's URL (for example https://git.example.com), an optional name, and an optional message to its admins — say who you are and what you want to contribute to.
3. Click Add peer. Your instance reads the peer's public key and sends it a signed peering request.
4. The other instance adds you as pending and notifies its admins, with your message. Nothing else happens until one of them acts.
5. Each admin clicks Trust on the other instance. Trusting on your side lets it send merge requests to you; its admin trusting you lets you send merge requests to it.

If a peer rotates its key, click Refresh key on its row to read the new one.

Accepting merge requests on a repository

Trusting a peer is not enough on its own: each repository must opt in. Open the repository's Settings and tick Accept merge requests from federated instances. Repositories that have not opted in look missing to peers.

Contributing to a repository on another instance

1. On your instance, open New repository, click Fork from remote URL (/new/fork-remote), and paste the upstream's HTTPS clone URL, such as https://git.example.com/team/project.git.
2. Push your work to a branch on the fork.
3. Open the fork's merge requests and click Submit upstream (/:namespace/:repo/-/merge_requests/upstream). Pick the source and target branches, write a title and description, and submit.
4. Keep pushing to the same branch to update the merge request. The upstream re-fetches it.

Limits

• Submitting upstream is only available in the web UI. The REST API and glab cannot open a federated merge request yet.
• CI pipelines do not run on the upstream for federated merge requests.