Setup guide

Setting up Fervio with GitHub

What to click on GitHub, what Fervio creates for you, and what to check when a project or an organisation does not appear. Roughly ten minutes end to end. If you use Linear instead, most of this still applies — the differences are noted as you go.

Before you start

A GitHub account, and permission to use the repositories whose issues you want on the map.
A Projects v2 board — either one you already have, or one Fervio creates for you in step 3. Classic Projects are not supported; Fervio reads the Projects v2 API only.
If the project belongs to an organisation, someone with owner rights may need to approve Fervio once. Section 6 covers that, and it is the single most common reason a project does not show up.

1. Sign in

Open fervio.co/app and choose how you want to sign in. GitHub shows a consent screen once, then returns you to Fervio.

SHOT 01 GitHub's "Authorize Fervio" consent screen, showing the requested scopes

GitHub asks once. The wording is GitHub's, and it is broader than what Fervio uses — see the note below.

The screen will say "Full control of private repositories." That wording is GitHub's own. GitHub has no issues-only permission, so reaching issues inside a private repository means asking for the broad scope. Fervio never calls an API that reads source code, but that is a promise from the program, not something GitHub enforces. The Permissions page sets out exactly what is granted, what is used, and which single narrowing GitHub does enforce.

There are three ways in, and they differ in what you hand over:

Way in	What it can reach	Pick it when
Default	Public and private repositories	Your issues live in private repositories. This is the usual choice.
Public repositories only	Public repositories only, enforced by GitHub	You want a hard guarantee rather than a promise. Private projects will not open.
Email link	Nothing at GitHub until you connect it	You want to look around first. Connect GitHub later from Settings; you land on the same account.

2. Check what got connected

After signing in you land on your boards. Open Settings from the menu under your name and confirm the connection is listed. One account can hold both a GitHub and a Linear connection at the same time, and more than one Linear workspace.

SHOT 02 Fervio → Settings → Connections, with GitHub connected

Each connection is a key of your own. Nobody borrows anyone else's.

3. Create your first board

A space groups the boards that belong to one connected account. A board is one story map over one project. Press + Board on a space heading to start.

SHOT 03 Fervio boards list, with the "+ Board" button on a space heading

Boards are always created inside a space, never outside one.

The wizard asks, in order:

Personal or organisation. These need different permissions and create things in different places, so the wizard splits them at the start rather than mixing them.
How to start. Three routes, covered just below.
Where new issues go. A Projects v2 board can span several repositories, so the project alone does not decide it. Pick the repository that new cards should be created in. You can override this per column later.
Name it. Already filled in from what you picked. Change it or press through.

SHOT 04 The wizard's three routes: new project, existing project, import issues

All three end in the same place — a map you can edit.

Which route to take

Route	What happens
New project	Fervio creates a Projects v2 board, adds the two fields the map needs, and opens an empty map.
Existing project	Your project is used as it is. Fervio adds the two missing fields if they are not already there, and touches nothing else.
Import issues	Fervio creates a project, then adds the issues you select from a repository. Good for a backlog that is not on a project board yet.

4. The two fields the map is built on

A story map has a backbone across the top and cards underneath. Fervio stores that backbone in two single-select fields on your Projects v2 board, found by name:

Journey — the top band, the coarse stages of the story.
Step — the columns underneath a journey.

Fervio creates them if they are missing, whichever route you took. You do not have to make them by hand — but knowing they are ordinary project fields explains everything else: you can edit them on GitHub, other tools can read them, and removing Fervio leaves them behind intact.

SHOT 05 GitHub → your Project → Settings, showing the Journey and Step single-select fields

Renaming either field on GitHub hides the backbone in Fervio, because the match is by name.

On Linear the same two levels come from initiatives and projects instead, so there is nothing to create.

5. Rows — releases or sprints

The horizontal slices of a map are the release you are cutting, or the sprint you are in. Fervio reads them from GitHub, so you set them up on GitHub:

Releases come from milestones on the repository. Create them under the repository's Issues tab.
Sprints come from an iteration field on the project. Add it in the project's field settings; Fervio picks it up automatically.

SHOT 06 GitHub → repository → Issues → Milestones, with a few milestones

Milestones become the release rows, ordered by due date.

SHOT 07 GitHub → your Project → Settings → a new iteration field

With an iteration field present, the row switch in Fervio offers sprints as well as releases.

6. Using an organisation's project

This is where setup usually stalls. GitHub restricts third-party application access to organisations by default, and an unapproved organisation does not appear as denied — it disappears from the list entirely. Zero organisations and "no organisations" look identical.

On GitHub, open the organisation's Settings → Third-party Access → OAuth application policy.
Find Fervio and grant it, or press Request approval if you are not an owner. An owner has to approve it once.
Back in Fervio, reload the boards list. The organisation now appears.

SHOT 08 GitHub → organisation → Settings → Third-party Access, with Fervio listed

Granted or requested — either way, this page is where an organisation becomes visible.

The first time you take the organisation route, Fervio also asks GitHub for permission to read your organisation membership. That is a second, smaller consent screen. It is asked only on that route, so people who never touch organisation projects are never asked for it.

If the organisation still shows no repositories after approval, check whether it uses an IP allow list. An allow list that does not cover the application blocks the request while leaving the organisation visible, which reads as "approved but empty."

7. Bringing other people in

There is no invite button, by design. Send someone the board URL. When they open it, Fervio asks GitHub whether they can see that project, and that answer decides everything:

Can see it on GitHub → the map opens.
Can edit it on GitHub → they can edit the map.
Cannot see it on GitHub → the board does not exist as far as they are concerned.

So you add and remove people on GitHub, in the repository or organisation, exactly as you already do. Removing someone there removes them here on their next request. The member list Fervio shows is a bookmark for the boards list, not a permission.

For people without a GitHub account, publish a view-only link from the board menu. Anyone holding that URL can open a read-only snapshot without signing in, so treat the URL itself as the secret. Links expire after 90 days, and anyone who can edit the board can revoke every link on it.

SHOT 09 Fervio → board menu → view-only link, showing the URL and the revoke action

A snapshot of the map as it was when you published it.

8. When something does not show up

What you see	Why	What to do
The organisation is not in the list	Its OAuth application policy has not approved Fervio.	Section 6. GitHub hides unapproved organisations rather than refusing them.
The organisation is there but has no repositories	Usually an IP allow list.	Have an owner check the organisation's IP allow list settings.
The map is empty although the project has items	Nothing is assigned to `Step` yet, or the fields were renamed on GitHub.	Check the field names are exactly `Journey` and `Step`, then set `Step` on a few items.
No sprint rows	The project has no iteration field.	Add one in the project's field settings (section 5).
Cards can be moved but nothing saves	You have read access on GitHub, not write.	Ask for write access to the project. Fervio mirrors GitHub and cannot grant more.
Everything is read-only	You are over the free plan's board limit.	Choose which boards stay editable in Settings, or upgrade. Nothing is deleted either way.
A Linear board will not open	That board belongs to a workspace you have not connected.	Connect that workspace in Settings. You can hold several at once, so there is no need to reconnect.
The card count stops at 2,000	That is the size limit, set so the map stays smooth to drag.	Narrow the project, or split it across two boards.

9. Undoing it

Deleting a board removes its ordering, its member list and any share snapshot from Fervio. Your issues, project and milestones on GitHub are untouched — with one exception you have to opt into: a project that Fervio's wizard created can be deleted along with the board if you tick that box.

To remove everything, use Delete account at the bottom of Settings. Fervio also revokes its own authorisation at GitHub, so it disappears from your authorized applications. You can revoke it yourself at any time from GitHub → Settings → Applications.

Want a copy first? Export your data in Settings gives you a JSON file with the ordering and row assignments, which exist nowhere else.

Still stuck?

Write to [email protected]. The person who built Fervio reads it. Say which of the rows in section 8 looks closest, and it will be a much shorter conversation.