The server's GitHub App

Stamp reaches GitHub through a GitHub App. Each Raft server has its own. This page is for the server's owners and admins. If you haven't set one up yet, start with Set up your team.

Why each server has its own App

• You control it. The App lives in your GitHub organization. You decide which repositories it is installed on, and your organization's owners can manage it on GitHub.
• One App, one server. An App serves only one Raft server. Another server can only use it if you share it (see below).
• One App per GitHub account. Each organization (or personal account) gets its own private App, which installs only on that account. To work in a second organization, open Settings → GitHub App and choose "Add an App for another organization".
• Sign-in goes through it too. When people choose "Connect GitHub", they connect through the server's App. With several Apps, that is the one marked "First App".

If you are not an owner of the organization, GitHub won't let you create its App. Choose "Hand it to the organization's owner", name a person of your server who owns it, and choose "Send request". They finish the setup from that request.

What the App's permissions are for

The App asks only for what Stamp does. It never asks for secrets, variables or discussions.

• Code (write): push branches. Workflows (write) is needed when a push changes files under .github/workflows.
• Pull requests (write): open and update pull requests.
• Checks and statuses (write): report check runs and Stamp's approval status on commits.
• Actions (write): re-run CI and start workflows.
• Issues (write): agents create, comment on and edit issues, and Stamp builds its issue pages from them.
• Branch protection (read): used by the merge queue.
• Organization members (read).

Settings → GitHub App has a "GitHub configuration check". It compares the App on GitHub with what Stamp needs. If something is marked in red, choose "Fix in Permissions & events on GitHub" and change it there.

Which repositories Stamp can work on

Stamp works only on the repositories your App's installations cover. Nothing else is in scope, and you can't add repositories in Stamp itself.

To add or remove repositories, change the installation on GitHub:

1. Open Settings and find "Repository access". It lists each installation and its repositories.
2. Choose "Manage on GitHub" next to an installation, then add or remove repositories there.

Stamp picks up the change on its own:

• GitHub usually tells Stamp right away when you add a repository.
• Stamp also syncs every 10 minutes.
• To sync now, choose "Refresh repository list" on Settings → GitHub App, under "Sync repositories".

If a sync fails, Settings → GitHub App says why and what to do. The repositories already synced stay in place. If the repositories haven't synced for over an hour, agents' commands are refused until the next good sync, so fix a failing sync promptly.

When a member hits a missing App

Only owners and admins can set up the App. Members and agents can ask.

The server has no App. Stamp refuses pushes, pull requests and reviews on a server without its own App (or one shared with it). People who sign in see "This server has no GitHub App yet":

• An owner or admin gets a button to "Create or link a GitHub App".
• A member sees "Owners and admins you can ask:" and a "Request a GitHub App" button.

A repository isn't covered. An agent is refused and told to run stamp app request --repo OWNER/REPO. That files the same kind of request, naming the repository.

Handling requests

Open requests appear on Settings → GitHub App as "Pending GitHub App requests". While any are open, your account menu shows "GitHub App requests" with a count. Each request says who asked and for what, for example "requested access to OWNER/REPO".

• Install the App on the repository (or set up or share an App). Once the App covers it, Stamp closes the request on its own, and an agent that asked is told.
• If you handled it some other way, choose "Mark as resolved".

Requests also show on the Requests page as "The server's GitHub App".

Sharing an App with another server

Another Raft server can use your App on the installations you pick. Shared installations aren't exclusive: you keep using them too.

On the server that owns the App:

1. Get the other server's ID from one of its owners or admins.
2. On Settings → GitHub App, under "Share with other servers", enter it as "Server ID" and choose "Look up".
3. Pick "All installations" (including ones added later) or "Selected installations" and tick them.
4. Choose "Share with {server}". The share shows as "Pending" until the other server accepts, then "Active".

You can change what is shared by sharing again, or end it with "Revoke". The other server loses those repositories at once.

On the server that borrows it:

1. On Settings → GitHub App, the "Use a shared App" panel shows this server's ID, with a "Copy" button. Send it to the other server's admin.
2. The offer appears at the top of that page. Choose "Accept" or "Decline".
3. Once accepted, the page shows the App under "Link". The owning server manages the App's keys, webhook and installations. To change what is shared, ask them.
4. To stop using it, choose "Leave". The server loses those repositories at once.

A server can use only one of these: an App of its own, or one shared with it. To accept a share, a server with its own App removes it first, and to set up its own App, a linked server leaves the link first.

If this Stamp deployment doesn't allow creating Apps, the no-App screen offers "Use a shared App" instead, and sharing is the way in.

Replacing or removing the App

Everything is on Settings → GitHub App, under "Manage this App":

• "Replace private key": make a new key on the App's GitHub page, enter it here, then delete the old key on GitHub.
• "Rotate webhook secret": Stamp makes a new secret and sets it on GitHub. Events signed with the old one still count for a few minutes.
• "Use a different App": enter another App's ID and private key to use it in place of this one. Then install the new App on your repositories. People connect GitHub again through the new App.

To stop using an App:

• With one App, choose "Unlink App" and tick the box to confirm.
• With several, open the App's card and choose "Remove from this server", then type the account name to confirm. If you remove the "First App", the earliest-added one takes its place, and people who connected through the removed one connect GitHub again.

Either way, Stamp stops working on that App's repositories at once. Tokens GitHub already issued stay valid for up to an hour. Stamp can't delete the App on GitHub: uninstall or delete it there if you no longer need it.