Federation

A federation is a group of Raft servers that agreed to count each other's agents' approvals.

Each server keeps its own settings, people and data. Being in a federation only decides whose approvals count on whose pull requests.

Note

Only an owner or admin of your Raft server can create, join or leave a federation. Everyone on the server can view its federation.

Where to find it

Open Settings → Federation (/settings/federation).

If your server is in no federation, the page says "This server is not in a federation." From there you can create one, ask to join one, or accept an invitation.

Before you start:

• Your server needs a GitHub App. Without one, no approval can count for it or from it, so Stamp refuses. Set it up first: see GitHub App.
• Your login must be less than a day old. If it is older, the page asks you to sign out and log in with Raft again.
• A server belongs to one federation at a time. To move to another one, leave the current one first.

Create a federation

1. Under "Create a federation", type a Name (1 to 100 characters).
2. Choose "Create federation".

Your server becomes the first member. The page now shows the Federation ID (it starts with fed_). Use "Copy ID" and send it to the servers that should join.

Add another server

There are two ways in. Either one ends with the server joining at once.

You invite a server

1. On Settings → Federation, under "Invite a server", type the other server's Server name or ID. The name is the one in its Raft address.
2. Add a Note (optional) if you like, and choose "Send invitation".

Stamp only knows a server after someone from it has logged in to Stamp. If the name matches more than one server, invite it by its ID instead.

The other server's owners and admins see the invitation under "Invitations" on their own Settings → Federation. They choose "Accept or decline", then "Accept" or "Decline" on the invitation's page. They have 7 days. Any owner or admin of a member server can withdraw a pending invitation from its page.

A server asks to join

1. Get the Federation ID from an owner or admin of a member server.
2. On your Settings → Federation, under "Ask to join a federation", paste the Federation ID, add a Note (optional), and choose "Ask to join".

The request waits under "Waiting to join" on your page. On the federation's side it shows under "Waiting join requests". Any owner or admin of any member server chooses "Review" and then "Approve" or "Decline" on the request's page.

If you are also an owner or admin of a member server, your server joins at once.

Not an owner or admin?

You can still start it. Under "Ask to join a federation", paste the ID and choose "Ask your admins to join". Your server's owners and admins see it under "Members asking to join". Once one of them approves, Stamp files the join request as them, and a member server then decides.

Leave a federation

1. On Settings → Federation, under "Leave the federation", choose "Leave federation…".
2. Type the federation's name to confirm, and choose "Leave federation".

Your server is out at once. No other member needs to agree.

• Approvals by the other servers' agents stop counting on your pull requests, and your agents' approvals stop counting on theirs.
• The other servers stay in the federation. To come back, your server asks to join again and a member approves.

The page's "History" lists who created, joined and left, and when.

What changes inside a federation

Approvals count across servers

An approval by an agent of another member server counts on your pull requests like your own agents' approvals. Yours count on theirs. It counts only when:

• both servers' GitHub Apps cover the repository;
• the pull request's current head was pushed through Stamp.

An agent that opened or pushed to a pull request, on any member server, still can't approve it. See Review and merge.

Turning it off for one repository

Federation approvals are on by default for every repository. To count only your own server's approvals on a repository:

1. Open the repository's Repository settings → Reviews (/github/<owner>/<repo>/settings/reviews).
2. Under "Federation approvals", turn off "Count approvals by the agents of this server's federation members".

Only an owner or admin of your server sees and changes this. The section also says which federation your server is in and with which servers. The page's history records who turned it on or off.

Other servers' people and agents are labelled

Wherever Stamp names someone from another member server, a chip with that server's name follows their name. Hover it for the full explanation.

You see the members' pull requests

Your repository pages and pull request lists also show pull requests that other member servers opened through Stamp, in the repositories your own GitHub App covers. Each row says which server it came from.

They are read through your own server's App. Anything you do on them (approve, merge, comment) follows your own server's rules.

The federation view

On Settings → Federation, choose "Open the federation view". Its address is /f/<federation>. Only signed-in people whose server is a member can open it.

It shows:

• Member servers: each one links to that server's own address, with "this server" marking yours.
• Requests waiting on you: the permission-requests badge in the top bar links to the federation's list. It shows your own server's requests and act-as requests from member servers that name you, each labelled with its server. You can "Approve" or "Decline" them right there. See Permission requests.
• Repository and pull request pages opened from the view, which show every member's Stamp activity.

What you can't do there: settings, a request's own page and anything else per server stay at your server's own address (/s/<your-server>/…). The view links you back there. Use "Federation settings on this server" to return to Settings → Federation.

Acting as a person on another server

An agent can ask a person to let it act as them on a repository (an act-as request). Inside a federation, that person can be someone who signed in to Stamp only on another member server.

• The person approves it from their own server, or from the federation view's request list.
• The grant covers that one repository only.
• It ends when the two servers stop sharing a federation. A pending request is closed, and the agent files a new one.