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). There is nothing to paste: FlaviBot has its own GitHub App, and connecting is three clicks on GitHub's side.

1. Connect with GitHub sends you to the FlaviBot GitHub App on GitHub.
2. Pick the account or organization, and the repositories the App may see — all of them, or only the ones this server should follow.
3. Authorize the App. GitHub sends you back to the dashboard, connected.

That last step is GitHub telling FlaviBot who you are, and it is why nobody can connect an account that is not theirs: FlaviBot asks GitHub, as you, whether you may use that installation before it stores anything.

• A personal account is connected by its owner only.
• An organization is connected by a member who can read every repository the App was given — an owner always can. If the App on your organization shares repositories you cannot read, either ask an owner to connect it, or narrow the App's repository access on GitHub.
• If you are not an owner of the organization, GitHub sends its owners a request to install the App instead. Once one of them approves it, press Connect with GitHub again.

Nothing of yours is stored: no token, no password, no secret. The App reads repository metadata, issues, pull requests and commits, with read access only, because nothing here writes back to GitHub.

Manage on GitHub on the connection opens the App's settings for your account, where you add or remove repositories, suspend the App or uninstall it. The card follows what you do there: a repository taken away from the App is marked Not shared with the App (its links stay), a suspended App and an uninstalled one are said plainly, with what to do about them.

When GitHub refuses a request FlaviBot makes — listing repositories, checking one you link — the card shows GitHub's own answer under GitHub refused the last request, and it disappears as soon as a request succeeds.

Servers connected with a token

Before the App, a server connected by pasting a personal access token and setting a webhook on each repository. Those connections keep working — every repository's webhook still arrives — but tokens are no longer accepted, and the card asks you to reconnect with the GitHub App. Once you have:

• the stored token and webhook secret are deleted on the spot;
• delete the old webhook from each repository on GitHub (its deliveries are refused from then on, which GitHub shows as failed deliveries);
• the linked repositories and every attachment stay exactly as they were.

Every delivery is verified

FlaviBot receives what GitHub sends it, and anybody on the internet can send something that claims to be from GitHub. Every delivery from the App carries a signature only GitHub and FlaviBot can compute; a delivery whose signature does not match is refused before it is read. Not parsed, not logged with its contents, not acted on. A delivery is routed by the App installation it names and the repository, to the servers that connected that installation and linked that repository, and to no other.

Linking a repository

A connection on its own does nothing. Link a repository offers the repositories the App can see; pick one, 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, or Issue linked to pull request #212 when the one thing attached is a pull request (draft pull request while it is still a draft) — 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 delivery 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.