Linked accounts and tokens

GitGumbo reads your projects through GitLab and GitHub accounts you link to it. You manage them in Settings → Linked Accounts.

GitGumbo works with GitLab.com and GitHub.com. Self-hosted GitLab and GitHub Enterprise Server aren't supported yet.

Two ways to link an account

• OAuth is the account you sign in with, or one you link with Link GitLab / Link GitHub. That button appears for a provider you haven't linked any account for yet. GitLab is asked for the api scope; GitHub for access to your repositories and projects, and to read your organisations, profile and email address.
• A personal access token (PAT) links another account by pasting a token you create on GitLab or GitHub. Use one for a second identity, such as separate work and personal accounts, or an account that belongs to other organisations.

Each linked account shows an OAuth or PAT badge and its username. You can give any account a label, such as "work", by clicking add label.

Tokens are stored encrypted.

Add a personal access token

1. Choose Add account under GitLab or GitHub.
2. Create a token on the provider with Create a token:
   • GitLab: the api scope.
   • GitHub: a classic token with repo, read:org, read:user and project. Fine-grained tokens also work; GitHub then decides what each one may do.
3. Paste it, optionally add a label, and choose Connect. GitGumbo checks the token with the provider straight away.

An account can only be linked once. If that GitLab or GitHub account is already linked, whether by you or by someone else, the token is refused. A token is for a different account, not for more access to one you've already linked.

A GitLab token with only read_api is accepted, but boards read through it are read-only: you can't move cards or create merge requests, and real-time updates can't be set up. Replace it with an api token to fix all three.

On GitHub, a classic token without the repo scope is read-only too: you can't move cards or create pull requests, and the board shows a notice that says so. Replace it with a token that has repo. A fine-grained token's permissions can't be read, so the board shows no notice for one and GitHub decides.

You can add up to 10 tokens (or replacements) in 10 minutes.

Replace or remove a token

• Replace token: paste a new token for the same GitLab or GitHub account. A token for a different account is refused. Use this when a token expires or you want different scopes.
• Remove: unlinks the token. Boards that read through it move to another of your accounts on the same provider, your OAuth one first. If you have no other account there, those boards become disconnected until a firm admin re-points them. You can't remove a token that runs boards in a firm where you're not an admin; an admin there has to move or remove those boards first.

Removing a token here doesn't cancel it on GitLab or GitHub. Revoke it there too if you want it to stop working altogether.

OAuth accounts have no Remove button. To cut GitGumbo off, revoke its access in your GitLab or GitHub settings.

Which account a board uses

When you add a project, you pick the account to add it with if you have more than one on that provider. From then on the board syncs, and makes every change, through that account, for everyone in the firm. A firm admin can move a board to one of their own accounts with Reassign… in Firm settings → Boards.

Plan limits count the accounts that back boards, not the accounts you link: 1 on Free, 4 on Pro and 10 on Team. You can link as many as you like. Using an account that already backs one of the firm's boards doesn't count again.

When a project is private, links on its cards say which account to be signed in to on GitLab or GitHub to open them.

When an account needs to reconnect

If GitLab or GitHub rejects an account, because its token was revoked or expired, GitGumbo stops syncing through it:

• You see "Sync paused — reconnect needed" across the top of every page. Only the account's owner sees this banner.
• In Linked Accounts, the account shows Reconnect needed. For OAuth, choose Reconnect and approve the access again. For a token, choose Replace token and paste a new one.
• Everyone else in the firm sees Sync paused on the pill of the boards that account runs.

The warning clears after the next successful sync.

When someone leaves

Boards read through a member's accounts become disconnected when that member leaves the firm, is removed or deletes their account. The board keeps everything it had but stops syncing, and changes can't be made from it. A firm admin fixes it with Reassign… in Firm settings → Boards.

"You already have an account with this email"

This appears on the sign-in page when you first signed up with the other provider. Sign in with that one, then link this one here with Link GitLab or Link GitHub.