Connect Linear and GitHub

A Stream Source is an account Fermata reads issues from: a Linear workspace, or a GitHub account. Connecting one is app-wide; you paste a key once and every project can see it. Which accounts a project actually reads is that project’s choice. Nothing in Streams writes to Linear or GitHub. Settings → Streams holds all of it. The pane looks different depending on the scope switcher at the top of Settings: with “All projects” picked it lists every connected account, and with a project picked it leads with that project’s Streams and the accounts it reads.

Connect an account

The “Connect an account” row, captioned “Linear or GitHub”, has two buttons: Linear… and GitHub…. Its (i) says: “Stream Sources are the accounts Fermata reads issues from. Keys stay in your Keychain.” Linear takes a personal API key. The sheet says “Paste a Linear personal API key. Fermata reads the workspace name back from it.” and links to “Create a personal API key in Linear”. GitHub offers the GitHub CLI first. When gh is logged in to github.com, the sheet shows Use gh account with the account’s name, and “Fermata asks the GitHub CLI for its token when it reads issues. Nothing is stored.” Otherwise, or if you prefer, paste a fine-grained token: “Or paste a fine-grained token with read access to Issues.” Fermata reads github.com only; a CLI logged in to another host is not offered. Press Connect. Fermata checks the credential with the tracker first (“Checking with Linear…”), and a refused key keeps the sheet open with the reason and stores nothing. When Settings is pointed at a project, the sheet also carries Use in with the project’s name, on by default, so the account is read in that project as soon as it connects. Turn it off and “the account is connected but no project reads it yet.”

Health

Each account row names the kind and the account (“Linear · Acme”) with a health line under it: Health is checked when the pane opens. The row’s ⋯ menu (“More actions for this account”) has Check now to ask again, and Disconnect account….

Choose which accounts a project reads

Point Settings at a project and the pane splits the accounts in two:

• “Accounts used in” the project lists the accounts this project reads. “Only these accounts appear in this project’s issue pickers.” Each row has Stop using here.
• “Other accounts” lists the ones connected in Fermata but not read here, each with Use in and the project’s name. A row also says which other projects read it (“Read in muse, atlas”), so you can tell whose workspace it is.

Stopping an account in a project that has Streams on it asks first, because those Streams go with it: “Stop Using and Delete 1 Stream”. Pieces already started from its issues keep their links.

Narrow a project’s read

A used account carries one more line, its narrowing, and clicking it opens the sheet that sets it. Linear: teams. “All teams” by default, which reads the whole workspace. Choose teams opens “Teams in” the workspace: pick the teams this project reads issues from, or press All teams to go back to the whole workspace. Use this when one Linear workspace serves several repositories. GitHub: the repository. A GitHub account reads the repository the project’s origin points at, shown as “origin: owner/name”. Choose a repository lets you name a different one as owner/name, for a project whose issues live in another repository; leave it empty to follow origin again. When origin is not on github.com the line reads “No repository”, and the account reads nothing in this project until you pick one.

Disconnect

Disconnect account… confirms with “Disconnect this account?” and says what it does. A pasted key is deleted from the Keychain; a CLI connection leaves the GitHub CLI logged in. Every project that read the account stops reading it. Pieces already started from its issues keep their links.

Next

With an account connected, you can pick a single issue by hand (starting from an issue), or add a stream so matching issues come to you.