GitHub

The issue lives here. The code lives on GitHub. Connecting the two means an issue can say this is the pull request that fixes me, and — if you want it to — move itself along the board when that pull request is merged.

This is optional, it is off until somebody sets it up, and it is worth setting up only for a server where the work on the board is code somebody pushes. A server running a moderation queue or a stream schedule should skip this page entirely.

If you have never wired two tools together like this, the shape is: you connect the server to a GitHub account once, you link the repositories that matter, and from then on people write an issue's identifier into the pull requests they open. Nobody has to press anything on the dashboard afterwards.

What it does, and what it does not

That last row is the one to read twice. Everything on this page is FlaviBot listening to GitHub. Nothing here writes anything back to your repository, which is also why the access it asks for is read access.

Connecting the server

One connection per server, set up under Management > Projects & Tasks, in Settings, by somebody with Manage settings (Manage Server, or the Admin preset). It asks for three things:

The GitHub App is the proper way in: you install it on the account, pick the repositories it may see, and GitHub tells FlaviBot who you are. The token path exists for servers that would rather paste a fine-grained personal access token — give it read access to the repositories you intend to link and nothing more, because nothing here needs to write.

The token and the webhook secret are stored encrypted, and neither ever comes back out: no route returns them, the dashboard never shows them again, and there is no masked "last four" anywhere. What the page shows is whether a credential is stored. Rotating one is pasting the new value over it; there is nothing to reveal first.

A connection that GitHub starts refusing — a revoked token, an uninstalled App — stamps the last thing it was told and the page says so, so a sync that stopped working is visible rather than merely quiet.

The webhook secret is the whole trust boundary

FlaviBot receives what GitHub sends it, and anybody on the internet can send something that claims to be from GitHub. The secret is what separates the two: every delivery carries a signature computed with it, FlaviBot recomputes that signature over the raw body, and a delivery whose signature does not match is refused before it is read. Not parsed, not logged with its contents, not acted on.

Two consequences, both deliberate:

• A connection with no secret stored accepts nothing inbound. The link still works from your side — repositories, manual attachments — but nothing arrives on its own.
• If the secret ever leaks, rotate it on both sides straight away. Somebody holding it could forge a delivery, and a forged delivery is somebody moving issues in your server.

A delivery about a repository this server has not linked is dropped without an answer. It is not this server's business, and answering differently would tell the sender what other people have linked.

Linking a repository

A connection on its own does nothing. Link repository adds one, by owner and name — flavibot/web — and each linked repository carries its own settings:

The three switches are worth a sentence each. Link pull requests is the one this page is mostly about, and it is on because it is the whole point: without it, nothing attaches itself. Sync issues is the one that goes and reads the repository's own issue list rather than waiting for somebody to write an identifier — leave it off unless you actually want GitHub issues appearing on your board, and note that it reads only: nothing you do here is written back to GitHub. Move issues automatically is the board moving on its own, and it has a section of its own below.

FlaviBot remembers the repository by GitHub's own id rather than by its name, so renaming a repository or transferring it to an organisation keeps every link that hangs off it working.

Unlinking a repository removes it and the attachments made through it. The issues themselves are untouched — they simply stop mentioning a pull request.

How many repositories a server may link depends on the plan; see limits at the foot of this page.

Magic words

Once a repository is linked with Link pull requests on, nobody needs to touch the dashboard again. Write an issue's identifier into a pull request and FlaviBot attaches it.

FlaviBot reads three places: the title of a pull request, its body, and the message of a commit pushed to the repository. In each it looks for one of these words followed by an identifier:

So:

fixes WEB-12 — rewrite the pricing section
refs WEB-19, and part of WEB-4

The first line attaches WEB-12 and arms the automation. The second attaches WEB-19 and WEB-4, and neither of those will ever be moved by this pull request — which is exactly what you want for the issue a change merely touches on the way past.

Three details worth knowing:

• Case does not matter, on the verb or on the identifier: Fixes web-12 is the same as fixes WEB-12.
• The words are whole words. prefix WEB-12 is not fix, and WEB-123 is not WEB-12. A tracker that guessed here would attach the wrong issue quietly, which is worse than attaching nothing.
• Attaching is not something that happens twice. The same words in a title, in the body and in three commits are one attachment, not five.

You can also attach one by hand, from the issue itself or with Link a pull request in the command palette, and that is how you attach a pull request whose author forgot, or a GitHub issue rather than a pull request.

FlaviBot remembers how a link came to exist, and it matters: automation only ever undoes its own work. A link a magic word made can be dropped by a later pass over the same pull request; a link you made by hand is removed by a person and by nothing else.

The merge automation

Off by default, per repository, under Move issues automatically. With it on, and for issues attached by a closing word above:

And the list of things it will not do, which is longer and more important:

• It never moves a closed issue. Something already in a Done or Cancelled column stays there; a late merge does not reopen finished work.
• It never moves an issue you attached by hand, unless the pull request itself used a closing word. A link somebody made to say these two are related is not permission to move their issue.
• ref, refs and part of never move anything, in either direction. That is the entire difference between the two groups of words.
• A pull request closed without being merged moves nothing. Abandoning a branch is not finishing the work, and the issue is left where the team put it.
• With no state chosen for a merge, a merge moves nothing. The attachment still happens; the board simply waits for a person.
• Nothing is ever written back to GitHub. The GitHub issue is not closed, no comment is posted, no label is set, no branch is made.

A word on whether to turn it on at all. Automatic state changes are lovely right up to the afternoon they move something you were in the middle of talking about. The setting is per repository precisely so you can try it on the repo where the workflow is tidy and leave it off on the one where it is not. Choosing In Review rather than Done for a merged pull request is the conservative setting most teams end up on.

What a linked issue looks like

An issue with something attached carries a banner at the top of its page — Issue synced with GitHub #2891 — and each attachment is a row naming the repository, the number, the title GitHub last reported and its state: open, draft, closed or merged. Clicking it opens the pull request.

The same thing shows more compactly elsewhere: a #2891 badge on the board card, once GitHub is one of your card properties, and on the issue's card in Discord and in /task view, where it appears whenever the issue has something attached. The filter bar can keep only the issues that have something attached, or only the ones that have nothing — what merged this week and what is still only a conversation are both questions somebody asks on a Friday.

An issue may carry 25 attachments. A title FlaviBot has not heard about yet — a pull request attached by a magic word seconds ago — shows as its number until the next thing GitHub says about it fills the rest in.

What this version does not do

Three things that a GitHub integration could plausibly do and this one does not. They are listed here rather than left to be discovered:

• Two-way comment mirroring. A comment on the issue does not appear on the GitHub pull request, and a comment on GitHub does not appear on the issue. The discussion stays where it was written: the dashboard and the issue's Discord thread on one side, GitHub on the other.
• Creating a branch from an issue. There is no start work on this button that makes a web-12-… branch for you. Make the branch the way you always make it, and name the issue in the pull request.
• GitHub Projects sync. A GitHub Project board and a FlaviBot board stay two separate boards. Nothing is copied between them in either direction, and moving a card on one does not move anything on the other.

None of the three is ruled out forever; they are simply not in this version, and a page that implied otherwise would be worse than a page that says so.

When it refuses

A delivery that fails its signature check is refused with no detail at all, and shows up as a failed delivery in GitHub's own webhook log. That is the one failure the dashboard cannot explain to you, by design: telling an unverified caller why it was refused is telling it how to get it right next time.

When GitHub asks FlaviBot to slow down, FlaviBot slows down and catches up afterwards; a burst of activity is not lost, it simply arrives over the next few minutes.

Limits

The rest are the same for everybody:

A linked repository is inbound traffic and outbound calls against a shared rate limit, which is why it is capped more tightly than projects are. The connection itself is not capped: there is one per server whatever your plan is, and the free tier gets a repository to point it at.

Next: doc pages.