# GitHub and Linear

> Start each project from the agreed scope, then watch the work move against the milestones the client signed up for.

Source: https://sydbar.app/docs/github-linear

## Connect once per business

Go to **Settings → Connections → Project tools**, or start from a client's **Delivery** section. Choose **Connect GitHub** or **Connect Linear** and approve access.

| Tool | Access Sydbar asks for | Why |
| --- | --- | --- |
| GitHub | `repo` | Read milestones, issues, pull requests and releases; write the scope file and milestones when you ask. |
| Linear | `read`, `write` | Read projects, milestones and issues; add the scope document and milestones when you ask. |

Prefer a token? Choose **Use a token instead**: a GitHub personal access token with repo access, or a Linear personal API key from Settings → Security & access in Linear.

## Link a client's repo and project

On the client page, under **Delivery**, choose **Link a GitHub repo** or **Link a Linear project** and pick it from the list (or type `owner/name` for a repo). One of each per client.

## Set up the project from the scope

Once the scope is confirmed, one click puts it where the team works:

| Tool | What Sydbar adds |
| --- | --- |
| GitHub | The scope as `README.md` (or `SCOPE.md` if the repo already has a README), and a milestone per scope milestone, named like "M1 · Events page". |
| Linear | The scope as a document in the project, and a project milestone per scope milestone. |

It's safe to run again. When you confirm a new scope version, the button changes to **Update** and rewrites the same file or document.

## Track progress

Under each milestone on the client page, Sydbar shows how much of its work is done, with the issues and pull requests behind it.

- Milestones match by the pairs Sydbar made at setup, then by names starting with the milestone number (M1, M2), then by the same name.
- Done means a closed issue, a merged pull request or a completed Linear issue. Cancelled, duplicate and not-planned work doesn't count.
- Progress refreshes when you open the client (if it's older than five minutes), every 30 minutes, and when you press refresh.

When the work says so, Sydbar suggests **Looks started** or **Looks delivered** with the reason ("All 7 items done in Linear", "Milestone closed on GitHub"). You mark it, then invoice the milestone.

## Show it to the client

Each link has **Show progress on the client portal**, on by default. Clients see task titles and states, never links, comments or descriptions. Turn it off for internal repos.

## Send an email to Linear

Client feedback often belongs in Linear. In the conversation, the share icon → **Send to Linear** files it as an issue, in the client's linked project when there is one, with the email in the description and a link back to the conversation. Nothing is filed until you press **Create issue**.

## Cursor Origin

If your code is on Cursor's Origin with GitHub sync, link the GitHub repo Origin mirrors; progress is the same. Repos hosted only on Origin aren't supported yet.

## Troubleshooting

| Message | What to do |
| --- | --- |
| Repo not found, or the token can't see it | Check `owner/name`, and that the connection can see the repo. For organisation repos, an owner may need to approve Sydbar in the organisation's third-party access settings. |
| The token can't do that on this repo | Reconnect, or give the token Contents and Issues access (read and write). |
| Didn't accept the token / Needs reconnecting | The token was revoked or expired. Reconnect in Settings → Connections. |