> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fermata.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Linear and GitHub

> Stream Sources are the tracker accounts Fermata reads issues from. Connect one once; each project picks which ones it reads.

> [!NOTE]
>
> Streams and Tracks are an Edge preview, part of **Loop intake**. Turn on Settings → Edge → **Enable Edge features**, then **Loop intake** in the "Features" card. See [Edge features](https://docs.fermata.run/configuration/edge.md).

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 | Meaning |
| - | - |
| "Connected" | The last check worked. |
| "Not checked yet" | Fermata has not checked this account yet. |
| "Rate limited, retry shortly" | The tracker asked Fermata to slow down. When it gave a time, the line names it instead. |
| "API key expired or revoked" | Linear refused the key. Connect it again. |
| "Token expired or revoked" | GitHub refused the pasted token. |
| "GitHub CLI is logged out" | Run `gh auth login` in Terminal, then check again. |

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](https://docs.fermata.run/loop/from-an-issue.md)), or [add a stream](https://docs.fermata.run/streams/add-a-stream.md) so matching issues come to you.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.