Connect and Authenticate
Connecting Daintree to a code forge: choosing a provider, the global and per-project settings, the GitHub token scopes that are actually required, credential validation, and what happens when a token expires or you hit a rate limit.
Provider settings
Forge configuration lives in Settings > Code Forge. A dropdown at the top of the tab switches between sections: General, and one section per registered provider. Each provider section renders a credential form built from the fields that provider declares.
General
The General section holds the global default, a view of how the current project resolves, and the forge audit log.
Default forge provider sets the provider used for newly opened projects. The default option is No global default (auto-detect from hostname), which leaves hostname matching in charge. Each registered provider appears below it, showing the hostnames it matches.
Active project routing lists the current project's git remotes and shows, for each one, which provider it resolves to and why. Each row carries a badge:
| Badge | Meaning |
|---|---|
| Override | Resolved from this project's provider override. |
| Default | Resolved by your global default provider. |
| Hostname | Resolved by matching the remote's hostname. |
| No match | No provider resolves this remote. Check the override and the global default first: a fail-closed explicit choice lands here too, not just an unknown hostname. |
If you're ever unsure why a project is or isn't talking to a forge, this table is the place to check.
Forge audit log
Below the routing table, Record forge provider calls appends a record each time a forge provider method is invoked (list, get, assign, validate) with redacted argument summaries. The viewer beside it shows the records, with copy, export and clear controls, plus an anomaly snapshot. It's there for triaging a slow provider or a cluster of failures, not for everyday use, and it's off unless you turn it on.
Per-project override
To override forge behavior for a single project, open Project Settings and go to the Code Forge tab. Two settings live here.
Forge remote selects which git remote Daintree uses for issues, PRs, and pulse data. The default, Auto-detect (origin), keeps the standard behavior: Daintree prefers remotes a registered provider can actually parse, ranked by name preference then git's own listing order. 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, leaves provider selection to the global default and hostname matching. Set it explicitly when matching picks the wrong provider, or when a remote's hostname doesn't make the right provider obvious.
forgeRemote fails closed too. If the remote you named is later renamed or removed, 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 dark toolbar is a prompt to fix the setting; a write to the wrong repo is not recoverable.GitHub provider
The GitHub provider is the one that ships with Daintree. Connecting it takes a single personal access token.
Personal access token
Open Settings > Code Forge, select GitHub, and find the Personal access token block. The token covers repository statistics, issue and PR detection, and linking worktrees to issues and PRs. It also means you don't need the gh CLI configured for any of these features.
Paste a token into the field. The placeholder shows the two accepted formats, ghp_... or github_pat_.... Use the buttons beside it:
- Test validates the token against GitHub without saving it. It reports Token valid, click Save to store it so you can confirm before storing.
- Save stores the token and reports Token saved. The sidebar and toolbar refresh as soon as it's accepted, with no restart needed.
- Clear token removes a stored token. It only appears when one is saved.
Tokens are stored locally in Daintree's config, keyed by provider in a forge credentials map rather than under a GitHub-specific key. A green GitHub connected indicator confirms a working token. Nothing is sent to Daintree. See Security & Privacy for the full storage model.
Required scopes
A second block, Create a new token, has a Create Token on GitHub button that opens GitHub's token page with the right scopes prefilled. A classic personal access token needs:
repo: access repository data (issues, PRs, statuses, and private repositories)read:org: read organization membership, required for private repos owned by an org
read:org. Fine-grained tokens also cap out at a one-year lifespan, so they need renewing on a schedule.Token resilience and rate limits
When the connection to the forge fails, the integration degrades rather than breaking.
When your token expires or is revoked, a banner appears reading GitHub token expired with the line Reconnect to restore issue, PR, and repository data and a Reconnect to GitHub button, which takes you to Settings > Code Forge > GitHub. Personal access tokens expire on a schedule; Daintree surfaces that clearly instead of quietly failing to fetch.
Inside the issues and PR panel, a token error shows its own inline banner with a Settings button that opens the same place. The panel keeps showing the last results it fetched in the meantime.
For transient network errors, Daintree retries quietly in the background with exponential backoff. Token and rate-limit errors aren't retried this way, since retrying wouldn't help: a rate limit is waited out against its reset time instead.