Skip to main content
Sign in
← All posts

Help getting a token right, and keeping it working

Every board reads and writes through a GitLab or GitHub account, and for many people that account is a personal access token. Tokens fail in quiet ways. One is missing a scope, so cards won't move. One expires on a weekend. One loses a permission, and the board goes on showing what it last saw. Until now you usually found out when something stopped working. These four changes are about finding out sooner, and knowing what to do.

A guided setup for new tokens

Add account, in Settings → Linked Accounts, is now a four-step setup instead of a paste box.

  1. Pick the kind of token. On GitLab, a legacy token with the api scope (recommended) or a fine-grained one. On GitHub, a classic token (recommended) or a fine-grained one. The recommended kind is the one GitGumbo can check for you. If you already have a token, you can skip ahead.
  2. Create it. A button opens the provider's token page with as much filled in as the provider allows: the name, the scopes and, for a GitHub fine-grained token, the repository permissions boards need and a 90-day expiry you can change. GitLab's fine-grained page can't be filled in from a link, so the step lists what to set, in the order GitLab asks for it.
  3. Connect it. Paste the token and GitGumbo shows what it checked as a checklist, where each line reads Passed, Missing or Not checked. A token missing a scope is still connected, read-only, and the step offers to replace it with one that has the scope. GitGumbo can't read a fine-grained token's permissions, so for one of those it lists them for you to confirm and never marks them as passed.
  4. Add projects. Each project you add shows its own checklist: whether your role is enough to move cards and create merge or pull requests, and whether GitGumbo could set up its webhook for real-time updates. If it couldn't, the line says why. The board still works and refreshes on the background interval instead.

Nothing is blocked. You can connect the token or the project and fix the gap later.

A warning before a token expires

GitGumbo now checks each linked token once a day. In the last week before one expires, you get:

  • A banner across the top of every page, with a link to replace the token. Only you see it.
  • One email to your own address, naming the boards that will stop updating.
  • A note on the account in Linked Accounts. Before that last week, the account just shows the expiry date.

You can dismiss the note, and the banner with it, until the last three days. After that both stay until you replace the token.

On GitLab, a fine-grained token needs the Personal Access Token: Read permission for GitGumbo to see its date. Without it, the account says GitGumbo can't see the date. GitHub reports the date with the requests a sync already makes. OAuth accounts don't expire this way, so they get no warning.

The same daily check also notices when a token has lost the scope boards need, or when your role on a board's project or repository has dropped too low to move cards or create merge or pull requests. Those show as notes on the account, naming the board. Check now on each account runs the check straight away.

When GitLab or GitHub says no, we say why

When a move, a reviewer request or a new merge request is refused, the message now says which part is short: the token's scope or permission, your role on the project, a token that doesn't include this repository, single sign-on the organisation still wants you to authorise, or a project the account can't see. Where there's a fix, the message links to it: the provider's token page, the single sign-on page, or the section of the guide that lists what every action needs.

The wording depends on who is looking. The member whose token runs the board is told what to change on their token. A teammate is told whose token it is, and that they can ask that member to update it or ask a firm admin to switch the board to another account.

A notice when a GitLab board stops updating its Status

Status, linked items and board Status lists come from GitLab's GraphQL API, not the one that reads the cards themselves. If GitLab refused those reads, the cards kept syncing and the board looked fine, while Status and links quietly stayed as they were.

Now the board shows a notice when that happens, saying what has stopped updating and that it shows what GitLab last sent. For a fine-grained token, it names the permissions GitLab asked for, or explains that GitLab doesn't yet let fine-grained tokens make those reads and suggests a token with the read_api scope. The notice clears once GitLab answers again.

The Linked accounts and tokens guide has the full list of what each action needs on GitLab and GitHub.