Connect and Authenticate
Choose GitHub, GitHub Enterprise Server, GitLab, Jira, Linear or Beads, review repository routing, supply credentials or import a GitHub token from gh, and understand token permissions, validation, expiry and host-bound credentials.
Provider settings
Forge configuration lives in Settings > Code forge, under the Integrations group. A switcher at the top of the tab moves between General and one entry per registered provider. The built-in providers are GitHub and GitLab for code, issues and pull requests, and Jira, Linear and Beads for issues only. A fresh visit opens on the first provider rather than on General, because that is where a token goes.
GitHub, GitLab and Jira each draw their own settings section. A provider without one, such as Linear or Beads, gets a generic credential form built from the fields it declares, with a Provider group naming its plugin and the capabilities it supports.
General
General holds the provider routing for the active project and the forge audit log.
Provider routing opens with Default provider, which applies to every project without its own provider setting. The default choice, Auto-detect, picks the first installed provider whose hostname matches the remote. Each registered provider is listed below it with the hostnames it matches.
Under the default, a group named after the active project lists each of its git remotes with its fetch URL. The remote the project actually routes through carries an In use badge (In use · auto-detected when no forge remote is pinned). On the right of each row, Daintree states the outcome:
| Result | Meaning |
|---|---|
| GitHub or GitLab, by project setting | Resolved from this project's provider override. |
| A provider, by default provider | Resolved by your global default. |
| A provider, by hostname | Resolved by matching the remote's hostname. |
| No provider | Nothing resolves this remote. The line beneath reads Set one in Project settings, or Install a forge plugin when no provider is registered at all. Check the override and the global default first: a fail-closed explicit choice lands here too, not just an unknown hostname. |
| Couldn't resolve | The lookup itself failed, which is not the same answer as no match. A Retry row appears beneath the list. |
If you're ever unsure why a project is or isn't talking to a forge, this list is the place to check.
Forge audit log
Below the routing list, the Forge audit log keeps a record of each call Daintree makes to a forge provider (list, get, assign, validate and the rest), with arguments redacted. It keeps the last 500 calls on this machine. Record forge provider calls is on by default; turning it off stops new records, and the ones already kept stay until you clear them. The viewer beside it shows the records with refresh, export and clear controls, plus any anomaly signals. It's there for triaging a slow provider or a cluster of failures, not for everyday use.
Per-project override
To override forge behavior for a single project, open Project settings > Code forge (switch the Settings sidebar heading from Global to the project). The Remote and provider section holds three settings.
Forge remote selects which git remote Daintree uses for issues, pull requests, and pulse data. The default, Auto-detect, prefers origin, then any other remote a forge provider recognizes. The other options list each configured remote with its name and owner/repo label. Change this when origin points to a fork and you'd rather track the upstream repository. The setting is honored in toolbar issue and PR resolution as well as in worktree linkage.
Forge provider pins the project to a specific provider. The default, Auto-detect, uses the default provider from the global Code forge settings, then the remote's hostname. Set it explicitly when matching picks the wrong provider, or when a remote's hostname doesn't make the right provider obvious, as with a self-hosted GitLab.
Issues provider says where the project's issues come from. The default, Use forge provider, keeps them with the forge provider. Choose an issue tracker (Jira, Linear or Beads) to pair it with the forge: issues then come from the tracker, while pull requests and CI stay with the forge provider.
forgeRemote fails closed too. If the remote you named is later renamed or removed, the select shows it as (unavailable) and resolution reports the missing remote instead of quietly falling back to origin. Forge resolution backs mutations (assign, close, merge), so substituting a different repository for the one you named could redirect a write to a fork. A toolbar without issue and PR counts is a prompt to fix the setting; a write to the wrong repo is not recoverable.GitHub provider
Connecting GitHub takes a single personal access token, which you can paste or import from the GitHub CLI.
Personal access token
Open Settings > Code forge, switch to GitHub, and find the Authentication section. The token authenticates repository statistics, issue and PR detection, and linking worktrees to GitHub. Daintree keeps its own copy, so none of these features depend on the gh CLI.
A Status row reads Token saved for @your-login once a token is stored, and No token saved before that. Paste a token into the Personal access token field; the placeholder shows the two accepted formats, ghp_... or github_pat_.... Then:
- Test checks the token against GitHub without saving it, and reports that the token works but isn't saved yet.
- Save checks the token, stores it, and reports Checked and saved. The sidebar and toolbar refresh straight away, with no restart needed.
- Clear token, in the Stored token row, removes Daintree's copy after a confirmation. It only appears when a token is saved.
Tokens are stored locally in Daintree's settings, in plain text, keyed by provider in a forge credentials map rather than under a GitHub-specific key. Nothing is sent to Daintree. See Security & Privacy for the full storage model.
Importing the GitHub CLI's token
If the gh CLI is installed, the Get a token row offers Import from GitHub CLI. Click it and Daintree asks gh for the token it holds for github.com, checks it with GitHub, and shows a confirmation titled Import token for @your-login? before anything is saved. Reading that token can raise an OS keychain prompt, which is why Daintree never reads it until you click.
The confirmation lists the token's scopes, calls out any scopes beyond what Daintree uses (the copy keeps them all), warns when repo or read:org is missing, and notes when the import replaces a token you saved earlier. Import token saves Daintree's own plain-text copy; later changes to gh's login do not follow it. If gh isn't signed in, the row says to run gh auth login and try again.
Required scopes
The same row's Create token on GitHub button opens GitHub's token page with the right scopes preselected. A classic personal access token needs:
repo: access repository data (issues, PRs, statuses, and private repositories)read:org: read organization membership; organization access can also depend on token approval and SSO policy
For a fine-grained token, select the intended owner and repositories, then grant permissions for the features you use. Reading and writing issues requires Issues permission; PRs and reviews require Pull requests; repository content and merge operations can require Contents; status data may require Commit statuses, and individual check runs require Checks. Choose read access for browsing and write access only for operations you intend to perform. Metadata access alone does not grant access to private issue or PR data. Consult GitHub’s endpoint permission reference for each operation.
A successful token test verifies the token, not every repository permission or organization policy. Fine-grained tokens may need organization approval, and organizations can impose expiration limits. Follow GitHub’s token management guidance when selecting repositories, expiration and organization access.
This token authenticates Daintree’s forge API requests. Git fetch, pull and push use your Git transport credentials, such as an SSH key or credential helper. A working forge connection does not prove that Git can push to the remote.
GitHub Enterprise Server
Repositories on your company's GitHub Enterprise Server get the same pull request, issue and CI context as github.com ones, through the same GitHub provider. The server has its own host setting and its own token, which is only ever sent to that host.
- Open Settings > Code forge, switch to GitHub, and find the GitHub Enterprise Server section below Authentication.
- Enter the hostname your repositories are cloned from in Server host, such as
github.example.com, and press Save. A pastedhttps://address is accepted. A path, query or fragment, credentials, a port other than 443, another scheme, a leadingwww., andgithub.comor any of its subdomains are refused. - Once a host is saved, paste a personal access token into Personal access token for your host, then Test or Save. Both check the token against that server's API before anything is stored. Create token on your host opens the server's token page with
repoandread:orgpreselected.
If the GitHub CLI is signed in to the server, Import from GitHub CLI reads the token it holds for that host (gh auth token --hostname) and asks Import token for @your-login on your host before saving Daintree's own copy. If it isn't, the row tells you to run gh auth login --hostname with your host first.
A repository uses the server when its git remote's hostname matches the saved host exactly, for HTTPS, SSH and scp-style remotes alike. Only one Enterprise Server host can be set. Changing it leaves the old host's token unused: the Status row says there's no token for the new host until you add one. Clear token, in the Stored Enterprise Server token row, removes only the server's token; github.com's stays.
Cloning a repository from the server uses gh repo clone when the GitHub CLI is signed in to that host, and plain git with your own credentials otherwise.
Some GitHub surfaces still describe github.com only. The token-health and rate-limit notices are github.com's, and while github.com is rate-limited, GitHub list views and pull request polling pause for Enterprise Server projects too, until the reset. Issue and pull request tooltips check only the github.com token, so with only an Enterprise Server token they ask you to add one. Commit authors on the server get the fallback avatar. Daintree's queries use recent schema fields, such as merge queue status, that an older server may not have.
GitLab provider
GitLab connects with a personal access token for one GitLab instance: gitlab.com by default, or your own server.
- Open Settings > Code forge and switch to GitLab.
- For a self-hosted server, set Instance URL to its base URL, including any port or path prefix. Leave it at
https://gitlab.comotherwise. - Click Create token on GitLab. It opens your instance's access-token page with the token named Daintree and the
apiscope preselected.read_apiis enough if you only want to read. - Paste the token (the default GitLab prefix is
glpat-) into Personal access token, then Test or Save. The Status row then reads Token saved for followed by the instance's host.
GitLab documents read_api for read access and api for read and write access. Instance policies can control token lifetimes and prefixes. See GitLab's token scopes and personal access token guidance.
Validation reports what went wrong in specific terms: the instance rejected the token (401), the token lacks API access because it has neither api nor read_api, the host couldn't be reached, or the host didn't answer like a GitLab instance.
A GitLab token is tied to the instance it was checked against, and Daintree never sends it to another host. Changing Instance URL while a token is saved doesn't switch anything on its own: the next Save or Test asks Switch to the new host first, and confirming removes the saved token, because it only works on the old instance.
gitlab.com and a few well-known public instances match by hostname. For a project whose remote points anywhere else, set Forge provider to GitLab under Project settings > Code forge. The routing list under General confirms the result.Jira provider
Jira is an issues provider. It connects to Jira Cloud or to your own Jira Server or Data Center, and a project pairs it with its code forge, which keeps pull requests and CI.
- Jira ships turned off, like Linear and Beads, so the Code forge switcher doesn't list it yet. Enable it in the Plugin Manager first.
- Open Settings > Code forge and switch to Jira.
- Under Jira, choose Jira Cloud or Server or Data Center, then fill in the fields for that choice (below).
- Press Save. Everything is checked against Jira together before it's saved, and Signed in as your name appears beside the button. There's no separate test.
- For each project whose issues live in Jira, open Project settings > Code forge and set Issues provider to Jira.
- Give the project its Jira project key, the prefix of its issue keys (
ENGforENG-123). Settings has no field for it yet: it's the Jira plugin'sprojectKeyproject setting, kept in the repository at.daintree/plugin-settings/daintree.jira.json, for example{"projectKey": "ENG"}. Without it, Jira lists no issues for the project.
Jira Cloud
- Site URL: your
atlassian.netaddress, such ashttps://acme.atlassian.net. - Account email: the Atlassian account the token belongs to.
- API token: Create token on Atlassian opens Atlassian's token page. Choose Create API token: tokens with scopes don't work with a site URL.
A Cloud API token belongs to your Atlassian account, so Daintree sends it only to atlassian.net sites.
Jira Server or Data Center
- Site URL: the address you open Jira at, over HTTPS, including any port and path, such as
https://jira.example.comorhttps://example.com:8443/jira. A pasted issue or project page address is trimmed back to the site. Anatlassian.netaddress is refused here; choose Jira Cloud for it. - Personal access token: in Jira, open your profile, choose Personal Access Tokens and create one. There's no email field.
Jira 8.14 or later is required, the release that added personal access tokens. Saving first asks the server, without the token, which deployment and version it is, so a custom domain in front of Jira Cloud that says it's Cloud never sees the token. If that anonymous request gets HTTP 401 or 403, Daintree asks again with the token, before it knows which deployment the server is. It then checks the token by reading your account.
The token is bound to the exact site it was saved for and is never sent anywhere else, so changing the site means entering the token again. Requests go through Chromium's network stack, so certificates are checked against your operating system's trust store: a server behind a company certificate authority that this computer trusts works. There's no option to ignore certificate errors. An untrusted one fails with Couldn't reach Jira: this computer doesn't trust its certificate.
On Server and Data Center, Assign to me assigns by your Jira username rather than an account id. For every Jira deployment, creating, closing, editing, commenting on and labeling issues happen in Jira itself; Daintree says so if you try.
Linear provider
Linear is an issues provider. A project reads the issues of one Linear team and pairs them with its code forge, which keeps pull requests and CI.
- Linear ships turned off, so the Code forge switcher doesn't list it yet. Enable it in the Plugin Manager first.
- Open Settings > Code forge and switch to Linear.
- Paste a Linear personal API key (it starts
lin_api_) into Personal API key. Create one in Linear under Settings > Security & access > Personal API keys. - Press Save. Daintree checks the key by reading your Linear user before storing it and reports Checked and saved. The Status row then reads Credentials saved.
- For each project whose issues live in Linear, open Project settings > Code forge and set Issues provider to Linear.
- Give the project its Linear team key, the prefix of the team's issue IDs (
ENGforENG-123). Open Project settings > Plugins, pick Linear, and fill in Linear team key. It's saved in the repository at.daintree/plugin-settings/daintree.linear.json. Without it, Daintree reports that Linear isn't set up for this project yet.
Linear connects with a personal API key only; there's no OAuth sign-in. One saved key serves every project, stored with the other forge credentials, and Daintree sends it only to Linear's API at api.linear.app.
Teams and issues
Each project reads one team, in the workspace the API key belongs to. The team key is trimmed and uppercased; it must start with a letter and contain only letters, digits and underscores, up to 16 characters. A key that no team in the workspace has fails with an error naming it and pointing back at Project settings.
- Open issues are those whose workflow state isn't of Linear's completed, canceled or duplicate type, so backlog and triage issues count as open. Closed is those three types.
- Search matches text in the title, or an issue number in the team:
42,#42orENG-42. Another team's key, such asDES-42, matches by title only. - Linear lists newest first, by creation or by last update. A request for any other order, such as an agent asking for oldest first, is refused rather than answered in a different order.
The toolbar's issues count is the team's open issues. Clicking it, or View all issues on Linear in its right-click menu, opens the team's issue list on linear.app in your browser; there's no in-app issues panel for Linear. Linear doesn't report totals, so Daintree counts by paging through the open issues: past 2,000, the count reads as unknown. Daintree reuses a count for up to five minutes.
Linear issues on worktrees
- Creating a worktree: the Issue row in the Create worktree dialog lists the team's issues. If you haven't edited the branch field, picking one fills in the branch name Linear suggests for that issue, as is, without
feature/or your configured branch prefix, so Linear can recognize the branch. When Linear has no suggestion or the name fails Daintree's branch-name check, Daintree generates its own instead. - Branch detection: while Linear is the project's issues provider, a branch containing the team key and a number as a whole token, in any case (
eng-42-fix-login,jo/ENG-42-fix), links to that Linear issue. The worktree's folder name is checked when the branch has no match, and long-lived branches such asmainorrelease/…are skipped. This runs before the built-in patterns, soeng-42-fix-gh-7isENG-42. For any other worktree, use Attach issue. - On the card: the issue badge, the Open issue menu item and Review Hub show the Linear key (
ENG-42), and opening the issue goes to its Linear page. In a recipe prompt,{{issue_number}}and{{number}}give the key too. - Assigning yourself while creating the worktree assigns the issue to the user who owns the API key, replacing any current assignee, since a Linear issue has one. Undo puts back whoever had it before, or no one, and leaves the issue alone if someone else has taken it since. Daintree only ever assigns you; assigning anyone else is refused.
What Linear doesn't do in Daintree
Assigning yourself and unassigning yourself are the only writes. Create, close, reopen, edit, comment on and label issues in Linear itself: a forge.* action that tries one is refused with a message to do it in Linear instead. Daintree doesn't read Linear comment threads. A project reads one team; issues from the workspace's other teams don't appear. When Linear's rate limit is reached, requests fail with Linear's rate limit was reached. Try again shortly.
Beads provider
Beads is an issues provider for a Beads (bd) workspace. Daintree doesn't run the bd CLI or open the .beads database itself: it reads and writes beads through a bd serve server over HTTP. The project's code forge keeps pull requests and CI.
- Beads ships turned off, so the Code forge switcher doesn't list it yet. Enable it in the Plugin Manager first.
- Have
bd serverunning for the workspace, where the machine running the project can reach it. It picks an ephemeral port by default, so give it a fixed one if you enter the address yourself. - For each project whose issues live in Beads, open Project settings > Code forge and set Issues provider to Beads.
- Tell the project where the server is. Open Project settings > Plugins, pick Beads, and fill in Beads server URL with the address
bd servelistens on. It's saved in the repository at.daintree/plugin-settings/daintree.beads.json. Leave it empty to use the addressbd connectrecorded in the project's.beads/http_target.json. With neither, Daintree reports that Beads isn't set up for this project yet. - If the server was started with
--auth-token-file, open Settings > Code forge, switch to Beads, paste a token from that file into Server token, and press Save. A server started without one needs no token.
Server address and token
The server URL must be an http or https address. A path is kept, for a server behind a proxy mount; an address carrying a user name, password, query string or fragment isn't usable. If the setting is filled in but isn't usable, Daintree reports the error rather than falling back to .beads/http_target.json, so a typo can't point the project at a different server.
There's one Beads token for all projects, while each project names its own server, so Save can't try the token against a server. It checks only that the token isn't empty and contains no whitespace or control characters, and Checked and saved means no more than that. The server judges it on the project's first request, and a rejected token reads The Beads server rejected the token.
The token goes to loopback addresses (localhost, 127.x.x.x, ::1 or a .localhost name) and to addresses read from any project's Beads server URL setting, which Daintree keeps trusting while the plugin runs. That setting is a file in the repository, so check it in a repository you cloned before relying on a saved token. An address that comes only from .beads/http_target.json and points anywhere else gets no token, because a cloned repository can name any server. If that server needs a token, the error says to enter its address as Beads server URL in Project settings.
- Daintree doesn't follow redirects from the server, so the token can't be forwarded to another host.
- A server that refuses the address it's reached at fails with a message to start
bd servewith--allowed-hostfor it. - When the server reports which workspace it serves, Daintree sends that workspace's id with later requests. If a different workspace now answers at the same address, the request is refused with a message that the server now serves a different workspace, and Daintree forgets what it learned about that address, so trying again connects to the new workspace.
Beads issues
- Open is the set
bd listshows by default, which leaves out closed beads and the workspace's custom done and frozen statuses. Closed is beads with theclosedstatus, and All is every status. - Search is passed to the server. Lists come newest first by creation only; a request for another order is refused.
- Beads ids have no issue number. Daintree shows the bead id wherever an issue key appears (the picker, the worktree card, menus and Review Hub), and
{{issue_number}}and{{number}}in a recipe prompt give the bead id. bd servehas no web pages, so commands that open an issue or the issue list in your browser have nothing to open.
The toolbar's issues count pages through the open set, up to 1,000 beads; past that, it reads as unknown. Daintree reuses a count for up to five minutes.
Beads issues on worktrees
- Creating a worktree: the Issue row in the Create worktree dialog lists the project's beads. If you haven't edited the branch field, picking one names the branch
bead/followed by the bead id, as is, without your configured branch prefix. If that name fails Daintree's branch-name check, Daintree generates its own instead. - No branch detection: Beads doesn't claim branch names, so a worktree created outside Daintree isn't linked to a bead by its branch. Link it with Attach issue.
- Assigning yourself while creating the worktree assigns the bead to your Beads actor, the name
bditself would record, looked up on the machine running the project: theBEADS_ACTORorBD_ACTORenvironment variable, then your global gituser.name, then your operating-system user name, anddaintreeas a last resort. If someone else holds the bead, Daintree doesn't force it; the server decides whether to refuse. Undo puts back whoever had it before, or no one, as long as the bead is still yours.
Writes
Unlike Jira and Linear, Beads accepts issue writes through the forge.* actions: creating a bead (as a task at priority 2), closing it with an optional reason, reopening it, editing its title and description, posting a comment, and adding or removing labels. Daintree sends your Beads actor with each write. These actions address an existing bead by the number Daintree derives from its id, the one forge.listIssues returns, rather than by the id itself. Reading a bead's comment thread isn't supported.
Token resilience and rate limits
When the connection to the forge fails, the integration degrades rather than breaking.
When a stored token stops working, a callout drops from the issues count in the toolbar. Its title names the problem: GitHub token expired for a revoked or expired token, GitHub token is missing permissions for an under-scoped one, or GitHub token needs SSO authorization when an organization's SSO blocks it (GitLab tokens get the same callout under GitLab's name). Reconnect to GitHub takes you to the provider's section of Settings > Code forge, and an SSO block adds Open reauthorization page. You can dismiss the callout; it returns only if a different token fails. A project with no token at all gets no callout: the counts' tooltips invite you to configure one instead.
Saving or clearing a credential re-checks the provider's token health right away, so the callout clears as soon as the provider accepts the new token.
Inside the GitHub issues and pull requests panel, a token error shows its own message with a button into settings, and the panel keeps showing the last results it fetched in the meantime. See When the forge is unreachable.
For transient network errors, the toolbar's polling retries in the background with backoff: the first failure retries after 30 seconds, doubling toward a two-minute ceiling. Retrying wouldn't help a rate limit, so that is waited out against its reset time instead.