Providers overview

Birch connects to six providers. Three are full git hosts — GitHub, GitLab, and Azure DevOps give you pull requests and issues — and three are issue trackers only: Jira, Linear, and YouTrack feed your Inbox with assigned tasks. All use personal tokens stored in your OS keychain, all support multiple accounts, and all but Linear work self-hosted.

Capability matrix

Provider	Pull requests	Tasks in the Inbox	Self-hosted
GitHub	Yes	Assigned issues	GitHub Enterprise Server
GitLab	Yes (merge requests)	Assigned issues	Self-managed GitLab
Azure DevOps	Yes	Assigned work items	Azure DevOps Server
Jira	No	Assigned issues	Jira Server / Data Center
Linear	No	Assigned issues	No — cloud only
YouTrack	No	Assigned issues	YouTrack Server

The three git hosts drive everything PR-related: the PR lists on the repository page, the workspace PR card, creating and managing pull requests, and AI code review. The three trackers only feed tasks — they have no pull requests and no git remotes, so Birch never tries to match them to a repository.

Cloud and self-hosted

Every connect form except Linear’s takes an instance URL:

• GitHub — leave the base URL empty for github.com; for GitHub Enterprise Server enter the API root, https://<host>/api/v3.
• GitLab — leave the base URL empty for gitlab.com; for self-managed GitLab enter your instance’s root URL.
• Azure DevOps — the URL is always required: https://dev.azure.com/your-org, or your collection URL on Azure DevOps Server.
• Jira — the site URL is always required: https://your-domain.atlassian.net for Cloud, or your self-hosted Jira URL. Birch detects Cloud vs Server/Data Center automatically — see Jira.
• YouTrack — the base URL is always required and is stored exactly as you type it, including a context path like /youtrack. One code path serves Cloud and Server alike.
• Linear — there is no URL field. Linear is cloud-only.

How authentication works

Open Settings → Integrations (⌘, / Ctrl+,), click a provider tile, and the connect form expands below the tiles. Every provider authenticates with a personal token — there is no OAuth sign-in flow:

1. Check the form’s Token permissions list, then click its Create … link. It opens the provider’s token page in your browser, and it honors the self-hosted URL you typed — for example, a GitHub Enterprise base URL sends you to that instance’s token settings, not to github.com. The GitHub and GitLab links open with the listed scopes already ticked.
2. Paste the token (plus the provider’s other fields) and click Verify & connect. Birch verifies the credential against the provider before storing anything — a bad token is rejected on the spot.
3. On success the account appears above the form with a Connected badge, its base URL, and a Verified: timestamp, plus Sync now and Remove buttons.

As the pane itself says: “Tokens are stored in the system keychain and used only for API calls (pull requests, reviews, Inbox sync), never for git push or pull.” Tokens live in your OS credential store, not in Birch’s database.

You can connect multiple accounts per provider — the connect form stays available after the first account, so a work and a personal GitHub account (or two Jira sites) coexist fine.

Note

The Integrations pane applies account changes immediately — Verify & connect is the save, and as the pane says, “Account actions apply immediately and cannot be undone with Cancel.” The window’s Save changes button doesn’t submit a token you typed but never verified; it is discarded when the window closes.

Provider tokens are a separate system from the git credentials used for push and pull over HTTPS/SSH — those live in Settings → Git → Credentials. See Git credentials.

Token permissions

Every connect form lists the permissions its provider’s token needs for every Birch feature to work — Inbox feeds, PR create / merge / close / draft / review, CI checks, issue status changes, and task images. In short:

Provider	Grant
GitHub	Classic token (recommended): repo, plus project (optional) for issue Status. Or a fine-grained token with Contents and Pull requests read and write — it can’t show GitHub Actions check runs
GitLab	api — read_api can’t write
Azure DevOps	Custom defined: Code (Read & write), Work Items (Read & write), Project and Team (Read)
Jira	Cloud: an API token made with Create API token, not with scopes. Server / Data Center 8.14+: a PAT. Your account needs Browse projects and Transition issues
Linear	Full access, or Read + Write; All teams or the teams you work in
YouTrack	Permanent token with the YouTrack scope; your account needs Read Issue and Update Issue

Verify & connect only checks whose token it is, on every provider. A token missing a scope connects fine and then quietly misses private data or fails a write — so grant the whole list, not just what connects.

When GitHub, GitLab or Azure DevOps refuses a pull request write — create, merge, close or reopen, draft, or review — the error keeps the host’s own reason and adds what to check, pointing at Settings > Integrations: on GitHub and GitLab a 401 says the token may have expired or been revoked and a 403 names the missing scope; Azure DevOps names both causes in one hint. Each provider page quotes its exact wording.

What syncs, and when

Birch’s background sync talks to your connected accounts roughly every 10 minutes (with a little jitter to spread requests out). Each cycle refreshes:

• pull request state for your repositories, including checks,
• review-requested PRs and activity on your own PRs, into the Inbox,
• PR comments,
• your assigned issues and work items, into the Inbox Tasks tab — including images from their descriptions, downloaded as thumbnails.

PR state also syncs once shortly after the app starts, so you are not waiting ten minutes after launch. Outside the schedule you can force a refresh with the per-account Sync now button in the Integrations pane, and entering a workspace refreshes that branch’s PR chip on the spot.

If automatic AI review is enabled, newly synced PRs can be reviewed as they arrive — an Anthropic API feature. Sync activity can also raise desktop, sound, and Teams notifications — see Notifications.

Issue status transitions

When you start a workspace from a tracker task — and again when you create a PR from that workspace — Birch can move the issue through your workflow. The first time, an Update task status? dialog shows the issue, its current status, and a Move to picker; choose a status and click Change status, or Skip. Ticking Remember and don’t ask again makes Birch apply that same status automatically next time.

Settings → Task automation holds the per-account configuration: one row per tracker account and surface (workspace launch, PR created), each with a mode:

Mode	Behavior
Ask each time	Show the status dialog (the default)
Change automatically	Apply the remembered status silently — offered only once a status has been remembered
Never offer	Do nothing, and stop asking

Each row shows its Remembered status: and a Reset button. The dialog’s “Don’t offer this anymore” link is a shortcut to Never offer.

What a “status” is depends on the provider: Jira offers its workflow transitions, Linear its workflow states, and YouTrack the values of its State field. On the git hosts: GitHub offers the Status field of the Projects v2 boards the issue is on (GitHub has no workflow on the issue itself), GitLab offers its Work Item statuses (a Premium/Ultimate feature on GitLab 18.4+ — on other instances no statuses are offered), and Azure DevOps offers the work item type’s own states.

Issue-only providers and the repository picker

Jira, Linear, and YouTrack tasks carry no repository information Birch could match to a local clone — their URLs point at a tracker site, not a git remote. So when you click Start workspace on one of those tasks, Birch opens the Choose Repository dialog and asks you where the work should happen. That is the designed flow, not an error. See Start a workspace from a task.

Their issue identifiers (PROJ-123, ENG-123) are not numbers, so Birch labels tasks and status prompts with the identifier itself rather than a #123-style number.

Removing an account

Click Remove on the account’s row in the Integrations pane. The account disappears from the pane and from Birch’s account pickers, and background syncing for it stops. To reconnect later, add the account again with a fresh token.