Real-time updates

How real-time updates work

Your board keeps itself current — you never hit refresh. It re-checks for changes every 5 seconds on Pro, every 30 seconds on Free, and again the moment you switch back to the tab.

What real-time updates change is how fresh the data underneath that is. On Pro, GitGumbo registers a webhook with GitLab or GitHub, so when a pipeline finishes or a review lands we hear about it straight away — and because your board re-checks every 5 seconds, you see it within seconds.

Without a webhook, nothing breaks, and you are never left waiting. Boards refresh on the background sync interval — every 5 minutes on Pro, every 15 on Free — and you can always pull changes in yourself: Sync refreshes the whole board, and the ↻ on any card refreshes just that issue and its merge requests. Both work on every plan.

The same timing carries over to the history GitGumbo keeps of what changed on your board over time. An event — a merge landing, a card moving column — is recorded the moment its webhook arrives on Pro, and on the next background sync without one. On a board you're watching, that gap is noticeable; in history read back over days or weeks, it isn't. Either way the change is recorded, not lost.

Two things have to be true for a webhook to exist. Your plan has to include real-time updates, and the account you connected has to be allowed to create webhooks on that project. The sections below cover what to do when the second one isn't true.

The connected account needs permission to create webhooks

This is the most common reason real-time updates aren't running. Reading a project and adding a webhook to it are different permissions, and GitGumbo can do the first without being able to do the second.

On GitLab, the connected account must be a Maintainer or Owner of the project. A Developer can read everything on your board and still not be allowed to create the webhook.

On GitHub, the connected account must have admin access to the repository. Note that GitHub answers with a 404 (not a 403) for repositories your token isn't allowed to administer — so if you see “not found” for a repo you can clearly see, it almost always means “not an admin”, not “doesn't exist”.

To fix it, either ask a project owner to grant the connected account the role above, or connect an account that already has it. Then open the sync-health pill on your board and choose Try again.

GitLab: your token needs the api scope

GitLab tokens carry scopes, and a token with only read_api can read your issues and merge requests but cannot create a webhook. The api scope is required.

Use the Reconnect button in the sync-health pill and approve the api scope. Note that this is the same scope that lets you drag issues between columns, so granting it fixes both at once.

If a webhook was already registered before the token was downgraded, it keeps delivering — GitLab doesn't check your scope when it fires an existing hook. That's why a read-only token doesn't switch real-time off if it was already on.

The provider was unreachable

GitLab and GitHub occasionally time out, rate-limit us, or return a 5xx while we're setting the webhook up. We record that it happened and we don't retry automatically, because a retry loop against a struggling provider helps nobody.

There is nothing to fix on your side. Open the sync-health pill and choose Try again — this usually just works.

We don't have a reason on record

The popover only ever tells you a reason we actually recorded. If we don't have one — because the project predates us recording reasons, or the attempt failed in a way we couldn't classify — we say so rather than guessing at a cause and sending you off to fix the wrong thing.

Choose Try again. Whatever the provider says this time gets recorded, and the popover will then name the real reason and point you at the section above that fixes it.

Real-time on

A webhook is registered and delivering — on Pro, changes reach your board within seconds.

Real-time off

No webhook. Your board still refreshes on the background interval and manual Sync — it's just slower to notice changes. Open the pill to see why.

Periodic sync

Real-time updates aren't part of your plan. Boards refresh on the background interval and manual Sync.

Sync error

The last sync failed. The popover shows what the provider said.

Sync paused

The connected account needs to reconnect before anything can sync.